• New functionrenameGear() to rename gears in a MizerParams object, similar
  torenameSpecies().
• addSpecies() now proceeds with a warning instead of an error when species
  growth stops after maturity (#315).
• matchBiomasses() andmatchNumbers() now provide more informative error
  messages.
• plotDiet() now restricts the plot to size ranges with meaningful biomass
  density (#317).
• Thewlim andylim arguments in plotting functions now set the actual axis
  limits instead of just zooming (#320).
• The legend inplotlyFeedingLevel() is improved when critical feeding level
  is included.
• species andgears columns are now never factors, so no longer need to
  callas.character() so often.
• validParams() also callsvalidGearParams().
• validParams() checks thatw_min is valid for all species and increases it
  if necessary.
• validSpeciesParams() now also sets default forp to be equal ton.
• species_params<-() andgiven_species_params<-() now check that species
  names match.
• Theparams argument inl2w() andw2l() has been renamed tospecies_params
  to follow mizer's convention thatparams refers to a MizerParams object.

Bug fixes

• animateSpectra() now uses consistent colours and preserves colour identity
  across frames (#321).
• getReproductionProportion() no longer returns incorrect proportions > 1 (#299)
• setResource() now correctly applies thew_pp_cutoff parameter to the
  carrying capacity and initial resource abundance when changed without
  providingresource_capacity(#306).
• Predation kernels are now truncated as documented.
• given_species_params() no longer makes unwanted changes to the species
  parameters.
• steadySingleSpecies() no longer changestime_modified.

Full Changelog:v2.5.3...v2.5.4

This is a patch release with many small fixes and improvements since the v2.5.0 release.

• validSpeciesParams() has extra checks on consistency of species parameters.
• validParams() checks that rate arrays contain finite numeric values.
• validSim() checks that simulation results are finite and truncates the
  simulation if they are not.
• Fixed bug that had lednewCommunityParams() to set up resource parameters
  differently since version 2.4.0 (#293).
• addSpecies() now correctly preserves allspecies_params of the existing
  model.
• addSpecies() no longer requires new species to grow to maximum size, only
  maturity size is required.
• NowvalidGivenSpeciesParams() validates the given species parameters without
  adding defaults andvalidSpeciesParams() validates and returns a completed
  species parameter dataframe.
• New species parameterw_repro_max giving the size at which a species
  invests 100% of its energy into reproduction. Set tow_max by default.
• removeSpecies() now also removes species parameters that are NA for
  all of the remaining species.
• Changingw_max now also correctly updatesft_mask (#296).
• compareParams() now also spells out differences in given species parameters.
• getDiet() now also includes the contribution of the external encounter rate
  to the diet.
• setPredKernel() now throws an error if some of the required predation kernel
  parameters are NA.
• InplotYieldGear() one can select a subset of gears with a newgears
  argument.
• New helper functionvalid_gears_arg() to check thegears argument in
  functions that take agears argument.
• Improved scaling of the y-axis inplotGrowthCurves().
• steadySingleSpecies() no longer requires species to grow tow_max.
• matchGrowth() now also rescales the external encounter rate.
• setExtEncounter() no longer resets the external encounter rate to zero when
  called without theext_encounter argument.
• The functionplotBiomassObservedVsModel() now plots the ratio of modelled
  to observed biomass as default (ratio = TRUE).
• Thetime_modified field is now updated correctly bysteadySingleSpecies(),
  setColours() andsetLinetypes().
• DeprecatedmatchYields() andcalibrateYield().
• project() andprojectToSteady(..., return_sim = TRUE) now correctly
  returns also the other components of the MizerSim object stored inn_other.
  #285
• Improved some unit tests.
• Some improvements to documentation.

This release introduces a change that requires you to upgrade your old
MizerParams and MizerSim objects withupgradeParams() orupgradeSim().

External encounter rate

Now the model can include an external encounter rate that represents the
rate at which a predator encounters food that is not explicitly modelled.
This encounter rate is set withsetExtEncounter() orext_encounter<-()
and can be read withgetExtEncounter() orext_encounter(). So this is
similar to how external mortality is handled.

Given versus calculated species parameters

You can now usegiven_species_params() to see the species parameter
values that you have explicitly specified andcalculated_species_params()
to see the species parameter values that mizer has calculated automatically or
set to defaults. You can continue to usespecies_params() to get all
species parameters, irrespective of whether they were given or calculated.

You can still set parameter values withspecies_params<-(), but you can also
use the strongergiven_species_params<-() which not only sets the values you
give but also triggers a re-calculation of the calculated species parameters.
Usinggiven_species_params<-() is therefore usually the better option.

New mizer course

There is now a three-part mizer course athttps://mizer.course.sizespectrum.org
with each part consisting of several tutorials, including code and exercises:

• Part 1: Understand
  You will gain an understanding of size spectra and their dynamics by exploring simple example systems hands-on with mizer.

• Part 2: Build
  You will build your own multi-species mizer model for the Celtic sea, following our example. You can also create a model for your own area of interest.

• Part 3: Use
  You will explore the effects of changes in fishing and changes in resource dynamics on the fish community and the fisheries yield. You will run your own model scenarios.

Other improvements

• Warnings are given if user gives irrelevant species parameter values.
• Some messages have been converted to warnings and some to signals that are not
  shown as frequently.
• Frequent warnings are avoided when length-based and weight-based parameters
  are both given and are inconsistent.#277
• Documentation ofeffort argument inproject() is improved.
• An error message is given if a predation kernel returns negative values or
  is everywhere zero.#283

Bug fixes

• When the coefficienth of the maximum intake rate is not given, it is now
  again given a default value.#282
• matchGrowth() no longer gives an error when there is now_inf column.#279

This release introduces a change that requires you to upgrade your old
MizerParams and MizerSim objects withupgradeParams() orupgradeSim():

Avoid confusion between maximum size and von Bertalanffy asymptotic size

For an explanation see blog post at
https://blog.mizer.sizespectrum.org/posts/2022-11-30-dont-use-von-bertalanffy-growth-parameters/

The species parameter that specifies the size at which also the largest fish stop
growing is renamed fromw_inf tow_max. The parameterw_inf is now
reserved for the von Bertalanffy asymptotic size parameter. If you upgrade
your existing MizerParams object withupgradeParams() thew_inf column is
copied over to thew_max column automatically, but you may want to change
the values yourself if they do not currently reflect the maximum size of the
species. Otherwise the size distributions predicted by mizer will not match
observations.

Set resource abundance rather than carrying capacity

The resource parameterskappa andlambda are now used to set the abundance
of the resource in the steady state rather than the carrying capacity, because
the latter is not observable.

While tuning the steady state using thesteady() function the resource
abundance is now being kept fixed at the chosen value. Then the resource
dynamics can be switched on later withsetResource() without changing the
steady state. At that stage you only choose either the resource intrinsic
growth rate or the resource carrying capacity and the other is determined by
setResource() in such a way that the resource replenishes at the same rate at
which it is consumed. If you want to keep the old behaviour and switch off this
automatic balancing you have to add thebalance = FALSE argument when calling
setResource().

You can also choose between semichemostat dynamicsresource_semichemostat()
or logistic dynamicsresource_logistic() or you can write your own function
implementing more sophisticated resource dynamics.

ThesetParams() function no longer includes the arguments for setting the
resource parameters. Instead you set these separately withsetResource().

Automatically match growth rates

As explained in the blog post athttps://blog.mizer.sizespectrum.org/posts/2022-11-30-dont-use-von-bertalanffy-growth-parameters/,
the von Bertalanffy curves fitted to size-at-age
data are not suitable for estimating the size-dependent growth rates in mizer.
It is therefore now recommended that instead of von Bertalanffy parameters you
supply the age at maturity in theage_mat column of the species parameter
data frame. This is then used by mizer to calculate a default for the
maximum intake rate parameterh if you do not supply this.

In the past, whenever you changed any model parameters, you needed to re-tune
other parameters to keep the growth rates in line with observations. There is
now a new functionmatchGrowth() that automatically scales the search volume,
the maximum consumption rate and the metabolic rate all by the same factor in
order to achieve a growth rate that allows individuals to reach their maturity
size by their maturity age while keeping the feeding level and the critical
feeding level unchanged. This function does not however preserve the steady
state, so you will need to also callsteady() after matching the growth rates.

Other improvements

• New functionsteadySingleSpecies() that only balances the size-spectrum
  dynamics while ignoring multi-species effects. In other words, it calculates
  the steady-state size spectrum of each species as it would be if the abundance
  of prey and predators could be kept constant at their current values.
• plotGrowthCurves() can now superimpose a scatterplot of size-at-age data
  if you supply this via the newsize_at_age argument.
• New functionscalibrateNumber() andmatchNumbers() that are like
  calibrateBiomass() andmatchBiomasses() but work with observed numbers
  instead of observed biomasses.
• New functionage_mat() to calculate the age at maturity from the growth
  rate and the size at maturity.
• If an effort vector or effort array contains NA's, these are now replaced by
  the default effort value.#230
• The entries of the interaction matrix and of interaction_resource are no
  longer restricted to be less or equal to 1.#232
• If user supplies no row names in the interaction matrix but gives column names
  then the column names are also used as row names.#247
• project() now also works when called with a MizerSim object with additional
  components.
• steady() now preserves the RDD function in the MizerParams object rather
  than always setting it to "BevertonHoltRDD".
• When averaging abundances over time inplotSpectra() orsetInitialValues()
  the user can now choose geometric averaging withgeometric_mean = TRUE.
• Thew_mat25 species parameter is no longer filled in automatically if it is
  not supplied. This makes it easier to changew_mat without having to change
  w_mat25 at the same time.
• compareParams() now also checks the validity of its second argument.
• Hide the printing of messages about chosen defaults innewTraitParams().
• Higher values for theinfo_level argument innewMultispeciesParams() now
  leads to more messages.
• Giving more helpful messages invalidSpeciesParams().#136
• New helper functionsl2w() andw2l() for converting between length-based
  and weight-based species parameters.#258
• Check that assessor functions for MizerSim slots are called with a MizerSim
  object.
• Addstyle argument toplotDataFrame() to facilitate producing area plots.
• Addwrap_scale argument toplotDataFrame() to control scaling of axes in
  faceted plots.
• plotDiet() can now show diets of several predator species in a faceted
  plot.#267
• Change fromsize tolinewidth aesthetic to avoid warnings in new version
  of ggplot2.
• Better error message when functions are called with no valid species selected.
  #251
• If there are no differences thencompareParams() says so clearly.
• getReproductionLevel() works as long asR_max is set.#252
• Converted several unit tests to edition 3 of testthat package.
• Improved documentation forgear_params().
• Improved defaults can now be implemented while keeping backwards compatibility
  viadefaults_edition().#186
• New defaults edition 2: catchability = 0.3 instead of 1, initial effort = 1
  instead of 0.#243
• In defaults edition 2,get_gamma_default() ensures a feeding level off0
  for larvae also ifinteraction_resource is not equal to 1.#238
• Set default linecolour and linetype for external mortality.

Bug fixes

• Restored the line colours toNS_params
• Comment field now preserved byset_species_default().#268
• Comment onw_inf no longer leads to error inplyr::aaply().#269
• Can now again seturl field in metadata.
• Correct species now listed in the legend ofplotYieldObservedVsModel() and
  plotBiomassObservedVsModel().#266
• Standard order for legend inplotDiet() restored after change toggplot2
  package.#265
• Fix handling of column names when interaction matrix is read from .csv file.
  #263

• Resolved conflict inmizerPredRate() between the argumentt and the
  functionbase::t().
• Assert that upgradeParams() must be called with a MizerParams object and
  upgradeSim() with a MizerSim object.
• Errors changed to warnings ingetRequiredRDD()
• renameSpecies() no longer fails when linecolour and linetype are of
  different lengths.
• matchYields() now also works for a model with only a single species.
• setInitialValues() can now average over a time_range.
• getSSB(),getBiomass(),getN(),getYieldGear() andgetYield()
  can now be called with a MizerParams object as well as with a MizerSim
  object. (#200)
• Updated the shiny app in inst/shiny/selectivity_effects to current mizer
  version.

New features

• New plotsplotBiomassObservedVsModel() andplotYieldObservedVsModel()
  contributed by@SamikDatta., together with their plotly counterparts.
• NewcalibrateBiomass(),calibrateYield() to set the model scale to agree
  with total observed biomass or total observed yield. Uses the new
  scaleModel().
• NewmatchBiomasses() andmatchYields() will try to adjust the abundances
  of the species to produce the observed biomasses or yields.
  See blog post athttps://bit.ly/2YqXESV .
• There are now accessor and replacement functions for rates. So for example
  instead ofparams <- setReproduction(params, maturity = my_maturity) one
  can simply usematurity(params) <- my_maturity. These are documented
  together with the setter functions.#213
• NewsetMetadata() to add information to a MizerParams object describing
  the model, for example a title, a description, the author or list of
  authors, a url and a doi. This will be particularly useful for sharing your
  models with others
• NewsaveParams() for saving a MizerParams object to a file and
  readParams() for reading it back in. The resulting files can be shared
  with others who want to run your model.
• A MizerParams object now registers the mizer version under which the model was
  last saved. Should the model not be working as expected in the current version
  of mizer, you can go back to the older version under which presumably it was
  working. This helps with the reproducibility of your research.
• A MizerParams object registers the time when it was created and the time it
  was last modified. SeegetMetadata(). This helps you keep track of
  different versions of your model.
• steady() now has apreserve argument with possible valueserepro,
  R_max orreproduction_level to specify which quantity to preserve.
  This means that one can continue to usesteady() also
  once one has started to tune the density dependence in reproduction.#208
• Our website is now using the nice new mizer logo designed by Kira Askaroff
  (www.kiraaskaroff.com)
• There is a new mizer extension package
  mizerMR
  allowing you to include multiple resource spectra in your model.

Small improvements

• The rownames ofgear_params are now set to "species, gear", so that one
  can access individual entries with for example
  gear_params(NS_params)["Cod, Otter", "catchability"].#212
• Thez0 argument ofsetExtMort() has been deprecated in favour of
  ext_mort in order to avoid confusion with the species parameterz0.
• setColours() andsetLinetypes() now issue warnings when invalid values
  are given and ignores NAs.
• The experimentalcomment arguments to the setter functions have been
  removed.#214
• The setter functions have a newreset argument which, when set toTRUE
  will recalculate the rates from the species_, gear_ and resource_params even
  when custom values had been set.#214
• Thespecies argument to various functions, which is checked with
  valid_species_arg(), now does not throw an error even when there is no
  valid species included. Only a warning is issued. That means that for
  exampleplotSpectra(NS_params, species = list(), total = TRUE) is now
  allowed.
• getComponent() from the mizer extension mechanism now returns NULL when
  asked for a non-existent component instead of giving an error. This gives
  an easy way to check for the existence of a component.
• The example interaction matrixinter for the North Sea model now has the
  alternative nameNS_interaction, with the old name deprecated.
• Species added withaddSpecies() are now by default given a reproduction
  level of 1/4 instead of 0, because at the low densities at which they are
  introduced there would otherwise not be enough density dependence to
  stabilise them.
• The size range argumentsmin_w,max_w,min_l andmax_l used in some
  summary functions and processed byget_size_range_array() accept vector
  values setting different limits for different species.
• The resource dynamics function is now also passed theresource_rate and the
  resource_capacity as arguments, which makes it easier to use them in
  extension packages.
• Species names are now always coerced to strings, even if the user gives them
  as numbers.#202
• There is a new system for informing the user about how defaults were set by
  newMultispeciesParams(),#199
• Many improvements in the documentation.
• Many small improvements to code quality and testing.
• Better social media cards, especially for twitter.
• mizer can be run on binder,https://mybinder.org/v2/gh/sizespectrum/mizer/HEAD?urlpath=rstudio

Bug fixes

• Changinglinecolour orlinetype in the species parameters now actually
  changes the linecolours and linetypes as intended.
• Growth curves calculated withgetGrowthCurves() and plotted with
  plotGrowthCurves() are now correct, and no longer extend above the
  asymptotic size.
• plotGrowthCurves() withspecies_panel = TRUE now respects thespecies
  argument to only show growth curves for selected species, it works with
  a MizerParams object as well as a MizerSim object, and it shows the panels
  in the correct order.#201
• Reinstated the example .csv files that were missing from the package because
  the vignettes are no longer included.

Contributors

A maintenance release

A maintenance release.