Package index

Overview: the mizer workflow

mizer builds and simulates dynamic, size-structured models of fish communities. Building and using a model follows five stages, and the reference sections below are organised in roughly this order:

Create a model from species and gear parameters, starting with newMultispeciesParams() or one of the simpler newCommunityParams(), newTraitParams() and newSingleSpeciesParams().
Calibrate the steady state so that growth, biomass and yield match observations, with matchGrowth(), calibrateBiomass(), matchBiomasses() and tuneSteadyState().
Tune the dynamics so the model responds realistically to perturbations away from the steady state, with setBevertonHolt() and setResource().
Project the model forward in time under a fishing scenario, with project().
Analyse and plot the results, with summary functions such as getBiomass() and getYield() and plots such as plotBiomass() and plotSpectra().

New users should start with the Get started guide and the topic guides, or open the package overview page below.

mizer mizer-package: mizer: Multi-species size-based modelling in R

Creating a new model

Mizer allows the easy set-up of four different types of models, of increasing level of complexity. See https://sizespectrum.org/mizer/articles/mizer.html#size-spectrum-models for a description of these model types. The guide to building a mizer model walks through the workflow.

newSingleSpeciesParams() experimental: Set up parameters for a single species in a power-law background
newCommunityParams(): Set up parameters for a community-type model
newTraitParams(): Set up parameters for a trait-based multispecies model
newMultispeciesParams(): Set up parameters for a general multispecies model

Changing model parameters

After you have created a model, you will want to make changes to it while tuning the model and for investigating the impact of changes in parameters. See the guide to changing model parameters for how to do this.

species_params() `species_params<-`() is.species_params() given_species_params() is.given_species_params() `given_species_params<-`() calculated_species_params(): Species parameters
record_given_species_params() experimental: Record the species parameters that have changed
reconcileSpeciesParams() experimental: Reconcile the species parameters with the given species parameters
gear_params() `gear_params<-`() is.gear_params(): Gear parameters
`initialN<-`() initialN(): Initial values for fish spectra
`initialNResource<-`() initialNResource(): Initial value for resource spectrum
initial_effort() `initial_effort<-`(): Initial fishing effort
addSpecies(): Add new species
removeSpecies(): Remove species
renameSpecies(): Rename species
renameGear(): Rename gears
adjustSizeGrid(): Adjust the size grid
markBackground(): Designate species as background species
removeBackgroundSpecies(): Remove all background species
use_predation_diffusion() `use_predation_diffusion<-`(): Get or set the use_predation_diffusion flag
second_order_w() `second_order_w<-`() experimental: Get or set the second_order_w flags

Steady state tuning

The first task after creating a multi-species model is to tune the model parameters so that in its steady state the model reproduces average observed growth rates, abundances and fisheries yields. The guide to reaching steady state and calibrating walks through this calibration workflow.

tuneSteadyState() is the function that does that tuning: it holds the reproduction rate and the resource at the values you supply while the spectra settle, and then adjusts the parameters that generate them so that those values are steady too. Its counterpart findSteadyState() changes no parameter and instead reports the steady state that the parameters you already have imply. Both can either run the dynamics or solve the steady-state equation directly, chosen with their solver argument.

Two families of functions rescale abundances to match observations. The calibrate...() functions apply a single overall scaling factor to the whole model, whereas the match...() functions rescale each species individually. Within each family, the ...Biomass variant matches observed biomasses (a biomass_observed column in the species parameters) while the ...Number variant matches observed numbers (a number_observed column). Use matchGrowth() to match observed von Bertalanffy growth, and the plot...ObservedVsModel() functions to see how well the current model reproduces the observations.

