This release brings new biological realism, improved numerics, a richer interactive analysis experience, and a composable extension framework. For an overview see the blog post pre-announcing the release.
The McKendrick-von Foerster equation now supports a diffusion term, allowing individual variability in growth to be modelled.
New getDiffusion() calculates the total diffusion rate D(w) (g²/year) for
each species, combining the predation-induced diffusion from the jump-growth
equation and any externally specified diffusion set via setExtDiffusion().
It has both MizerParams and MizerSim methods and returns an
ArraySpeciesBySize or ArrayTimeBySpeciesBySize object respectively,
consistent with the other rate-getter functions.
The external diffusion coefficient is held in a new ext_diffusion slot in
MizerParams. Use setExtDiffusion() / ext_diffusion() /
ext_diffusion<-() to set and retrieve it. The new species parameter D_ext
(default 0) sets the coefficient of an external diffusion power law;
setExtDiffusion() calculates the default array from species parameters when
no custom array is supplied, following the same pattern as
setExtEncounter().
MizerParams gains a use_predation_diffusion slot (logical, default
FALSE). When FALSE (the default), mizerDiffusion() omits the
predation-induced diffusion term, preserving the behaviour of previous mizer
versions. Set to TRUE via the new use_predation_diffusion() accessor to
enable the jump-growth diffusion term.
New getFlux() function calculates the flux of individuals entering each
size class, combining the advective flux from somatic growth and the
diffusive flux. It has a power argument, similar to that of plotSpectra(),
for multiplying the flux by a power of the weight; power = 1 gives the flux
of biomass.
getRequiredRDD() is exported. It calculates the recruitment rate needed
to maintain a given initial abundance, accounting for both growth and
diffusion.
steadySingleSpecies() correctly preserves the steady state under
project(), including when diffusion is non-zero.
The vignette cohort dynamics demonstrates the effect of diffusion in an example.
project(), projectToSteady() and steady() gain a method argument for
choosing the consumer density time-stepper. The default "euler" preserves
the existing semi-implicit update, while "predictor_corrector" uses a new
second-order predictor-corrector method. The accuracy of the two methods is
compared in the numerical details
vignette.
MizerSim objects now have a sim_params slot (a named list) that records
the projection parameters — currently method and dt — passed to
project() or projectToSteady(). The new getSimParams() accessor
retrieves this list. When project() is called on an existing MizerSim
object it defaults dt and method from the stored sim_params, with a
warning if the supplied values differ. Older objects are upgraded
automatically by validSim(), with sim_params set to an empty list.
project_n() and project_n_2(2) are new exported functions, factored out of
project_simple(), that projects the abundance spectrum forward in time with
the different methods.
New ArraySpeciesBySize S3 class for the species × size arrays returned by
many mizer functions. An ArraySpeciesBySize object behaves like a regular
matrix for arithmetic and subsetting but carries a human-readable
value_name and units attribute and provides enhanced print(),
summary(), plot(), and as.data.frame() methods. The plot() method
accepts log_y, wlim, and ylim arguments for controlling the y-axis
scale and limits.
New ArrayTimeBySpecies S3 class for the time × species arrays returned by
getBiomass(), getSSB(), getN(), and getYield() when called on a
MizerSim object. Like ArraySpeciesBySize, it carries value_name and
units attributes and provides enhanced print(), summary(), plot(),
and as.data.frame() methods. The plot() method accepts log and ylim
arguments.
New ArrayTimeBySpeciesBySize S3 class for the time × species × size arrays.
The N() accessor on a MizerSim object now returns an
ArrayTimeBySpeciesBySize object. Many rate-getter functions —
getEGrowth(), getEReproAndGrowth(), getPredMort(), getFMort(),
getMort(), getFeedingLevel(), getEncounter(), getPredRate(),
getRDI(), getRDD() — now also accept a MizerSim object and return an
ArrayTimeBySpeciesBySize. An animate() method allows interactive
playback. Subsetting an ArrayTimeBySpeciesBySize object returns an
ArraySpeciesBySize object when a single time is selected, and an
ArrayTimeBySpecies object when a single size is selected.
New plot2() generic with methods for comparing two compatible mizer array
objects in one plot, with species or group shown by colour and model by
linetype. The plotSpectra2() helper has moved from mizerExperimental into
mizer for comparing two abundance spectra.
New plotRelative() generic with methods for plotting the symmetric relative
difference between two compatible mizer array objects. The
plotSpectraRelative() and plotlySpectraRelative() helpers have moved from
mizerExperimental into mizer.
New plotCDF() and plotCDF2() generics for plotting cumulative abundance
or biomass distributions from MizerParams and MizerSim objects, together
with plotlyCDF() and plotlyCDF2() wrappers.
New plotHover() generic with methods for ArraySpeciesBySize,
ArrayTimeBySpecies, ArrayTimeBySpeciesBySize, and mizer_plot converts
mizer plots into hover-enabled plotly figures.
New addPlot() generic with methods for adding ArraySpeciesBySize and
ArrayTimeBySpecies values as extra lines on an existing compatible ggplot.
The animate() methods produces animated plots showing the time evolution
during a simulation. It can take aMizerSim and ArrayTimeBySpeciesBySize
argument and supports axis range settings (xlim, ylim), timing controls,
interpolation options, arguments log_x log_y and log to control which
axis is log-transformed, and total and background arguments, consistent
with plotSpectra().
Plotting functions now consistently expose log_x, log_y and log
arguments. In all cases, when supplied, log overrides log_x and log_y.
plotBiomass() and plotYield() keep support for logical log values for
backward compatibility.
Time-filtering is now consistent across all time-series plot functions via a
new tlim parameter (analogous to wlim and ylim): a length-two numeric
vector c(start, end) that restricts the plotted time window. plotYield(),
plotYieldGear(), and animate() gain this parameter for the first time.
plotBiomass() and animate.MizerSim() now use tlim in place of the
former start_time/end_time and time_range parameters respectively;
the old parameters are deprecated and will be removed in a future release.
Size-based plots now accept size_axis = "l" to show length in cm on the
size axis instead of weight in grams, using the species' allometric
weight-length relationship.
Size-based plots with a size_axis argument now accept llim, the
length-axis equivalent of wlim, for filtering and limiting plots when
size_axis = "l".
A shift in interpretation of a MizerParams object from just a specification of the model to a representation of its state, consisting of both model parameters and current values of the state variables (the abundances).
getParams(sim, time_range, geometric_mean = FALSE) now extracts the
ecosystem state from a MizerSim object at a particular time or averaged
over a time range. When no time_range is given, the state at the final time
step is extracted. New finalParams(sim) and initialParams(sim) return the
states at the initial and final times of a simulation respectively.
Once a state has been extracted from a simulation, it can be analysed by all
the existing mizer functions. For that purpose the indicator functions
getProportionOfLargeFish(), getMeanWeight(), getMeanMaxWeight(), and
getCommunitySlope() now also accept a MizerParams object and return a
single value (or named vector for getMeanMaxWeight() with
measure = "both") calculated from that state. Closes #262.
setInitialValues() is deprecated. Replace
setInitialValues(params, sim) with finalParams(sim) (or
getParams(sim, time_range, geometric_mean) when averaging over a time
range).
Many functions are now S3 generics with methods for
MizerParams or MizerSim objects, and users can define their own subclass
methods to modify mizer behaviour (#330).
New composable extension chain infrastructure: registerExtensions(),
getRegisteredExtensions(), coerceToExtensionClass(),
clearExtensionChain(), and registerExtension(). Extension classes are S3
marker classes; MizerSim derives its extension chain from
sim@params@extensions. Extensions that do not provide a marker class remain
metadata-only and do not trigger the S3 projection-rate dispatch path.
S3 projection hooks have been added for all standard mizer rate functions.
Extension-aware projections dispatch through projectRates(),
projectEncounter(), projectFeedingLevel(), projectEReproAndGrowth(),
projectERepro(), projectEGrowth(), projectDiffusion(),
projectPredRate(), projectPredMort(), projectFMort(), projectMort(),
projectRDI(), projectRDD(), and projectResourceMort() — while models
without extensions continue to use the pre-resolved mizerRates() pipeline
directly, with no per-step overhead.
The MizerSim accessors getParams(),
validSim(), N(), NResource(), finalN(), finalNResource(),
idxFinalT(), getTimes(), getEffort(), and are now
registered as S3 generics with MizerSim methods, making extension-specific
methods possible. validParams() is also now an S3 generic.
saveParams() now serialises extension objects as plain MizerParams
objects while preserving their extension chain, and readParams() restores
the appropriate extension class. New saveSim() and readSim() helpers
provide the same lifecycle for MizerSim objects.
Extension installation support now integrates pak for managing missing or
outdated extension packages.
New vignette
Extending mizer
documents when to use setRateFunction(), setComponent(), and
customFunction(), summarises required function signatures and return shapes,
and gives worked examples for both a custom encounter function and an added
ecosystem component. A companion vignette
Using extension packages
is aimed at users of extension packages, and
Creating a mizer extension package
guides extension authors through setting up a new extension package.
setRateFunction() now validates the registered function by calling it with
test inputs and checking that the return value has the correct dimensions,
catching mismatched custom rate functions at registration time rather than
during a simulation run. Closes #167.
setComponent() now accepts optional colour and linetype arguments and
applies them via setColours() and setLinetypes() so added components can
be styled directly in plots.
The plot() and summary() methods for MizerParams, MizerSim, and the
mizer array classes are now registered as S3 methods rather than S4 methods,
so plot() and summary() remain plain S3 generics when mizer is loaded,
avoiding interference with S4 method dispatch for other packages.
See the model description vignette for the mathematical details.
New species parameters z_ext (default 0) and d (default n - 1) add an
optional power-law term to the external mortality: mu_ext(w) = z0 + z_ext * w^d. When z_ext is zero (the default) the behaviour is unchanged. Closes
#329.
New species parameter E_ext (default 0) sets the coefficient of the
external encounter rate power law. setExtEncounter() now calculates the
default external encounter rate as E_ext * w^n when no custom array is
supplied, matching the pattern of setMaxIntakeRate(). A reset argument is
also added to setExtEncounter() to force recalculation from species
parameters.
New species parameter D_ext (default 0) sets the coefficient of the
external diffusion rate power law. setExtDiffusion() calculates the default
array from species parameters when no custom array is supplied.
The MizerSim methods of the rate-getter functions (getEncounter(),
getFeedingLevel(), getEReproAndGrowth(), getERepro(), getEGrowth(),
getDiffusion(), getPredRate(), getPredMort(), getMort(), getFMort(),
getFMortGear(), getRDI(), getRDD() and getFlux()) are now much faster.
They resolve the rate functions and validate the parameters once and then, at
each saved time step, calculate only the rates needed (and their
dependencies) rather than re-resolving and recomputing the whole rate chain.
The speed-up grows with the depth of the rate chain, e.g. roughly 100× for
getRDI() and getFlux() on a 50-step simulation.
New scaleRates(params, factor) function that rescales all rates in a model
by a given factor. This is equivalent to a time rescaling: it speeds up or
slows down all dynamics without affecting the steady state. All rate slots
(search_vol, intake_max, metab, mu_b, ext_encounter,
ext_diffusion, catchability, rr_pp) and their associated species
parameters (gamma, h, ks, k, z0, z_ext, z0pre, E_ext,
D_ext, R_max) are rescaled consistently.
New getTrophicLevel() function returns a matrix (species × size) with the
trophic level of individuals at each size, accounting for ontogenetic diet
shifts by integrating the consumption-weighted average prey trophic level
over the individual's growth trajectory. New getTrophicLevelBySpecies()
returns the consumption-rate-weighted mean trophic level per species. Both
functions accept MizerParams and MizerSim objects. Closes #307.
New expandSizeGrid() function (an S3 generic) expands the size grid of a
MizerParams object to a new minimum and/or maximum size while preserving
all existing species data. Both addSpecies() and expandSizeGrid() now
preserve the MizerParams subclass. upgradeParams() also preserves
MizerParams subclasses and their extra slots.
compareParams() output is now printed in a human-readable format, with each
difference as its own block separated by blank lines. When array slots differ,
the max absolute difference is shown per species. When slots differ only in
their comment attributes, both comments are displayed. Closes #205.
summary() for MizerParams and MizerSim now displays metadata from the
@metadata slot, including title, description, authors, DOI, URL, mizer
version, and creation/modification timestamps (when set). Closes #294.
New str() methods for MizerParams and MizerSim objects, and the mizer
array classes (ArraySpeciesBySize, ArrayTimeBySpecies, and
ArrayTimeBySpeciesBySize), showing a clean, compact overview of their
structures without dumping large amounts of internal data.
A new steady argument to addSpecies() controls whether steady() is
called after adding the new species.
constantEggRDI() now accounts for diffusion across the egg-size boundary,
including when project() uses the "predictor-corrector" method.
setRateFunction() now validates custom RDI functions with the same
diffusion argument that they receive during projection.
Growth is now forced to always be non-negative, preventing unphysical shrinkage. No warning is issued when growth stops at or after maturity size.
Added info_level argument to projectToSteady(), steady(), setParams(),
newCommunityParams(), newTraitParams(), matchBiomasses(),
matchNumbers(), matchYields() and addSpecies()to control the
verbosity of information messages, consistent with newMultispeciesParams().
Set info_level = 0 to suppress all messages. Closes #290.
t_max and t_save arguments in project() are now respected even when an
effort array is supplied. When t_max is provided, the simulation extends
beyond the times in the effort array using the last known effort values. When
t_save is provided, it controls the save frequency with effort values
interpolated as needed (#231).
getBiomass() now has a use_cutoff argument to restrict the biomass
calculation to sizes above the biomass_cutoff species parameter.
plotBiomass() and plotlyBiomass() also gain this argument.
setResource() now allows resource_level = 1. When balancing would
otherwise divide by zero because the resource capacity equals the current
resource abundance at positive consumption, the capacity is increased
slightly with a warning instead of failing early.
project() now warns when t_max is not a multiple of t_save and ensures
that the state at t_max is always saved, even if the final save interval is
shorter than t_save. (#341)
New function psi() returns an ArraySpeciesBySize with the population-level
reproductive proportion.
age_mat_vB() is now exported.
New Cheatsheet: Analysis and Plotting vignette provides a quick reference for all functions that access simulation arrays, compute summaries, calculate indicators, and create plots. Closes #176.
getFMort() on a MizerSim object was silently dropping the component
names from n_other when passing it to the rate function and its
dependencies (getEGrowth(), getPredMort()), causing failures whenever
rate functions accessed n_other by name (e.g. n_other[["resource"]]).
The implementation has been refactored to use the same plyr::aaply pattern
as getFeedingLevel() and getPredMort().
getFMort.MizerSim() was not passing the time argument t to user-defined
fishing mortality functions.
plotSpectra() was incorrectly forcing the y-axis lower limit to 1e-20
(instead of auto-scaling to the data) and was using min(params@w) / 100
as the default lower w-axis limit even when resource = FALSE, where
min(params@w) is more appropriate.
upgradeParams() was silently dropping some slots (e.g. resource_dynamics)
and was not preserving MizerParams subclasses and their extra slots when
upgrading older objects.
getMeanMaxWeight() now correctly applies the species selector to the
denominator.
plotDataFrame() now correctly applies custom log-scale x breaks.
get_size_range_array() no longer gives an error when no size brackets are
selected.
The default ratio argument in plotBiomassObservedVsModel() and
plotlyBiomassObservedVsModel() is now consistently FALSE for all object
types. Calls that relied on the previous default ratio plot should now set
ratio = TRUE.
The first argument of plotBiomass(), plotYield(), plotYieldGear() and
their MizerSim methods and plotly* wrappers has been renamed from sim
to object for consistency with other plot generics. Calls using
sim = ... as a named argument must be updated to object = ....
The names of the dimnames of the arrays returned by getMort(),
getPredRate() are now sp and w to be in line with other
functions like getFMort().
Functions that return arrays of the form (species x size), (time x species)
or (time x species x size) now return them with extra attributes and an S3
class of ArraySpeciesBySize, ArrayTimeBySpecies or
ArrayTimeBySpeciesBySize. While this does not change their old behaviour,
the differences will be flagged by functions like is.identical().
Because plotDataFrame() now correctly applies custom log-scale x breaks,
the axis ticks in plots that use this function have changed.
plotDiet() no longer accepts a time_range argument.
renameGear() to rename gears in a MizerParams object, similar
to renameSpecies().addSpecies() now proceeds with a warning instead of an error when species
growth stops after maturity (#315).matchBiomasses() and matchNumbers() now provide more informative error
messages.plotDiet() now restricts the plot to size ranges with meaningful biomass
density (#317).wlim and ylim arguments in plotting functions now set the actual axis
limits instead of just zooming (#320).plotlyFeedingLevel() is improved when critical feeding level
is included.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.validSpeciesParams() now also sets default for p to be equal to n.species_params<-() and given_species_params<-() now check that species
names match.params argument in l2w() and w2l() has been renamed to species_params
to follow mizer's convention that params refers to a MizerParams object.animateSpectra() now uses consistent colours and preserves colour identity
across frames (#321).getReproductionProportion() no longer returns incorrect proportions > 1 (#299)setResource() now correctly applies the w_pp_cutoff parameter to the
carrying capacity and initial resource abundance when changed without
providing resource_capacity(#306).given_species_params() no longer makes unwanted changes to the species
parameters.steadySingleSpecies() no longer changes time_modified.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://blog.mizer.sizespectrum.org/posts/2021-08-20-a-5-step-recipe-for-tuning-the-model-steady-state/ .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().