mizer 2.5.0

This release introduces a change that requires you to upgrade your old
MizerParams and MizerSim objects with upgradeParams() or upgradeSim().

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 with setExtEncounter() or ext_encounter<-()
and can be read with getExtEncounter() or ext_encounter(). So this is
similar to how external mortality is handled.

Given versus calculated species parameters

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

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

New mizer course

There is now a three-part mizer course at https://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 of effort argument in project() is improved.
• An error message is given if a predation kernel returns negative values or
  is everywhere zero. #283

Bug fixes

• When the coefficient h 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 no w_inf column. #279

mizer 2.4.0

This release introduces a change that requires you to upgrade your old
MizerParams and MizerSim objects with upgradeParams() or upgradeSim():

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 from w_inf to w_max. The parameter w_inf is now
reserved for the von Bertalanffy asymptotic size parameter. If you upgrade
your existing MizerParams object with upgradeParams() the w_inf column is
copied over to the w_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 parameters kappa and lambda 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 the steady() function the resource
abundance is now being kept fixed at the chosen value. Then the resource
dynamics can be switched on later with setResource() 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 the balance = FALSE argument when calling
setResource().

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

The setParams() function no longer includes the arguments for setting the
resource parameters. Instead you set these separately with setResource().

Automatically match growth rates

As explained in the blog post at https://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 the age_mat column of the species parameter
data frame. This is then used by mizer to calculate a default for the
maximum intake rate parameter h 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 function matchGrowth() 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 call steady() after matching the growth rates.

Other improvements

• New function steadySingleSpecies() 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 new size_at_age argument.
• New functions calibrateNumber() and matchNumbers() that are like
  calibrateBiomass() and matchBiomasses() but work with observed numbers
  instead of observed biomasses.
• New function age_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 in plotSpectra() or setInitialValues()
  the user can now choose geometric averaging with geometric_mean = TRUE.
• The w_mat25 species parameter is no longer filled in automatically if it is
  not supplied. This makes it easier to change w_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 in newTraitParams().
• Higher values for the info_level argument in newMultispeciesParams() now
  leads to more messages.
• Giving more helpful messages in validSpeciesParams(). #136
• New helper functions l2w() and w2l() for converting between length-based
  and weight-based species parameters. #258
• Check that assessor functions for MizerSim slots are called with a MizerSim
  object.
• Add style argument to plotDataFrame() to facilitate producing area plots.
• Add wrap_scale argument to plotDataFrame() to control scaling of axes in
  faceted plots.
• plotDiet() can now show diets of several predator species in a faceted
  plot. #267
• Change from size to linewidth 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 then compareParams() says so clearly.
• getReproductionLevel() works as long as R_max is set. #252
• Converted several unit tests to edition 3 of testthat package.
• Improved documentation for gear_params().
• Improved defaults can now be implemented while keeping backwards compatibility
  via defaults_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 of f0
  for larvae also if interaction_resource is not equal to 1. #238
• Set default linecolour and linetype for external mortality.

Bug fixes

• Restored the line colours to NS_params
• Comment field now preserved by set_species_default(). #268
• Comment on w_inf no longer leads to error in plyr::aaply(). #269
• Can now again set url field in metadata.
• Correct species now listed in the legend of plotYieldObservedVsModel() and
  plotBiomassObservedVsModel(). #266
• Standard order for legend in plotDiet() restored after change to ggplot2
  package. #265
• Fix handling of column names when interaction matrix is read from .csv file.
  #263

mizer 2.3.1

• Resolved conflict in mizerPredRate() between the argument t and the
  function base::t().
• Assert that upgradeParams() must be called with a MizerParams object and
  upgradeSim() with a MizerSim object.
• Errors changed to warnings in getRequiredRDD()
• 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() and getYield()
  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.

v2.3.0

New features

• New plots plotBiomassObservedVsModel() and plotYieldObservedVsModel()
  contributed by @SamikDatta., together with their plotly counterparts.
• New calibrateBiomass(), calibrateYield() to set the model scale to agree
  with total observed biomass or total observed yield. Uses the new
  scaleModel().
• New matchBiomasses() and matchYields() will try to adjust the abundances
  of the species to produce the observed biomasses or yields.
  See blog post at https://bit.ly/2YqXESV .
• There are now accessor and replacement functions for rates. So for example
  instead of params <- setReproduction(params, maturity = my_maturity) one
  can simply use maturity(params) <- my_maturity. These are documented
  together with the setter functions. #213
• New setMetadata() 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
• New saveParams() 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. See getMetadata(). This helps you keep track of
  different versions of your model.
• steady() now has a preserve argument with possible values erepro,
  R_max or reproduction_level to specify which quantity to preserve.
  This means that one can continue to use steady() 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 of gear_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
• The z0 argument of setExtMort() has been deprecated in favour of
  ext_mort in order to avoid confusion with the species parameter z0.
• setColours() and setLinetypes() now issue warnings when invalid values
  are given and ignores NAs.
• The experimental comment arguments to the setter functions have been
  removed. #214
• The setter functions have a new reset argument which, when set to TRUE
  will recalculate the rates from the species_, gear_ and resource_params even
  when custom values had been set. #214
• The species 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
  example plotSpectra(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 matrix inter for the North Sea model now has the
  alternative name NS_interaction, with the old name deprecated.
• Species added with addSpecies() 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 arguments min_w, max_w, min_l and max_l used in some
  summary functions and processed by get_size_range_array() accept vector
  values setting different limits for different species.
• The resource dynamics function is now also passed the resource_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

• Changing linecolour or linetype in the species parameters now actually
  changes the linecolours and linetypes as intended.
• Growth curves calculated with getGrowthCurves() and plotted with
  plotGrowthCurves() are now correct, and no longer extend above the
  asymptotic size.
• plotGrowthCurves() with species_panel = TRUE now respects the species
  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.

v2.2.1

Updated website for version 2.1.1

v2.1.0

Ready for release 2.1.0. Updating website.

v2.0.4

A maintenance release

v2.0.3

A maintenance release.

v2.0.2

A maintenance release.

v2.0.1

A maintenance release.