tuneSteadyState() experimental: Tune a model so that the state it is in becomes a steady state
findSteadyState() experimental: Find the steady state of a model
isSteady() experimental: Check whether a model is at steady state
getSteadyResidual() experimental: How far a model is from its steady state
getStability() experimental: Analyse the dynamic stability of a mizer steady state
getDiscreteStability() experimental: Analyse the stability of mizer's numerical time step
getOscillationModeSim() experimental: Construct a MizerSim of the leading oscillatory mode
scanModel() experimental: Scan a model over a range of values
scanEffort() scanFishingMortality() scanSpeciesParam() experimental: Setters for scanning a model
steadySingleSpecies() experimental: Set initial abundances to solution of steady-state equation with current rates
matchGrowth() experimental: Adjust model to produce observed growth
plotBiomassObservedVsModel() experimental: Plotting observed vs. model biomass data
calibrateBiomass() experimental: Calibrate the model scale to match total observed biomass
calibrateNumber() experimental: Calibrate the model scale to match total observed number
matchBiomasses() experimental: Match biomasses to observations
matchNumbers() experimental: Match numbers to observations
plotYieldObservedVsModel() experimental: Plotting observed vs. model yields
scaleModel() experimental: Change scale of the model
scaleRates() experimental: Rescale all rates in a mizer model

Dynamics tuning

After tuning the steady state, you need to tune the sensitivity of the dynamics to perturbations away from the steady state. The following functions allow you to change the model without destroying the steady state.

setBevertonHolt() reproduction_level() `reproduction_level<-`(): Set Beverton-Holt reproduction without changing the steady state
setResource() resource_rate() `resource_rate<-`() resource_capacity() `resource_capacity<-`() resource_level() `resource_level<-`() resource_dynamics() `resource_dynamics<-`(): Set resource dynamics

Save a model together with its metadata so it can be archived or shared with other users.

setMetadata() getMetadata(): Set metadata for a model
saveParams() readParams() saveSim() readSim(): Save and restore mizer objects

Running simulations

Project a MizerParams object forward in time to produce a MizerSim object containing the full time series of size spectra.

project(): Project size spectrum forward in time
projectUntilSettled() experimental: Project the dynamics until they settle

Accessing results

Extract the raw arrays stored in a MizerSim object, such as species and resource size spectra and fishing effort at each saved time step, or extract the ecosystem state as a MizerParams object.

getParams() initialParams() finalParams(): Extract the model state from a simulation
N() NResource(): Time series of size spectra
finalN() finalNResource() idxFinalT(): Size spectra at end of simulation
getEffort(): Fishing effort used in simulation
getTimes(): Times for which simulation results are available

Analysing results

Calculate summary quantities from a MizerSim object, such as biomass, yield, growth, and feeding level, averaged or disaggregated over time, species, or size. The guide to analysing and plotting results introduces these functions.

summary_functions: Description of summary functions
getBiomass(): Calculate the total biomass of each species within a size range at each time step.
getDiet(): Get diet of predator at size, resolved by prey species
getGrowthCurves(): Get growth curves giving weight as a function of age
getN(): Calculate the number of individuals within a size range
getSSB(): Calculate the SSB of species
getSteadyResidual() experimental: How far a model is from its steady state
getTrophicLevel() experimental: Get trophic level of individuals at size
getTrophicLevelBySpecies() experimental: Get mean trophic level of each species
getYield(): Calculate the rate at which biomass of each species is fished
getYieldGear(): Calculate the rate at which biomass of each species is fished by each gear
getFeedingLevel(): Get feeding level
getCriticalFeedingLevel(): Get critical feeding level
bin_average_weight() experimental: Bin-average the weight of a size-spectrum integral
sizeIntegral() experimental: Integrate a quantity over the size spectrum
encounter_kernel() experimental: The predation kernel as used by the encounter quadrature
w() w_full() dw() dw_full(): Size bins

Calculating rates

Calculate instantaneous ecological rates from a MizerParams object, such as encounter rate, predation mortality, or somatic growth rate.

For readers coming from single-species fisheries assessment, mizer’s fish mortality rates map onto the standard notation as follows: predation mortality getPredMort() is the multi-species analogue of M2, external mortality ext_mort() is the residual natural mortality not resolved by the model, fishing mortality getFMort() is F, and the total mortality getMort() is Z, the sum of all of these. The older names getM2() and getZ() are retained as superseded aliases for getPredMort() and getMort(). Note that getResourceMort() is different in kind: it is the predation mortality imposed by fish on the background resource spectrum, not a component of fish mortality (its superseded alias is getM2Background()).

