species and gears columns are now never factors, so no longer need to
call as.character() so often.validParams() also calls validGearParams().validParams() checks that w_min is valid for all species and increases it
if necessary.A patch update so that users who had changed w_max manually in their model
will not get unhelpful error messages when trying to use their model in the
new version. General checking of parameters is made more robust. In particular
validSpeciesParams() has extra checks on consistency of species parametersvalidParams() checks that rate arrays contain finite numeric valuesvalidSim() checks that simulation results are finite and truncates the
simulation if they are not.newCommunityParams() to set up resource parameters
differently since version 2.4.0 (#293)addSpecies() now correctly preserves all species_params of the existing
model.addSpecies() no longer requires new species to grow to maximum size, only
maturity size is required.validGivenSpeciesParams() validates the given species parameters without
adding defaults and validSpeciesParams() validates and returns a completed
species parameter dataframe.w_repro_max giving the size at which a species
invests 100% of its energy into reproduction. Set to w_max by default.removeSpecies() now also removes species parameters that are not set for
any of the remaining species.w_max now also correctly updates ft_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.plotYieldGear() one can select a subset of gears with new gears
argument.valid_gears_arg() to check the gears argument in
functions that take a gears argument.plotGrowthCurves().steadySingleSpecies() no longer requires species to grow to w_max.matchGrowth() now also rescales the external encounter rate.setExtEncounter() no longer resets the external encounter rate to zero when
called without the ext_encounter argument.plotBiomassObservedVsModel() now plots the ratio of modelled
to observed biomass as default (ratio = T), as this is more useful visually
to see how far off modelled biomass is from observed biomass.time_modified field is now updated correctly by steadySingleSpecies(),
setColours() and setLinetypes().matchYields() and calibrateYield().This is a patch release made necessary by a change in CRAN's requirement regarding the vignettes. It also includes a bug fix:
project() and projectToSteady(..., return_sim = TRUE) now correctly
returns also the other components of the MizerSim object stored in n_other.
#285This release introduces a change that requires you to upgrade your old
MizerParams and MizerSim objects with upgradeParams() or upgradeSim().
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.
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.
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.
effort argument in project() is improved.h of the maximum intake rate is not given, it is now
again given a default value. #282matchGrowth() no longer gives an error when there is no w_inf column. #279This minor release was made necessary to keep mizer on CRAN after a unit test failed on macOS 13.3 with version 14.3 of the CLT toolchain.
This release introduces a change that requires you to upgrade your old
MizerParams and MizerSim objects with upgradeParams() or upgradeSim().
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.
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().
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.
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.calibrateNumber() and matchNumbers() that are like
calibrateBiomass() and matchBiomasses() but work with observed numbers
instead of observed biomasses.age_mat() to calculate the age at maturity from the growth
rate and the size at maturity.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".plotSpectra() or setInitialValues()
the user can now choose geometric averaging with geometric_mean = TRUE.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.newTraitParams().info_level argument in newMultispeciesParams() now
leads to more messages.validSpeciesParams(). #136l2w() and w2l() for converting between length-based
and weight-based species parameters. #258style argument to plotDataFrame() to facilitate producing area plots.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. #267size to linewidth aesthetic to avoid warnings in new version
of ggplot2.compareParams() says so clearly.getReproductionLevel() works as long as R_max is set. #252gear_params().defaults_edition(). #186get_gamma_default() ensures a feeding level of f0
for larvae also if interaction_resource is not equal to 1. #238NS_paramsset_species_default(). #268w_inf no longer leads to error in plyr::aaply(). #269url field in metadata.plotYieldObservedVsModel() and
plotBiomassObservedVsModel(). #266plotDiet() restored after change to ggplot2
package. #265mizerPredRate() between the argument t and the
function base::t().upgradeSim() with a MizerSim object.getRequiredRDD()renameSpecies() no longer fails when linecolour and linetype are of
different lengths.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)plotBiomassObservedVsModel() and plotYieldObservedVsModel()
contributed by @SamikDatta., together with their plotly counterparts.calibrateBiomass(), calibrateYield() to set the model scale to agree
with total observed biomass or total observed yield. Uses the new
scaleModel().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 .params <- setReproduction(params, maturity = my_maturity) one
can simply use maturity(params) <- my_maturity. These are documented
together with the setter functions. #213setMetadata() 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 otherssaveParams() 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.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. #208gear_params are now set to "species, gear", so that one
can access individual entries with for example
gear_params(NS_params)["Cod, Otter", "catchability"]. #212z0 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.comment arguments to the setter functions have been
removed. #214reset argument which, when set to TRUE
will recalculate the rates from the species_, gear_ and resource_params even
when custom values had been set. #214species 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.inter for the North Sea model now has the
alternative name NS_interaction, with the old name deprecated.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.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.resource_rate and the
resource_capacity as arguments, which makes it easier to use them in
extension packages.newMultispeciesParams(), #199linecolour or linetype in the species parameters now actually
changes the linecolours and linetypes as intended.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. #201setBevertonHolt() function has been expanded with more arguments. It
allows you to change the density dependence in reproduction without changing
the steady state of your model.getReproductionLevel() function tells you at what proportion of
their maximum reproduction rate the species are operating in your model.NS_sim which holds
a simulation of the North Sea model.plotDataFrame() allows easier creation of plots.setInitialValues() correctly preserves the gear names on the
initial effort. Thanks to Axel Rossberg.getFMort() correctly passes the t argument on to any custom fishing
mortality function you may have written.mizerPredMort() suggested by Axel Rossberg.plotSpectra() now only shows those species in the legend that are
actually contained in the plot.initialNOther() also works with MizerSim object.projectToSteady() is called with effort, this effort is now also
stored in the initial_effort slot.summary() which is now using sprintf() for better
formatting and also gives the initial_effort.project_simple() have been given convenient defaults.projectToSteady().newSingleSpeciesParams() for creating a single species in a
power-law background.animateSpectra() creating an animated plot of a simulation.addSpecies(), removeSpecies() and renameSpecies().setComponent() can
now take any form, they no longer have to be a named list.return_data in the plot's functions allows to return the
data frame used for the ggplot instead of the plot.steady() no longer switches off the Beverton-Holt density dependence.
You can do this manually with setBevertonHolt() with R_factor = Inf.getYield() now also works with density-dependent fishing mortality.
Thanks to James Roger for discovering the problem.gamma argument now is no longer ignored in newTraitParams() but
correctly overrides the f0 argument. #188getFMort() again works correctly when called with a MizerSim object.resource_semichemostat() no longer fail when at some sizes both the
resource growth rate and the resource mortality rate are both zero.no_w in newTraitParams() is now always an integer.w_min_idx should point to the start of the size bin containing
the egg size w_min".valid_species_arg() is called with species = NULL and there are no
background species then it returns NULL.getDiet() and plotDiet().projectToSteady() to run the full dynamics to steady state.distanceSSLogN() and distanceMaxRelRDI() to measure
distance between two states.compareParams() to compare two MizerParams objects.constantEggRDI() to allow keeping egg densities fixed.customFunction() to allow users to overwrite mizer functions.plotGrowthCurves as a panel of
species with their respective Von Bertalanffy curvesplotPredMort() and plotFMort will stop
displaying mortality values past the species' asymptotic size. The argumentall.sizes allows you to continue to show these values.getFMort() now passes time argument correctly. #181validEffortArray() now sets the dimnames correctly. #173lifecycle package to indicate status of some functions and arguments as
'experimental' or 'deprecated'.setFishing(). #172species argument in mizer functions, via the new
valid_species_arg() function. #170setInitialValues()min_w_pp is larger than min_wt passed to dynamics functions has been corrected.setReproduction() now correctly sets the the total proportion psi when the
maturity proportion is changed.project() has been simplified. They are now either
set by the arguments t_start, t_max and t_save or by the dimension names
of the effort array.setRmax() to setBevertonHolt() and allow it to work on an
arbitrary MizerParams object. The old name setRmax() is still available as
alias.mizerFMort() now can also use the abundances and the rates e_growth and
pred_mort. This is useful for example for implementing balanced harvesting.gear_params is allowed to have zero rows.validGearParams() the species name is used as gear name in case
gear_name is NA.validGearParams() ensures that all required arguments of the
selectivity function are supplied and checks validity of species names.species_params()<- suppresses warnings.steady() fails because RDI is zero it gives a meaningful error message.newCommunityParams() now protects its zero investment in reproduction with
a comment.valid_species_arg() checks validity of species
selection arguments.upgradeParams() can now also upgrade old MizerParams objects that do not
have a consistent initial_effort.validParams() validates a MizerParams object and
automatically upgrades it with upgradeParams() if necessary.project() or steady(), #163.getRates() to calculates all rates and collects them in a list.steady() with return_sim = TRUE now creates the MizerSim object the same way
as project(), namely with the original values in the first time slot.species_params(), gear_params() and
resource_params().project().getRates() functions by removing the arguments that passed in
other rates. Instead the required rates are now always calculated within
these functions.validGearParams() handle NAs more gracefully and check that there are
no duplicates.upgradeParams() works also on params objects that were created with a
development version of mizer.upgradeParams() does a better job at
guessing the value for w_pp_cutoff.getFeedingLevel(), getPredMort(), setInitialValues() and steady() now
work also when model has extra components.plotFeedinglevel() when called with include_critical = TRUE, see #162.species_params is a tibble.params(), effort() and times() to getParams(),
getEffort() and getTimes() to avoid conflicts.getDiet() also takes into account possible contributions by user-defined
other components.project() is called with t_max < t_save then t_save is automatically
reduced so that the result at t_max will get saved.project().project_simple() that projects a given number of
time steps. This might be useful to extension writers.... argument to project() is passed on to the dynamics and rate
functions.steady() runs faster by using project_simple().summary() now also works with non-default feeding kernels. #159validSpeciesParams() no longer fails when w_mat25 is not specified. #160setInitialValues() also works in a model with only a single species. #161resource_params()<- now works and has unit tests.Some inconsistencies in the choice of names for parameters was removed by renaming
interaction_p -> interaction_resourcer_resource -> resource_rateK_resource -> resource_capacityother_params()<- and other_params() for setting and
getting other parameters, for example to be used in user-defined rate
functions.setInitialValues() also sets initial_effort. #157This is a major new release with many new features, an internal refactoring of the code and a new extension mechanism.
Nevertheless this version of mizer is almost fully backwards compatible with version 1.0 with the exception of bug fixes and the following breaking changes:
print_it argument from plot functions.plotFeedingLevel() now only plots the values within the size range of each
species. If for some reason you want the old plots that show a feeding level
also for sizes that the fish can never have, you need to supply an argument
all.sizes = TRUE.RDD argument in setReproduction().sex_ratio argument has been removed from getRDI() and getRDD().set_scaling_model() function has been removed because such models can
now be set up with newTraitParams() with the options perfect_scaling = TRUE
and egg_size_scaling = TRUE.display_frames(), addSpecies(), setBackground() and
retuneAbundance() have been removed to the "mizerExperimental" package
(https://sizespectrum.org/mizerExperimental/)project() a progress bar is displayed by default. You can
turn this off with the option `progress_bar = FALSE.The new functions
newCommunityParams()newTraitParams()newMultispeciesParams()replace the old functions set_community_model(), set_trait_model() and
MizerParams(), which are now deprecated. The new functions choose better
default values, in particular for metabolic rate and maximum intake rate.
After setting up a mizer model, it is possible to change specific model parameters with the new functions
species_params<-()resource_params<-()gear_params<-()setPredKernel()setSearchVolume()setInteraction()setMaxIntakeRate()setMetabolicRate()setExtMort()setReproduction()setFishing()setResource()The new function setParams() is a wrapper for all of the above functions
and is also used when setting up a new model with newMultispeciesParams().
(#51)
The documentation for these functions serves to explain the details of the mizer model.
Along with these setter functions there are accessor functions for getting the
parameter arrays: getPredKernel(), getSearchVolume(),
getInteraction(), getMaxIntakeRate(), getMetabolicRate(),
getExtMort(), getMaturityProportion(), getReproductionProportion(),
getCatchability(), getSelectivity(), getResourceRate(),
getResourceCapacity(), getResourceParams(), getResourceDynamics(),
setRmax().The MizerParams object now also contains the initial values for the size
spectra. This is particularly useful if the model has been tuned to produce
the observed steady state. The new function steady() finds a steady state
for a model and sets it as the initial value. The initial values can be
accessed and changed via functions initialN() and initialNResource(). The
initial values can be set to the final values of a previous simulation with
setInitialValues().
The MizerParams object now has a slot initial_effort that specifies the
initial fishing effort to which the steady state has been calibrated.
Mizer now has an extension mechanism that allows other R packages to be
written to generalise the mizer model. See setRateFunction() and
setComponent(). This mechanism is still experimental and may change as we
gain experience in writing extensions for mizer.
plotlyBiomass() as the
plotly version of plotBiomass(), and so on.plotGrowthCurves() plots growth curves and compares them to the von
Bertalanffy growth curve.plotDiet() plots the diet composition as a function of predator size.highlight argument to all plot functions that display curves for
multiple species. Displays highlighted species with wider lines.plot() method for MizerParams object to plot the initial state.include_critical in plotFeedingLevel() allows to show also
the critical feeding level.wlim argument to plotSpectra() in analogy to the existing ylim
argument to limit the w range in the plot.setColours().solid but this can be changed via the
setLinetypes() function.box_pred_kernel() implements a box-shaped kernel as an alternative to
the default lognormal_pred_kernel().power_law_pred_kernel() implements a power-law kernel with sigmoidal
cutoffs at both ends. This is suitable for filter feeders.setPredKernel()). Mizer automatically
falls back on the old non-FFT code to handle this. (#41)getPredKernel() returns the full 3-dimensional predation kernel array,
even when this is not stored in MizerParams object.Now it is finally possible to have several gears (or fleets) targeting the same
species. The information is set up via a new gear_params() data frame. See
setFishing() for details.
w(), w_full(), dw(), dw_full().upgradeParams() and upgradeSim() can upgrade objects from
previous versions of mizer so they work with the new version.getDiet() calculates the diet of predators. (#43)RickerRDD() and SheperdRDD() for density-dependence
in reproduction, as well as noRDD() and constantRDD().double_sigmoid_length() allows modelling
of escape of large individuals.sigmoidal_weight() is weight-based trawl
selectivity function. (Ken H Andersen)getGrowthCurves() calculates the growth curves (size at age).mizerRates() calculates all the rates needed in the model and collects
them in a list.times() to extract the times at which simulation
results are saved in a MizerSim object.finalN(), finalNResource() and finalNOther() as
well as idxFinalT() to access the values at the final time of a simulation.getCriticalFeedingLevel() returns the critical feeding level
for each species at each size.melt() function from the reshape2 package which allows
users to convert the arrays returned by mizer functions into data frames
that can be used for example in ggplot2 and plotly.validSpeciesParams() checks validity of species parameter data frame and
sets defaults for missing but required parameters.n, p and q as well as the feeding level f0
can now be set at the species level via columns in species_params.fc can now be specified as a species parameter
and will be used to calculate the metabolic rate parameter ks if it is not
supplied.project() now shows a progress bar while a simulation is running. Can be
turned off with progress_bar = FALSE argument.Inf.resource_semichemostat().interaction_resource column in the
species parameter data frame.w_mat25
column in the species parameter dataframe, which gives the size at which
25% of the individuals of a species are mature.m column in the species parameter data frame.project() can now continue projection from last time step of a previous
simulation if the first argument is a MizerSim object. The new append
argument then controls whether the new results are appended to the old.newMultispeciesParams().n, n_pp and n_other arguments
from the initial values in the params argument.perfect_scaling argument allows newTraitParams() to produce a perfectly
scale-invariant model.ext_mort_prop argument in newTraitParams() allows the inclusion of
external mortality.NS_params with the North Sea model MizerParams object.newMultispeciesParams().getmM2() -> getPredMort()plotM2 -> plotPredMort()getM2background() -> getResourceMort()getZ() -> getMort()getESpawning() -> getERepro()MizerParams() -> emptyParams() or set_multispecies_model()r_max to R_max.getSSB(), the calculation of the spawning stock biomass is done correctly
using the maturity ogive instead of the proportion of energy allocated to
reproduction. (#47)getEncounter() and getPredRate() now set names on the returned arrays.ylim argument is not handled correctly in plots.display_frame() is now exported.plotGrowthCurves() and getGrowthCurves() also works when there is only a
single speciest_start argument in project() is used correctlyget_initial_n() gets values for n and q from params objectsummary() of MizerParams object reflects the number of non-empty resource
bins. (@patricksykes)get_gamma_default(),
get_h_default() and get_ks_default(), making it easier to change or
extend these in the future.set_species_param_default() makes it easier to set default
values for species parameters.@inherit functionality of roxygen2 to reduce duplication in
roxygen documentation.getPhiPrey() is replaced by getEncounter() which now returns the full
encounter rate, including the contribution from other components. Even
in the absence of other components, getEncounter() differs from the
old getPhiPrey() because it includes the search volume factor.params to refer to an argument of class MizerParams, sim
to refer to an argument of class MizerSim, and object to an argument that
can be either.setClass() to follow the new guidelines, replacing
representation by class and removing prototype and validity.shiny_progress renamed to progress_bar because they control
any type of progress bar.outer() instead of tapply() where possible to improve readability.hasArg() and anyNA() because they were not available in R 3.1@std_metab and @activity slots into a single @metab slot.@w_min_idx out of @species_params into its own slot.@maturity to hold the maturity ogive.@pred_kernel to hold predation kernel if it has variable
predator/prey ratio.@resource_dynamics to allow user to specify alternative
resource dynamics.@gear_dynamics to species to be targeted by multiple gears.@ft_mask that is used when calculating predation rates using
the Fourier transform method.@rates_funcs to allow mizer extensions to replace mizer rate
functions with their own rate functions.@srr we now have the name of the
function in @rate_funcs$RDD, see #91.@other_dynamics, @other_params, @other_encounter,
@other_mort and @initial_n_other to allow mizer extensions to add more
ecosystem components.set_scaling_model(), see section 12 in the vignette.PlotYield() no longer fails when species names are numbers or when a
species abundance is zerototal parameter to several plot functions to add the curve for the
total community (sum over all species and resource)species parameter to all plot functions to allow for only a
selection of species to be plotted@initial_n and @initial_n_pp slots to MizerParams class.getPhiPrey() and getPredRate().getPhiPrey() and getPredRate().