getRates(): Get all rates
getDiffusion(): Get diffusion rate from predation
getEGrowth(): Get energy rate available for growth
getERepro(): Get energy rate available for reproduction
getEReproAndGrowth(): Get energy rate available for reproduction and growth
getEncounter(): Get encounter rate
getFMort(): Get the total fishing mortality rate from all fishing gears by time, species and size.
getFMortGear(): Get the fishing mortality by time, gear, species and size
getFeedingLevel(): Get feeding level
getFlux(): Get flux into size bins
getFluxGradient() experimental: Get flux gradient
getMort(): Get total mortality rate
getPredMort(): Get total predation mortality rate
getPredRate(): Get predation rate
getRDD(): Get density dependent reproduction rate
getRDI(): Get density independent rate of egg production
getResourceMort(): Get predation mortality rate for resource

Calculating indicators

Calculate ecological indicators from a MizerSim object, such as mean weight, mean maximum weight, and the Large Fish Index.

indicator_functions: Description of indicator functions
getCommunitySlope(): Calculate the slope of the community abundance
getMeanMaxWeight(): Calculate the mean maximum weight of the community
getMeanWeight() getMeanLength(): Calculate the mean size of the community
getProportionOfLargeFish(): Calculate the proportion of large fish

Plotting results

Visualise size spectra, biomass and yield trajectories, growth curves, and comparisons of model output with observations. See the guide to analysing and plotting results for an introduction to them.

Several plots come in related variants. A plain plot such as plotSpectra() shows a single model or simulation. The ...2 variants (plotSpectra2(), plotCDF2()) overlay two objects in one figure so you can compare them, and the ...Relative variants (plotSpectraRelative()) show the ratio between two objects. The ...ObservedVsModel functions compare model output against observed data. Most plot...() functions have a matching get...() accessor that returns the underlying data frame if you would rather build the plot yourself.

plotting_functions: Description of the plotting functions
plot: Plot mizer arrays
plotHover(): Create a hover-enabled plotly plot from a mizer object
plot2(): Compare two mizer arrays in a single plot
plotRelative(): Plot relative difference between two mizer arrays
animate() animateSpectra(): Animate size-dependent quantities through time
plotSpectra(): Plot abundance and biomass spectra
plotSpectra2(): Compare abundance and biomass spectra from two objects
plotSpectraRelative(): Plot relative difference between abundance spectra
plotCDF(): Plot cumulative abundance or biomass distributions
plotCDF2(): Compare cumulative abundance or biomass distributions from two objects
plotBiomass(): Plot the biomass of species through time
plotPredMort(): Plot predation mortality rate of each species against size
plotFeedingLevel(): Plot the feeding level of species by size
plotYield(): Plot the total yield of species through time
plotYieldGear(): Plot the total yield of each species by gear through time
plotYieldVsF() experimental: Plot the yield of a species against the fishing mortality on it
MizerScan() is.MizerScan() experimental: S3 class for the result of a parameter scan
plot(<MizerScan>) experimental: Plot method for MizerScan objects
plotFMort(): Plot total fishing mortality of each species by size
plot(<MizerParams>): Summary plot for MizerParams objects
plot(<MizerSim>): Summary plot for MizerSim objects
plotDiet() experimental: Plot diet, resolved by prey species, as function of predator at size.
plotGrowthCurves() experimental: Plot growth curves
addPlot() experimental: Add lines to an existing plot
plotBiomassObservedVsModel() experimental: Plotting observed vs. model biomass data
plotYieldObservedVsModel() experimental: Plotting observed vs. model yields
setColours() getColours() setLinetypes() getLinetypes() experimental: Set line colours and line types to be used in mizer plots

Setting custom rates

You can override the rates mizer calculates from the species parameters and gear parameters with your own rate arrays.

setParams(): Set or change any model parameters
setPredKernel() pred_kernel() `pred_kernel<-`(): Set predation kernel
setSearchVolume() search_vol() `search_vol<-`(): Set search volume
setInteraction() interaction_matrix() `interaction_matrix<-`(): Set species interaction matrix
setMaxIntakeRate() intake_max() `intake_max<-`(): Set maximum intake rate
setMetabolicRate() metab() `metab<-`(): Set metabolic rate
setExtDiffusion() ext_diffusion() `ext_diffusion<-`(): Set external diffusion rate
setExtMort() ext_mort() `ext_mort<-`(): Set external mortality rate
setExtEncounter() ext_encounter() `ext_encounter<-`(): Set external encounter rate
setReproduction() maturity() `maturity<-`() repro_prop() `repro_prop<-`() psi(): Set reproduction parameters
setFishing() catchability() `catchability<-`() selectivity() `selectivity<-`(): Set fishing parameters

Extending mizer

Functions for customising a model with new rate functions or ecosystem components. See the guide to extending mizer.

setRateFunction() getRateFunction() other_params() `other_params<-`(): Set own rate function to replace mizer rate function
other_mort() `other_mort<-`() other_encounter() `other_encounter<-`(): Extra contributions to the mortality and encounter rates
setComponent() removeComponent() getComponent(): Add a dynamical ecosystem component
`initialNOther<-`() initialNOther(): Initial values for other ecosystem components
NOther() finalNOther(): Time series of other components
customFunction() experimental: Replace a mizer function with a custom version

Creating extension packages

Infrastructure used by extension package constructors to record their package and apply its S3 class. Model users do not need to call these functions; readParams() and validation manage existing objects. See the guide to creating an extension package.

recordExtension(): Record an extension and its version stamp on a mizer object
coerceToExtensionClass(): Coerce a mizer object to its extension class

Predation kernels

Functions that determine the size preference of predators for prey, i.e. the probability of a predator of a given size eating prey of a given size.

box_pred_kernel(): Box predation kernel
gaussian_mixture_pred_kernel() experimental: Gaussian-mixture predation kernel
lognormal_pred_kernel(): Lognormal predation kernel
power_law_pred_kernel(): Power-law predation kernel
truncated_lognormal_pred_kernel(): Truncated lognormal predation kernel

Fishing selectivity functions

Functions that determine the size-selectivity of fishing gears, i.e. the proportion of fish of a given size that are retained by a gear. The guide to setting up fishing explains how to set up gears, selectivity and effort.

double_sigmoid_length(): Length based double-sigmoid selectivity function
knife_edge(): Weight based knife-edge selectivity function
knife_edge_length(): Length based knife-edge selectivity function
sigmoid_length(): Length based sigmoid selectivity function
sigmoid_weight(): Weight based sigmoidal selectivity function

Resource dynamics

Functions governing the time evolution of the background resource spectrum, together with functions for getting and setting resource parameters.

resource_constant(): Keep resource abundance constant
resource_logistic() balance_resource_logistic(): Project resource using logistic model
resource_semichemostat() balance_resource_semichemostat(): Project resource using semichemostat model
resource_params() `resource_params<-`(): Resource parameters

Reproduction functions

Functions governing the density-dependent relationship between the energy invested in reproduction and the actual egg production rate.

BevertonHoltRDD(): Beverton Holt function to calculate density-dependent reproduction rate
RickerRDD() experimental: Ricker function to calculate density-dependent reproduction rate
SheperdRDD() experimental: Sheperd function to calculate density-dependent reproduction rate
constantEggRDI() experimental: Choose egg production to keep egg density constant
constantRDD() experimental: Give constant reproduction rate
noRDD(): Give density-independent reproduction rate
setBevertonHolt() reproduction_level() `reproduction_level<-`(): Set Beverton-Holt reproduction without changing the steady state
getRequiredRDD(): Determine reproduction rate needed for initial egg abundance

Internal rate functions

These functions are used by project() to calculate instantaneous rates at each time step. You should use the get...() functions instead of the project...() functions.

mizerRates() projectRates(): Get all rates needed to project standard mizer model
projectDiffusion() mizerDiffusion(): Calculate diffusion rate
projectEGrowth() mizerEGrowth(): Get energy rate available for growth needed to project standard mizer model
projectERepro() mizerERepro(): Get energy rate available for reproduction needed to project standard mizer model
projectEReproAndGrowth() mizerEReproAndGrowth(): Get energy rate available for reproduction and growth needed to project standard mizer model
projectEncounter() mizerEncounter(): Get encounter rate during projection
projectFMort() mizerFMort(): Get the total fishing mortality rate from all fishing gears
mizerFMortGear(): Get the fishing mortality needed to project standard mizer model
projectFeedingLevel() mizerFeedingLevel(): Get feeding level needed to project standard mizer model
projectMort() mizerMort(): Get total mortality rate needed to project standard mizer model
projectPredMort() mizerPredMort(): Get total predation mortality rate needed to project standard mizer model
projectPredRate() mizerPredRate(): Get predation rate needed to project standard mizer model
projectRDI() mizerRDI(): Get density-independent rate of reproduction needed to project standard mizer model
projectResourceMort() mizerResourceMort(): Get predation mortality rate for resource needed to project standard mizer model
projectRDD(): Get density-dependent reproduction rate during projection

Info signalling functions

Mizer tells the user about choices it makes on their behalf, such as filling in defaults or adjusting inputs, by raising information signals. These are collected and reported together at a verbosity set by the info_level argument. This allows the user to suppress routine chatter while keeping important warnings. See the guide to changing parameters for how a user controls this, and the guide to creating an extension package for how an extension developer should use this system so their reports are collected along with mizer’s own.

with_info_level() experimental: Collect and report the information signals raised while setting parameters
default_info_level() experimental: The default level of information that mizer gives
signal_info() experimental: Signal information about a choice mizer made
signal_not_recalculated() experimental: Signal that a rate array was not recalculated because it is frozen
signal_frozen(): Signal that a change the user made cannot take effect
signal_frozen_changes(): Signal the changes to species parameters that cannot take effect
signal_ignored_changes(): Signal the changes that are ignored because another parameter was given
signal_gear_params_changes(): Signal a gear parameter changed through the given species parameters
signal_removed_species_params(): Signal that species parameter columns have been removed
frozen_rate_params(): Which parameters feed which frozen array

Internal helper functions

Utility functions used internally by mizer that may also be useful for users building extensions or working with model objects directly.

age_mat(): Calculate age at maturity
age_mat_vB(): Calculate age at maturity from von Bertalanffy growth parameters
calc_selectivity(): Calculate selectivity from gear parameters
constant_other(): Helper function to keep other components constant
default_pred_kernel_params(): Set defaults for predation kernel parameters
different(): Check whether two objects are different
distanceMaxRelRDI() experimental: Measure distance between current and previous state in terms of RDI
distanceSSLogN() experimental: Measure distance between current and previous state in terms of fish abundances
emptyParams(): Create empty MizerParams object of the right size
get_f0_default(): Get default value for f0
get_gamma_default(): Get default value for gamma
get_h_default(): Get default value for h
get_initial_n(): Calculate initial population abundances
get_ks_default(): Get default value for ks
get_phi(): Get values from feeding kernel function
get_size_range_array(): Get size range array
get_steady_state_n(): Calculate steady state abundance
get_time_elements(): Get array indices for a time range in a MizerSim object
get_yield_observed(): Observed yield of each species
l2w() w2l(): Length-weight conversion
needs_upgrading(): Determine whether a MizerParams or MizerSim object needs to be upgraded
project_n() project_n_no_diffusion(): Project values for first time step of Euler method
project_n_2(): Project values with a predictor-corrector method
project_n_tr_bdf2(): Project values with the TR-BDF2 method
project_simple(): Project abundances by a given number of time steps into the future
reconcileSpeciesParams() experimental: Reconcile the species parameters with the given species parameters
record_given_species_params() experimental: Record the species parameters that have changed
set_species_param_default(): Set a species parameter to a default value
validEffortVector(): Make a valid effort vector
validGearParams(): Check validity of gear parameters and set defaults
validSpeciesParams() validGivenSpeciesParams(): Validate species parameter data frame
valid_gears_arg(): Helper function to assure validity of gears argument
valid_species_arg(): Helper function to assure validity of species argument
defaults_edition(): Default editions

Classes

The S3 classes used by mizer, together with functions for constructing, inspecting, comparing, and validating them.

MizerParams-class: A class to hold the parameters for a size based model.
summary(<ArraySpeciesBySize>) summary(<ArrayTimeBySpecies>) summary(<ArrayTimeBySpeciesBySize>) summary(<MizerSim>) summary(<MizerParams>): Summarise mizer objects
str(<ArraySpeciesBySize>) str(<ArrayTimeBySpecies>) str(<ArrayTimeBySpeciesBySize>) str(<MizerSim>) str(<MizerParams>): Display the structure of mizer objects
compareParams(): Compare two MizerParams objects and print out differences
validParams(): Validate MizerParams object and upgrade if necessary
MizerSim-class: A class to hold the results of a simulation
getSimParams(): Extract the projection parameters used to produce a simulation
validSim(): Validate MizerSim object and upgrade if necessary
MizerSim(): Constructor for the MizerSim class
print(<ArraySpeciesBySize>) print(<ArrayTimeBySpecies>) print(<ArrayTimeBySpeciesBySize>) print(<summary.ArraySpeciesBySize>) print(<summary.ArrayTimeBySpecies>) print(<summary.ArrayTimeBySpeciesBySize>): Print mizer objects
print(<mizer_plot>): Print a mizer plot
as.data.frame(<ArraySpeciesBySize>) as.data.frame(<ArrayTimeBySpecies>) as.data.frame(<ArrayTimeBySpeciesBySize>): Convert mizer arrays to data frames
ArraySpeciesBySize() is.ArraySpeciesBySize(): S3 class for species x size rate arrays
ArrayTimeBySpecies() is.ArrayTimeBySpecies(): S3 class for time x species arrays
ArrayTimeBySpeciesBySize() is.ArrayTimeBySpeciesBySize(): S3 class for time x species x size arrays
ArrayResourceBySize() is.ArrayResourceBySize() experimental: S3 class for resource size spectra
ArrayTimeByResourceBySize() is.ArrayTimeByResourceBySize() experimental: S3 class for time x resource-size arrays

Example parameter sets

More example parameter sets are available via https://sizespectrum.org/mizerExamples

NS_params: Example MizerParams object for the North Sea example
NS_species_params: Example species parameter set based on the North Sea
NS_species_params_gears: Example species parameter set based on the North Sea with different gears
NS_interaction: Example interaction matrix for the North Sea example
NS_sim: Example MizerSim object for the North Sea example

Deprecated and superseded

These functions are available for backwards compatibility with earlier versions of mizer. The superseded ones are here to stay; the deprecated ones warn and will eventually be removed.

MizerParams() deprecated: Alias for set_multispecies_model()
completeSpeciesParams() superseded: Alias for validSpeciesParams()
expandSizeGrid() deprecated: Expand the size grid
getESpawning() superseded: Alias for getERepro()
getM2() superseded: Alias for getPredMort()
getM2Background() superseded: Alias for getResourceMort()
getPhiPrey() deprecated: Get available energy
getZ() superseded: Alias for getMort()
inter superseded: Alias for NS_interaction
plotM2() superseded: Alias for plotPredMort()
setInitialValues() deprecated: Set initial values to values from a simulation
setRmax() superseded: Alias for setBevertonHolt()
set_community_model() deprecated: Deprecated function for setting up parameters for a community-type model
set_multispecies_model() deprecated: Deprecated obsolete function for setting up multispecies parameters
set_trait_model() deprecated: Deprecated function for setting up parameters for a trait-based model
getCatchability() getSelectivity() getInitialEffort() getInteraction() getResourceDynamics() getResourceLevel() getResourceRate() getResourceCapacity() getPredKernel() getSearchVolume() getMaxIntakeRate() getMetabolicRate() getExtMort() getExtEncounter() getMaturityProportion() getReproductionProportion() getReproductionLevel() superseded: Superseded get-prefixed aliases for values stored in a model
steady() projectToSteady() superseded: Superseded names for the steady-state finders