Individual variability in growth: diffusion in the size spectrum

The headline addition in mizer 3.0 is a diffusion term in the McKendrick–von Foerster equation. Until now, mizer’s size-spectrum model treated growth as a purely advective process: every individual of a given species and size grows at the same rate. In reality, individuals of the same age and species vary considerably in size, and that spread in body size has measurable ecological consequences — for predation, reproduction, and the shape of the size spectrum itself.

The new diffusion term captures this individual variability as a spreading (or “diffusion”) of the abundance distribution along the size axis. Two sources of diffusion are now available:

• External diffusion (D_ext species parameter, set via setExtDiffusion()): a power-law diffusion rate you specify directly, representing any source of individual growth variability.
• Predation-induced diffusion (use_predation_diffusion = TRUE): derived automatically from the jump-growth interpretation of predation, where consuming a prey item causes a discrete jump in body size rather than smooth growth.

The total diffusion rate at every body size is returned by the new getDiffusion() function, and the full flux of individuals (advective + diffusive) is available from getFlux(). The steady-state solution and project() both account for diffusion correctly, including at the recruitment boundary.

A new vignettes Cohort dynamics and diffusion demonstrates the effect of diffusion in a simple example.

A second-order numerical scheme

project(), projectToSteady(), and steady() now accept a method argument. The default "euler" method is unchanged from previous versions. The new "predictor_corrector" option implements a second-order predictor–corrector scheme that delivers substantially better accuracy for the same time step, making it the recommended choice for demanding applications.

Simulation settings are now recorded in every MizerSim object via the new sim_params slot (accessible with getSimParams()), so you always know which method and time step produced a given result. When continuing a simulation from a MizerSim object, project() automatically uses the stored settings.

A new vignette on The Numerical Scheme used in Mizer describes the details of the numerical schemes.

Rich, interactive return values

One of the most user-visible changes in mizer 3.0 is that the arrays returned by mizer’s getter functions are no longer plain matrices — they carry metadata and come with built-in plot(), ggplotly(), print(), summary(), and as.data.frame() methods.

So to get, for example, a plot of the spawning stock biomass, you simply need

ggplotly(getSSB(NS_sim))

Three new S3 classes cover all the main cases:

Each object carries a human-readable value_name and units attribute so that plot() can produce a labelled graph immediately, without requiring any manual axis annotation. ggplotly() wrappers convert every ggplot2 output into a fully interactive plotly figure with a single call.

For ArrayTimeBySpeciesBySize objects, an animate() method produces a smooth animation of the evolving size spectrum, supporting axis limits, interpolation, and background species. So if you want to see how the size-dependent mortality in the North Sea model has changed over the years you can simply do:

animate(getMort(NS_sim), wlim = c(10, NA))

The addPlot() generic lets you overlay additional quantities on an existing figure, and the new plot2() and plotRelative() generics make it straightforward to compare two model states side by side.

New cumulative distribution functions are also available: plotCDF() and plotCDF2() show the cumulative abundance or biomass distribution across sizes — a quick way to see how a fishery or environmental change reshapes the community size structure.

library(mizer)
plotCDF(NS_params)

Composable extension chains

Mizer has long supported custom rate functions and ecosystem components. Version 3.0 introduces a composable extension chain that makes it possible to stack multiple independent extensions on a single model without them interfering with each other.

Extensions register themselves via registerExtension() and can define S3 methods for any of the projection hooks — projectEncounter(), projectFeedingLevel(), projectPredMort(), projectRDI(), and so on. Models without active extensions continue to use the original mizerRates() pipeline at full speed with no per-time-step overhead.

saveParams() and readParams() now preserve the extension chain, and new saveSim() and readSim() helpers do the same for simulation objects. This means shared models load correctly on any machine where the extension packages are installed, with pak invoked automatically to fetch missing dependencies.

Three new vignettes support extension authors and users:

• Extending mizer — when to use setRateFunction(), setComponent(), and customFunction(); required function signatures; worked examples
• Using extension packages — a user-facing guide to loading and running extension-based models
• Creating a mizer extension package — a step-by-step guide for extension authors

New species parameters for external rates

A mizer model does not need to model all ecosystem components explicitly. So some part of mortality, prey encounter and diffusion rates comes from external sources. Three new species parameters give you control over rates that originate outside the explicitly modelled community:

• z_ext and d — add an allometric term to external mortality: mu_ext(w) = z0 + z_ext * w^d. Useful for representing predation by species not included in the model.
• E_ext — coefficient of an external allometric encounter ratew, set via setExtEncounter(). Allows food subsidies from outside the model.
• D_ext — coefficient of an external allometric diffusion rate, as described above.

All three default to zero, so existing models are unaffected.

Other highlights

getTrophicLevel() calculates the trophic level of individuals at every body size, accounting for ontogenetic diet shifts by integrating over each individual’s growth trajectory. getMeanTrophicLevel() returns the consumption-weighted mean trophic level per species.

ggplotly(getTrophicLevel(NS_params))

expandSizeGrid() extends the size grid of a MizerParams object to a new minimum and/or maximum size while preserving all existing species data. This is for example used by addSpecies() when you add a new species to an existing model that grows to sizes larger than previously includes species.

Verbosity control: an info_level argument has been added to projectToSteady(), steady(), setParams(), addSpecies(), newCommunityParams(), newTraitParams(), and the matchBiomasses()/matchNumbers()/matchYields() family. Set info_level = 0 to run these functions silently in pipelines or automated scripts.

compareParams() output has been reformatted for readability, with each differing slot shown as a separate block and per-species max differences reported for array slots.

A new cheatsheet vignette — Analysis and Plotting — provides a compact quick-reference for all functions that access simulation arrays, compute summaries, calculate indicators, and create plots.

For more changes see the Changelog.

Upgrading

mizer 3.0 introduces a few breaking changes:

• 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() and such.

• plotDiet() no longer accepts a time_range argument.

Existing MizerParams and MizerSim objects are upgraded automatically when loaded with readParams() or readSim().

2 Calculating age in mizer

Growth is an emergent property of feeding (Andersen 2019) and so is size-at-age. To calculate the emergent size at age in mizer at time , we introduce an immortal individual (II) of species and track the size of that individual. At time , the size of the II will be , with Solving this from to time with boundary condition , we know that an individual of species and age will be size . In mizer, fish cannot overtake each other in size, therefore we know that fish smaller than will be younger, and larger fish will be older. If we introduce such IIs at annual increments, then we can follow different age classes throughout the model. Figure 1 demonstrates the process, showing how, for a given species, age is calculated.

We solve equation (5) in mizer for time dt numerically given weight classes w, with differences dw. If at the current time the II is size cur_waa then it will be in size class

cur_idx <- max(which(cur_waa >= params@w))

and will grow at rate

g <- grow[cur_idx]
time_to_end <- (togro - cur_waa) / g # how far is next size class, can i grow it in dt?

It will grow at this rate until it reaches the next size class

togro <- params@w[cur_idx + 1]

which will take time

time_to_end <- (togro - cur_waa) / g

Initially the II will grow for time dt but will move through weight classes. We monitor how long is left to grow with variable time_left intially setting it to dt. If time_to_end<=time_left then the II’s weight will be

cur_waa <- cur_waa + g * time_left

otherwise it will grow to the next size class for time_to_end and we update the time remaining

cur_waa <- cur_waa + g * time_to_end
time_left <- time_left - time_to_end 

The process is repeated until time_to_end<=time_left.

Figure 2 shows the emergent weight at age for whiting in mizer.

We added the above to the project and project_simple functions so that it updates the size of the IIs each dt. In addition we added a new slot to the MizerSim objects so that we can store the weight at age for all ages, time steps and species, waa.

#the mizerSim object - now with a waa section
setClass( 
    "MizerSim",
    slots = c(
        params = "MizerParams",
        n = "array",
        effort = "array",
        n_pp = "array",
        n_other = "array",
        waa = "array"
    )
)

Each year we add a new II, and also remove the oldest II at the same time. We give an argument to project to input the initial weights at age (waa_initial), a matrix with dimensions number of species and maximum age (defaulted to 20), nages. If absent the initial weights at age are calculated from the getGrowthCurves function.

The project function will now return a mizerSim object with a waa slot which contains an array with the dimensions t_max*t_save, number of species and nages.

We demonstrate the weight at age using the North Sea model with fishing mortality from stock assessments (historicfishingM see Spence et al. (2024)) from 1984 to 2019. We ran the model to the steady state by running it for 100 years using 1984 fishing and then projected it to 2019.

#project to steady state - so that we can use the waa generated here as initial_waa
#fishing array is the historicfishingM remade for mizer
tosteady <- project(params, effort = fishing_array[1,],t_max =100, initial_n = params@initial_n)

#projecting, using the values from the end of the steady state run for n, npp and waa
projection <- project(params, effort = fishing_array,  initial_n = (tosteady@n)[(dim(tosteady@n)[1]),,],
                      initial_n_pp = (tosteady@n_pp)[(dim(tosteady@n)[1]),],
                      waa_initial = tosteady@waa[1001,,]) 

In Figure 3 we show the size at age of whiting and compare it to weight at age inputs to SMS’ key-run (ICES 2024). Using the default mizer model NS_params we show that the weight at age of whiting changes over the simulation, with a similar pattern to the inputs to SMS, however, the scale and range are different.

2.1 Numbers at age

Given the IIs we can calculate the numbers at age. Suppose that at time the density of numbers at weight is shown below, with IIs aged one, , and two, , being shown.

The numbers younger than age one are all of the individuals smaller than , which in the figure above is 14671.88. The number of individuals younger than two years old are smaller than , which in the figure is 17671.88. Therefore, 14671.88 are in the youngest age class (less than one years old) and 3000 individuals are in the age class between one and two years old.

In this example the IIs were on the boundary of the weight-classes. However, in practice this will almost surely not happen. The IIs will fall between weight-classes, and so, to assign an age to individuals in that weight-class we describe how individuals are distributed within the weight class. The plot below is more likely:

It is clear that the individuals in the red bars are less than one, and the individuals in the blue bar are less than two but older than one, but it is not clear how old the individuals in the white bars are.

Defining how the individuals in the white bars are distributed is down to the user. In this work we defined it as following a power law. Specifically the density of individuals between sizes and was We set and which ensures that the total number in the weight-class is constant in both cases.

The example above becomes:

2.2 Mortality rates

By calculating the numbers at age, as done in the section ‘Numbers at age’, we can calculate how many individuals die in a cohort in a year. Consider that at time and we have calculated numbers age and respectively, then we can rearrange equation (2) to find This is the total mortality for age at time . By calculating the numbers caught at age in time , , in a similar way to how we calculate the numbers at age, we can calculate the fishing mortality and the natural mortality

After a simulation we get the numbers at age and the numbers caught at age

numbers <- get_num_by_year_by_age(sim)
catch <- get_catch_by_year_by_age(sim)

The get_catch_by_year_by_age function works the same as get_num_by_year_by_age, but prior to the numbers in size classes being summed over ages, they are multiplied by the size, species specific fishing mortality, acquired from getFMort. The catch here is the same as in mizer’s getYield.

We calculate equations (6) and (7) for the ith year, jth species and kth age class to get and

z <- -log(numbers[i+1,j,k+1]) + log(numbers[i,j,k])
F_m <- catch[i-1,j,k]*z)/(numbers[i,j,k]-next_alive) ### F_m rather than F as F is protected

and equation (8) to get

m <- z - F_m

Figure 7 is the emergent , and over time using the historical fishing mortality.

3 Sensitivity to no_w and dt

Due to the numerical integration of the partial differential equation (pde) in mizer, the II do not follow the distribution of fish density exactly and this sometimes results in negative . To investigate this we followed one individual and their growth for different values of dt and no_w. We initialised the params object for no_w equal to 100, 1000 and 10000

params <- newMultispeciesParams(NS_params@species_params, no_w = no_w)
allgrow <- getEGrowth(params)
gs <- allgrow[6,]

and assumed a constant growth rate gs for a whiting individual. We initialised the population at zero except in the first size class where we set it so that there was only one individual.

num <- rep(0,length(params@w))
num[1] <- 1 / params@dw[1]

Assuming no mortality and no recruitment we updated the numbers at size for 10 years using the numerical pde solver in mizer (see supplementary for the code) and compared the size distribution with the size of an II at the same age.

We compared the proportion of individuals that are smaller than the II and found that as dt got smaller and no_w got bigger the proportion approached 50%, Figure 8. Further, as dt got smaller and no_wgot bigger the range of sizes at age decreased Figure 9.

Therefore for more accurate age-based information we are required to choose a finer resolution for the numerical solver in mizer. We demonstrate this on the North Sea model for values of dt equal to 0.1, 0.01 and 0.001, and no_w equal to 100, 1000 and 2000.

Decreasing dt and increasing no_w makes the numerial integration more accurate and stablises the results. This comes at a cost, as the MizerSim object gets very large.

4 Discussion

Most models used in advice are age-based. In this blog post, we have introduced a way of calculating emergent age in mizer, potentially increasing the utility of mizer when it comes to giving management advice.

For example, mizer could be used as an operating model for MSEs. A common MSE framework is to use an operating model to test management actions. The operating model stands in for reality and management actions, such as harvest control rules, are run (Punt et al. 2016). This process involves the operating model generating data, which assessment models are fitted to. As data for assessment models is age resolved, the operating model has to be able to sample age resolved data. By introducing emergent age in mizer, mizer can now generate age-based data, meaning that it can be used as an operating model in the MSE frameworks.

Some category 1 assessments, those that have full analytical assessments, use natural mortality at age from fitted multispecies models as inputs to the assessment. For example, many North Sea stocks use natural mortality estimates from the stochastic multispecies model (Lewy and Vinther 2004). Typically, assessment models require natural mortality at age rather than size. In the section ‘Mortality rates’ we showed that we can calculate emergent natural mortality at age. Therefore, coupled with dynamical fitting, (Spence et al. 2021), mizer could be used to provide natural mortality estimates as inputs to single-species assessments.

Many data collection schemes are designed to be fit to age-based models, for example, length stratified sample is used on surveys to calculate age-length keys. For these reasons, it can be difficult to incorporate age-based data when calibrating mizer. Furthermore, the data collected are not in a steady state (e.g., see Figure 3). Using the ages process described here, we can compare these data with mizer. For example, growth could be tuned by looking at emergent growth rates rather than steady states.

In many cases, fishing mortality from stock assessments has been used to drive the dynamics of the mizer model (Blanchard et al. 2014; Spence et al. 2016, 2024). Typically fishing mortality from stock assessments is age-based. In previous studies, the fishing mortality inputs were some kind of average, for example Fbar, or some steady-state assumption about age (Spence et al. 2024). Using this approach, age-based fishing mortality can be implemented in age classes as they change size throughout the simulation as done in the assessment. However, how selectivity occurs within an age can be difficult to calculate (Spence et al. 2024), particularly at lower ages.

The work presented here is exact in the limit when dt and dw are 0, however practically this is not possible. We showed that as dt and dw get smaller the age estimation becomes more accurate, however, inaccuracies in the ageing process can lead to some strange behaviour. For example, we found that for the default values of dt and dw some cohorts natural mortality was less than 0, i.e. , which could cause difficulties when comparing mizer to age-based models. This could be caused by the numerical integration and/or how we say the lengths of fish within an age class are distributed. More research is required, although we suspect these problems occur due to how the emergent catch is calculated.

In this blog post, we introduced an extension that allows you to calculate dynamic growth curves and ages at size in mizer. This addition will improve how mizer is calibrated to data and also allows it to be interpreted and compared to age-based models, potentially increasing the utility of mizer in the assessment and advice process.

Avoid confusion between maximum size and von Bertalanffy asymptotic size

As I explained in the previous blog post Don’t use von Bertalanffy growth parameters, in the past mizer confused the von Bertalanffy growth curve and the mizer growth curve, even though they are very different things. In particular, the mizer documentation advised you to use the asymptotic size parameter of the von Bertalanffy curve as the size at which a species invests 100% of its income into reproduction. The new version finally fixes this.

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.

Separate tuning of steady state and tuning of dynamics

Already mizer 2.0 introduced the idea that building a new mizer model should be done in two stages. In the first stage one adjusts the species parameters so that the model has steady state spectra and steady state yields that roughly agree with averaged observations. Only in the second stage one adjusts the density dependence in the model, i.e., one tunes the sensitivity of the model to changes. This separation between these two stages is similar to the separation between Ecopath and Ecosim.

There are three tunable sources of density dependence in mizer:

• The reproduction level. This is the ratio between the actual rate of reproduction and the maximal rate of reproduction R_max. The higher the reproduction level, the less sensitive the species is to changes in its spawning stock biomass.

• The resource level. This is the ratio between the actual resource abundance and the resource carrying capacity. The higher the resource level the less sensitive the model is to competition among the larvae of the fish species for the limited resource.

• The feeding level. This is the ration between the rate at which individuals take in food and their maximum intake rate. The higher the feeding level, the less sensitive a species is to competition for prey. We’ll discuss this below when we talk about growth rates.

Ideally one would like to be able to tune each of these in the second stage of model calibration without spoiling the steady state calibration from the first stage of the process. Mizer 2.0 already introduced the setBevertonHolt() function that allows one to tune the reproduction level without changing the steady state. Now in mizer 2.4 the setResource() function allows you to also tune the resource level without changing the steady state. While you still can’t change the feeding level without changing the steady state, at least the new matchGrowth() function allows you to keep reasonable growth rates after changing the feeding level.

setResource()

While tuning the steady state using the steady() function the resource abundance is now being kept fixed at the chosen value. Then, once the steady state is to your satisfaction, you can turn on the resource dynamics with setResource() without changing the steady state.

Ler’s assume we are happy with the steady state of the NS_params model that comes with mizer (there are many reasons not to be happy with it yet and mizer 2.5 whould definitely ship with a better example model, but let’s ignore that for now).

params <- steady(NS_params, tol = 1e-10)

Convergence was achieved in 82.5 years.

Warning in setBevertonHolt.MizerParams(params, reproduction_level = old_reproduction_level): The following species require an unrealistic value greater than 1 for `erepro`: Sprat, Sandeel

plotlySpectra(params, power = 2)

Then

params2 <- setResource(params, resource_level = 0.5)

will set the carrying capacity to twice the resource abundance at all sizes and at the same time it will set the resource replenishment rate so that the replenishment balances the consumption of the resource.

Let us verify that in spite of changing the resource level we are still at steady state:

sim2 <- project(params2, t_max = 10)
plotlyBiomass(sim2)

So, given that changing the resource level does not actually change any abundances and leaves us at the same steady state as before, what is the point?

The point is that the system will react differently to changes. As an example, we will investigate the effect of an industrial fishery targeting the small pelagics in the North Sea. The North Sea model is currently set up with an effort of 0 for the industrial gear:

effort <- params@initial_effort
effort

Industrial    Pelagic       Beam      Otter 
       0.0        1.0        0.5        0.5 

The target species of the industrial gear are Sprat, Sandeel and N.pout:

gear_params(params) |> filter(gear == "Industrial") |>
    select(catchability)

                    catchability
Sprat, Industrial              1
Sandeel, Industrial            1
N.pout, Industrial             1

We can now turn on the industrial gear, setting its effort to 1, and see how that impacts the biomasses of the different species in the future:

effort["Industrial"] <- 1
sim <- project(params, effort = effort, t_max = 15)
plotlyBiomassRelative(sim)

Not surprisingly, the target species are suffering. But there are also impacts on the other species. For example Gurnard increases by about 17%, presumably due to decreased competition with the small pelagics. It is of course these multi-species effects that we are particularly interested in being able to model in mizer. So it is important to explore how these effects are affected by the resource dynamics. So now we run exactly the same simulation but with the params object in which we had set the resource level to 0.5 while keeping exactly the same steady state.

sim2 <- project(params2, effort = effort, t_max = 15)
plotlyBiomassRelative(sim2)

By decreasing the resource level we have increased the competition for resource among the species. Fishing the small pelagics has decreased their biomasses and they thus consume less resource. Some species like Herring profit enormously from this.

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().

The arguments kappa and lambda in newMultispeciesParams() are now used to set the abundance of the resource in the steady state rather than the carrying capacity. This is in any case more useful because you may have observations about the resource abundance whereas the resource carrying capacity is unobservable.

Another addition in mizer 2.4.0 is that you can choose between semichemostat dynamics resource_semichemostat() or logistic dynamics resource_logistic(). To switch to logistc dynamics you would do

params3 <- setResource(params, 
                       resource_dynamics = "resource_logistic", 
                       resource_level = 0.3)

You can of course choose any value between 0 and 1 for the resource level.

Investigating resource dynamics other than semichemostat is interesting because semichemostat dynamics are particularly stable and the real world may not be as accommodating. For example in logistic dynamics, if the resource level drops below 1/2, the replenishment rate decreases as the abundance decreases, which is of course destabilising. Take a look:

sim3 <- project(params3, effort = effort, t_max = 60)
plotlyBiomassRelative(sim3)

Of course you can also still write your own function implementing more sophisticated resource dynamics.

matchGrowth()

In the previous blog post Don’t use von Bertalanffy growth parameters, I discussed that the von Bertalanffy curves fitted to size-at-age data are not suitable for estimating the size-dependent growth rates in mizer. I 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. Mizer will then use that 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.

This allows us for example to change the feeding level without spoiling the growth rates. Let’s do an example. We double the maximum intake rate for Cod, and this of course gives it a lower feeding level:

params4 <- params
species_params(params4)["Cod", "h"] <- species_params(params)["Cod", "h"] * 2
plotlyFeedingLevel(params4)

However this also spoiled the growth rate for Cod. We can fix that with matchGrowth() followed by steady().

params4 <- params4 |> matchGrowth() |> steady()

Convergence was achieved in 13.5 years.

Warning in setBevertonHolt.MizerParams(params, reproduction_level = old_reproduction_level): The following species require an unrealistic value greater than 1 for `erepro`: Sprat, Sandeel, N.pout, Herring, Dab, Whiting, Sole, Gurnard, Plaice, Haddock, Cod, Saithe

plotlyFeedingLevel(params4)

Normally you will want to also keep biomasses at the observed level, for which already mizer 2.3.0 provided the matchBiomasses() function. So often you will run all three in a row. So the pattern is:

# make some changes to the model parameters and then find a new steady state
# with the correct growth rates and abundances with
params <- params |> matchGrowth() |> matchBiomasses() |> steady()

There is of course a lot more to say. But first there is Christmas to celebrate. Even if your cultural background does not dictate that you celebrate Christmas, I hope you will have some quality time to spend with your friends and family.

Estimating von Bertalanffy parameters

The von Bertalanffy growth parameters are usually obtained by fitting the von Bertalanffy curve to size-at-age data. For a good introduction I recommend the fishR vignette. To illustrate this we will use the Croaker2 data set contained in the FSAdata package. The data consists of observations of the lengths and ages of a sample of fish.

library(tidyverse)
df <- FSAdata::Croaker2 |>
    select(age = age, length = tl) |>
    filter(age > 0) |>
    na.omit()
pl <- ggplot(df) +
    geom_jitter(aes(x = age, y = length))
pl

In this scatterplot each point shows the length and age of one croaker from our sample.

The standard method to fit a von Bertalanffy curve to such a point cloud of size-at-age observations is the method of least squares. This consists of choosing the parameters so as to minimise the sum of the squares of the differences between the the observed lengths and the length predicted by the von Bertalanffy curve. So if we denote the length measurements by and the corresponding age measurements by then we want to minimise

where the sum is over all fish in our sample.

To find the minimum, we will use the function optim(). First we create a function that calculates the sum of squares when given a vector with the parameters:

sum_of_squares <- function(par, df) {
    Linf <- par[[1]]
    K <- par[[2]]
    t0 <- par[[3]]
    sum((df$length - length_vB(df$age, Linf, K, t0))^2)
}

We need to give an initial guess for the parameters to optim, as well as lower bounds on the parameter values.

start <- list(Linf = 400, K = 0.3, t0 = 0)
lower <- list(Linf = 0, K = 0.01, t0 = -4)

It does not matter too much what the initial guess is as long as it is not too wrong. The lower bound is needed to keep the optimizer from trying negative values for . Now we can call optim(). (We use the method “L-BFGS-B” because that is the only built-in method that handles bounds on the parameters.)

op_age <- optim(start, fn = sum_of_squares, 
            df = df, lower = lower, 
            method = "L-BFGS-B")
op_age$par

       Linf           K          t0 
416.0794061   0.2423941  -2.1629160 

Let us plot the von Bertalanffy curve with these parameters on top of or observations:

pl <- pl +
    geom_function(fun = length_vB, args = as.list(op_age$par),
                  linewidth = 2, colour = "blue")
pl

At each age the fitted von Bertalanffy curve approximates the average of the lengths of all the fish of that age.

Of course, the curve is only made to fit the data in the observed size range. The curve clearly does not extrapolate well to larval sizes as we can see from the large negative value of . This becomes clearer if we extend the age range of the plot.

pl + xlim(0, 12) +
    geom_hline(yintercept = op_age$par[["Linf"]], 
               colour = "blue", linetype = "dashed")

The curve would predict a length of more than 170cm at birth, which is clearly nonsense. The larval growth must be much faster than predicted by the von Bertalanffy curve. That is why mizer works with a bi-phasic growth model, but that is not our current topic.

In the above plot we also indicated the average asymptotic length with a dashed blue line. What will be important for us is to note that this is the average asymptotic length and that there are a lot of fish with a length larger than .

There are many issues that we could debate and that have been debated at length in the literature:

1. Is the von Bertalanffy growth model the best growth model.
2. How reliably can the growth be estimated from the size-at-age data.
3. Is least squares estimation an appropriate method.

But none of these are our topic. We will assume that the von Bertalanffy curve gives an appropriate representation of the length at age of an average fish of that age.

Age-dependent growth rate

The slope of the von Bertalanffy curve at age gives the average growth rate of fish of that age:

(We used that time and age increase together, .)

The important point to understand is that this is the growth rate as a function of age. The length that enters the expression is the average length of fish of age . This is useful information in age-based population models. It is not useful in size-based models like mizer.

Size-dependent growth rate

We want the average growth rate for fish of some given length rather than the average growth rate for fish of a given age . Why? There can be several reasons.

Assume for example that we want to estimate the productivity of a population and have only information about the size distribution of the population. Such size data is often more readily available than age data because length or weight measurements are easy while age determination is difficult and time consuming. If we have the average growth rate of fish as a function of size then we can multiply that by the abundance of fish of that size and sum over all sizes to get the total productivity.

More relevantly to us, the mizer model is a size-based model that uses the growth rate as a function of size to project the size distribution into the future. Mizer of course can calculate this growth rate itself with its getEGrowth() function. However it would be good if one had an observed growth rate to compare to to calibrate the species parameters in mizer that influence the mizer growth rate.

One might think that the above equation also gives an expression for the average growth rate for fish of length . Can’t we simply replace the by ?

We can’t. If we try that, then at all above the formula gives a negative growth rate. But that is not how fish work. Fish that are lucky enough to grow beyond the average asymptotic size are not compelled to shrink back to average size.

What we need to realise is that in fitting the von Bertalanffy curve to the size-at-age data we did not treat size and age equally. Rather we chose to average over all sizes at fixed age. From that averaged data we can not reconstruct the information about what happens at a specific size.

Size-based growth curve

We now understand that from a curve describing the average size of all fish of a certain age we can not deduce the average age of all fish of a certain size and hence we can not use it to determine the growth rate as a function of size. What we would need is a curve describing the average age of all fish of a certain size. Let’s refer to that as a size-based growth curve as opposed to an age-based growth curve.

Now we want to discuss how we can determine a size-based growth curve from size-at-age data. This should be possible. If the size-at-age data comes from a random sample of fish for each of which its size and age were measured, then the data treats size and age the same. It was only our least squares fit that singled out age as the explanatory variable and size as the variable to average over. We now simply have to reverse the roles of size and age.

We’ll again use the von Bertalanffy growth model, in the sense of assuming that the growth rate decreases linearly with length,

but now we interpret this as the growth rate of an average individual of size . This immediately implies that the parameter is the length of the largest individual in the population. We can use that growth rate to express the age as a function of length instead of expressing length as a function of age. This gives the expression

This expression of course has a singularity at because even if a fish lived for an infinite amount of time it would not grow beyond . Dealing with that singularity in the expression numerically would be challenging, so we acknowledge that fish are never going to live infinitely long and therefore will never quite reach and so we can cut of the curve when gets sufficiently close to .

age_vB <- function(L, Lmax, K, t0) {
    r <- pmin(L / Lmax, 0.999999)
    t0 - log(1 - r) / K
}

Instead of choosing the parameters so as to minimize the sum of squares of the difference between the observed lengths and the predicted lengths, we minimize the sum of squares of the difference between the observed ages and the predicted ages. The function calculating the sum of squares is now

sum_of_squares <- function(par, df) {
    Lmax <- par[[1]]
    K <- par[[2]]
    t0 <- par[[3]]
    sum((df$age - age_vB(df$length, Lmax, K, t0))^2)
}

Because all observations must be strictly shorter than we need to start optim with a starting value for that is above the largest observed length.

start <- list(Lmax = max(df$length) * 1.2, K = 0.3, t0 = 0)
lower <- list(Lmax = 0, K = 0.01, t0 = -4)
op_length <- optim(start, fn = sum_of_squares, df = df, 
            lower = lower, method = "L-BFGS-B")
op_length$par

         Lmax             K            t0 
1235.69702683    0.04733173   -1.22046772 

We can now again visualise this curve by plotting it on top of the point cloud of observations:

pl <- ggplot(df) +
    geom_jitter(aes(x = length, y = age)) +
    geom_function(fun = age_vB, args = as.list(op_length$par),
                  linewidth = 2, colour = "blue")
pl

Given that we are now dealing with the size-based growth curve, we plot the length on the x axis and the age on the y axis.

I am not saying that fitting a von Bertalanffy curve to the average growth at size via least squares is a good idea. I am showing it only to compare to the fitting of a von Bertalanffy curve to the average growth at age that is commonly done. I think that a bi-phasic growth model like that used in mizer is more appropriate.

One problem with the von Bertalanffy curve is that there is a wide range of maximum sizes that can fit the data almost equally well. For example we may find that the maximum length of 1236cm predicted by the least squares fit is unrealistic and set an upper bound of 600cm:

upper <- list(Lmax = 600, K = 0.5, t0 = 4)
op_length_2 <- optim(start, fn = sum_of_squares, df = df, 
            lower = lower, upper = upper, method = "L-BFGS-B")
op_length_2$par

       Lmax           K          t0 
600.0000000   0.1838247   0.9216962 

That leads to totally different values for and but the fit is almost as good:

pl + geom_function(fun = age_vB, args = as.list(op_length_2$par),
                   linewidth = 2, colour = "green")

So what should you do?

We have now understood that to estimate the size-dependent growth rate you should not use the age-based von Bertalanffy parameters, even though they are routinely used in age-based models and are therefore often readily available. So what do I propose you use instead for your species parameters when setting up a mizer model?

species <- c("Gadus morhua", "Sprattus sprattus")
length_weight <- rfishbase::estimate(species) |>
    select("Species", "a", "b")

Joining with `by = join_by(SpecCode)`

max_length <- rfishbase::species(species) |>
    select(Species, Length)

Joining with `by = join_by(SpecCode)`

max_weight <- left_join(max_length, length_weight) |>
    mutate(w_inf = a * Length ^ b)

Joining with `by = join_by(Species)`

max_weight

maturity_tbl <- rfishbase::maturity("Sprattus sprattus") |>
    select(Species, l_mat = Lm, age_mat = tm, Locality) |>
    na.omit()

Joining with `by = join_by(SpecCode)`

maturity_tbl

Aerobic scope

The relationship between aerobic scope and temperature is a somewhat left-skewed distribution with a thermal optimum and upper and lower thermal tolerance limits. Pörtner and Peck (2010) provide an overview of this relationship and Pörtner (2012) discusses open questions related to temperature and physiology. The exact nature of the relationship between aerobic scope and temperature varies by species and requires a fair bit of physiological research to establish. Therefore, it is generally necessary to approximate this relationship, which is what therMizer does. A generic polynomial rate equation is used to approximate the effect of temperature on aerobic scope, s: where T is the temperature to which a fish is exposed and and are the species’ upper and lower thermal tolerance limits, respectively (van der Heide et al. 2010). All temperatures in eq. (1) are in Kelvin. The result of this expression varies considerably given a species’ thermal tolerance limits. Therefore, it is necessary to scale this value across all modeled species so that it equals a value ranging from 0 – 1. This is done by dividing by the maximum value over each species’ thermal range (Woodworth-Jefcoats et al. 2019). therMizer will take care of this scaling for you.

The scaled value is then used as a multiplier for encounter rate and predation rate in mizer. The scaling is applied to encounter rate as proxy for foraging movement. The resulting temperature effect is such that when species are at their thermal optima they realize peak aerobic performance and encounter the maximum amount of prey possible. This ability diminishes to either side of the optimum and reaches zero outside species’ thermal tolerance limits. The scaling is applied to predation rate to ensure encountered prey are predated upon.

Metabolic rate

The relationship between metabolic rate and temperature is exponential and positive (see, for example, Brown et al. 2004). To simulate this, therMizer uses a Boltzmann factor or Arrhenius relation: where r is the effect of temperature on metabolic rate, E is activation energy (0.63 eV), k is Boltzmann’s constant ( eV K), and T is temperature in Kelvin (Brown et al. 2004, Jennings et al. 2008). The result of this expression varies depending upon the temperature to which species are exposed, which is in turn a factor of species’ thermal tolerance limits. Therefore, it is necessary to scale this value across all species so that it equals a value ranging from 0 – 1. This is done by subtracting the minimum value over each species’ thermal range and then dividing the result by the range (Woodworth-Jefcoats et al. 2019). therMizer will take care of this scaling (and converting from degrees C to Kelvin) for you when you.

The scaled value is then used as a multiplier for standard metabolism in therMizer. This has the effect of metabolism being the least expensive when species are at the low end of their thermal tolerance and the most expensive at the upper limits of their thermal tolerance.

Finally, therMizer sets the rate scalings to 0 outside species’ thermal range, simulating the assumption that species would move out of waters that are either too warm or too cool.

Model input

The only additional input you’ll need to provide, beyond what’s needed to run mizer, are three temperature values for each species. temp_min and temp_max represent the lower and upper bounds of a species’ thermal tolerance limits. You can find this information in the literature or in databases such as rfishbase (Boettiger et al. 2012). You also need to provide ocean_temp, the temperature to which species are exposed. This can be static or dynamic, and informed from either empirical or modeled data. Temperatures are input in degrees Celsius. therMizer will convert them to Kelvin.

That’s it. That’s all you need.

A simple simulation

Let’s do a simple simulation with two fictional fish species. We’ll need to invent some parameters for them:

library(mizer)

species_params <- 
    data.frame(species = c("speciesA", "speciesB"), 
               w_inf = c(500, 5000), 
               k_vb = c(0.8, 0.3), 
               w_min = c(0.001, 0.001), 
               beta = c(1000,100), 
               sigma = c(3,3))
species_params$interaction_resource <- c(1,0.5)
params <- newMultispeciesParams(species_params, no_w = 200, kappa = 0.0001) |> 
    steady(tol = 0.001)

Add their hypothetical thermal tolerance limits:

species_params(params)$temp_min <- c(15, 10)
species_params(params)$temp_max <- c(25, 20)

And, finally, the temperatures to which each species is exposed. To make it interesting, we’ll have one species eventually encounter temperatures beyond its thermal tolerance limits.

# Create temperature array and fill it
times <- 0:500
species <- species_params(params)$species
ocean_temp_array <- array(NA, dim = c(length(times), length(species)), 
                          dimnames = list(time = times, sp = species))
temp_inc <- 0
for (i in 1:501) {
  ocean_temp_array[i,] <- c(17 + temp_inc, 17 + temp_inc)
  temp_inc <- temp_inc + 0.01
}
other_params(params)$ocean_temp <- ocean_temp_array

Now that we’ve put in all the necessary temperature information, we can add the code that tells mizer how to use it. First, the parameters needed to do the scaling that’s mentioned above:

# Create parameter for scaling encounter and mortality rates
species_params(params)$encounterpred_scale <- 
    rep(NA, nrow(species_params(params)))

for (indv in seq(1:length(species_params(params)$temp_min))) {
    
    # Create a vector of all temperatures each species might encounter
    temperature <- seq(species_params(params)$temp_min[indv], 
                       species_params(params)$temp_max[indv], 
                       by = 0.1) + 273
    
    # Find the maximum value of the unscaled effect of temperature on encounter
    # and predation rate for each species 
    species_params(params)$encounterpred_scale[indv] <- 
        max((temperature) * 
                (temperature - (species_params(params)$temp_min[indv] + 273)) *
                ((species_params(params)$temp_max[indv] + 273) - temperature)^(1/2)
            )
}

# Determine the minimum, maximum, and range of value for the effect of 
# temperature on metabolism
    
min_metab_value <- 
    (exp(25.22 - (0.63/((8.62e-5)*(273 + species_params(params)$temp_min)))))
max_metab_value <- 
    (exp(25.22 - (0.63/((8.62e-5)*(273 + species_params(params)$temp_max)))))
        
species_params(params)$metab_min <- min_metab_value
species_params(params)$metab_range <- max_metab_value - min_metab_value

Then, we can add code to scale encounter rate and predation rate based on the temperature at a given time step:

# Calculate the temperature scaling factor for the encounter rate and 
# predation rate
scaled_temp_effect <- function(t) {
    # Using t+1 to avoid calling ocean_temp[0,] at the first time step
    temp_at_t <- other_params(params)$ocean_temp[t + 1,] + 273
    
    # Calculate unscaled temperature effect using a generic polynomial rate equation
    unscaled_temp_effect <- 
        temp_at_t * (temp_at_t - (species_params(params)$temp_min + 273)) * 
        ((species_params(params)$temp_max + 273) - temp_at_t)^(1/2)
    
    # Scale using new parameter
    scaled_temp_effect <- 
        unscaled_temp_effect / species_params(params)$encounterpred_scale
    
    # Set temperature effect to 0 if temperatures are outside thermal 
    # tolerance limits
    above_max <- (temp_at_t - 273) > species_params(params)$temp_max
    below_min <- (temp_at_t - 273) < species_params(params)$temp_min
    scaled_temp_effect[above_max | below_min] = 0
    
    scaled_temp_effect
}


therMizerEncounter <- function(params, t, ...) {
    
      # Calculate maximum possible encounter rate
      max_encounter <- mizerEncounter(params, t, ...)
      
      # Apply temperature effect
      return(max_encounter * scaled_temp_effect(t))
      
}

therMizerPredRate <- function(params, t, ...) {
      # Calculate maximum possible encounter rate
      max_predrate <- mizerPredRate(params, t, ...)
      
      # Apply temperature effect
      return(max_predrate * scaled_temp_effect(t))
      
}

As well as metabolic rate:

therMizerEReproAndGrowth <- function(params, t, encounter, feeding_level, ...) {
    
    # Using t+1 to avoid calling ocean_temp[0,] at the first time step
    temp_at_t <- other_params(params)$ocean_temp[t + 1,]
  
    # Arrhenius equation
    unscaled_temp_effect <- (exp(25.22 - (0.63/((8.62e-5)*(273 + temp_at_t)))))
    
    # Arrhenius equation scaled to a value between 0 and 1
        temp_effect_metabolism <- 
            (unscaled_temp_effect - species_params(params)$metab_min) /
            species_params(params)$metab_range
        
        # Set temperature effect to 0 if temperatures are outside thermal 
        # tolerance limits
    above_max <- temp_at_t > species_params(params)$temp_max
    below_min <- temp_at_t < species_params(params)$temp_min
    temp_effect_metabolism[above_max | below_min] = 0
  
    # Apply scaled Arrhenius value to metabolism
    sweep((1 - feeding_level) * encounter, 1,
          species_params(params)$alpha, "*", check.margin = FALSE) - 
        metab(params)*temp_effect_metabolism  
      
}

Finally, we need to replace mizer’s rate functions with our new temperature-dependent rate functions:

params <- setRateFunction(params, "Encounter", "therMizerEncounter")
params <- setRateFunction(params, "PredRate", "therMizerPredRate")
params <- setRateFunction(params, "EReproAndGrowth", "therMizerEReproAndGrowth")

Let’s see what a simulation looks like.

sim <- project(params, t_max = 500, effort = 0) 
plot(sim)

Adapting this for a data-based simulation

You’re likely going to want to do simulations based on real species and real temperature observations or projections. This is straightforward to do. When you prepare your species parameters, add temp_min and temp_max columns for each species. You’ll also need to prepare an ocean_temp input with dimensions that match those of time and species.

Once you’ve prepared your input, you can use the code above to create and use the encounterpred_scale, metab_min, and metab_range parameters and the therMizerEncounter, therMizerPredRate, and therMizerEReproAndGrowth rate functions.

In the works

Many fish undergo ontogentic migration, spending different life stages at different depths and therefore different thermal habitats. I’m working on adding to therMizer the capacity for different size classes to experience different temperatures.

Acknowledgements

This blog post was compiled with mizer version 2.3.1 and R version 4.2.1. Many thanks to Gustav Delius for guidance on mizer’s inner workings and writing better code. Thank you also to Romain Forestier for insight on working with temperatures below 0.

Update note

Post updated on 19/09/22: The equation for aerobic scope was changed to allow users to input negative Celsius temperature. To accommodate this, temperatures are now converted to Kelvin and the square root of the final polynomial term is taken to preserve the curve shape.

References

Boettiger C, Lang DT, Wainwright PC. (2012) rfishbase: exploring, manipulating, and visualizaing FishBase from R. Journal of Fish Biology 81, 2030–2039. https://doi.org/10.1111/j.1095-8649.2012.03464.x

Briere J-F, Pracros P, Le Roux A-Y, Pierre J-S. (1999) A novel rate model of temperature-dependent development in arthropods. Population Ecology, 28(1): 22-29. https://doi.org/10.1093/ee/28.1.22

Brown JH, Gillooly JF, Allen AP, Savage VM, West GB. (2004) Toward a metabolic theory of ecology. Ecology, 85: 1771–1789. https://doi.org/10.1890/03-9000

Jennings S, Mélin F, Blanchard JL, Forster RM, Dulvy NK, Wilson RW. (2008) Global scale predictions of community and ecosystem properties from simple ecological theory. Proceedings of the Royal Society B, 275: 1375–1383. https://doi.org/10.1098/rspb.2008.0192

Pörtner HO. (2012) Integrating climate-related stressor effects on marine organisms: unifying principles linking molecule to ecosystem-level changes. Marine Ecology Progress Series, 470: 273–290. https://doi.org/10.3354/meps10123

Pörtner HO, Peck MA. (2010) Climate change effects on fishes and fisheries: toward a cause-and-effect understanding. Journal of Fish Biology, 77: 1745–1779. https://doi.org/10.1111/j.1095-8649.2010.02783.x

van der Heide T, Roijackers RMM, van New EH, Peeters ETHM. (2006) A simple equation for describing the temperature dependent growth of free-floating macrophytes. Aquatic Botany, 84: 171–175. https://doi.org/10.1016/j.aquabot.2005.09.004

Woodworth-Jefcoats PA, Blanchard JL, Drazen JC. (2019) Relative Impacts of Simultaneous Stressors on a Pelagic Marine Ecosystem. Frontiers in Marine Science, 6:383. https://doi.org/10.3389/fmars.2019.00383

Setting up an example

I will use the same species parameters and gear parameters for a North Sea model that I used in my previous blog post, but I will now also use the species interaction matrix NS_interaction that comes as an example with mizer, and which encodes that, due to only partial spatial overlap, not all species interact with each other with the same strength. With those parameters we can create the mizer model and make an initial plot of the steady state:

params <- newMultispeciesParams(species_params = species_params,
                                gear_params = gear_params,
                                interaction = NS_interaction,
                                initial_effort = 1)

Because you have n != p, the default value for `h` is not very good.
Because the age at maturity is not known, I need to fall back to using
von Bertalanffy parameters, where available, and this is not reliable.
No ks column so calculating from critical feeding level.
Using z0 = z0pre * w_max ^ z0exp for missing z0 values.
Using f0, h, lambda, kappa and the predation kernel to calculate gamma.

params <- steady(params)

Convergence was achieved in 16.5 years.

plotlySpectra(params, power = 2)

As discussed in that previous post, matching to the observed biomasses is easy:

params <- params |> calibrateBiomass() |> matchBiomasses() |> steady() |>
    calibrateBiomass() |> matchBiomasses() |> steady() 

Warning in setBevertonHolt.MizerParams(params): For the following species `erepro` has been increased to the smallest possible value: erepro[Sprat] = 0.021; erepro[Sandeel] = 0.000425; erepro[Cod] = 6.12e-05; erepro[Saithe] = 1.23e-05

Convergence was achieved in 15 years.

Warning in setBevertonHolt.MizerParams(params): For the following species `erepro` has been increased to the smallest possible value: erepro[Whiting] = 0.000257; erepro[Haddock] = 0.000163; erepro[Cod] = 6.11e-05

Convergence was achieved in 12 years.

plotBiomassVsSpecies(params)

The matching did not work quite so well for Saithe, and it will become clear in a moment why that is. Let us plot the growth curves:

plotGrowthCurves(params, species_panel = TRUE)

It is clear to see that the growth is too low for all species, but particularly so for Saithe.

plotGrowthCurves(params, species = "Saithe")

Saithe takes almost twice as long to reach maturity as is predicted by the von Bertalanffy growth curve. So we need to do some tuning. Before we start with that, we’ll save the current state into a new variable.

params_start <- params

If you want to try things for yourself, you can load this example MizerParams object with

params_start <- params <- readRDS(url("https://bit.ly/3jSNAKF"))

The future

This gadget for tuning growth curve is actually only a particular instance of a more powerful shiny gadget with many more controls and many more tabs, which allows you to adjust almost any model parameter and investigate many different aspects of you model. For example there is a tab for looking at the diets of the various species and how they change with size, a tab to look at the causes of death at various sizes, a tab to compare the size distribution of the catches in the model to observed size distributions, …

I have been told that the full gadget, that you can start with

params <- tuneParams(params)

is overwhelming, even though it does not yet have all the tabs and controls that I envisage. The tuneParams() function therefore allows us to just select just the bits we need for a particular task. The tuneGrowth() gadget is actually just what you get when you tell tuneParams() that you want the “growth” control and the “Growth” and “Biomass” tabs.

params <- tuneParams(params, controls = c("growth"), 
               tabs = c("Growth", "Biomass"))

So I think that very soon we will have a large set of targeted tools similar to tuneGrowth() to facilitate various stages of the model tuning process, but also one very powerful combined tool for those of us who like the Swiss army knife approach.

Now, quite likely, when you try this with your own model you will run into problems. I am always eager to hear about those problems. Post about them in the comments or email them to me at gustav.delius@gmail.com.

Why it is a hard problem

We have a chicken and egg problem. The equilibrium abundance and size distributions of the fish are determined by their size-dependent growth and death rates. These rates in turn are determined by the abundance and size distribution of their prey and their predators. So we can’t determine the size distributions before we have determined the rates and we can’t determine the rates before we have determined the size distributions.

Because every species is a both prey and predator of fish of various species and sizes during their life, this is a highly coupled non-linear problem. If for example we use 100 size bins and 12 species, plus a resource spectrum, then we would have far over a thousand coupled nonlinear equations to solve simultaneously. That is not practical.

Rather than solving the equilibrium equations, another way to find a steady state is to simply evolve the time dynamics until the system settles down to a steady state. The problem with this approach is that the coexistence steady state of a size spectrum model has a very small region of attraction, so unless one starts with an initial state that is already very close to that coexistence steady state one will end up with extinctions.

The reason is a feedback loop: as the spawning stock biomass of a species grows, also its reproduction rate grows, leading to further growth of the spawning stock biomass and so on. Similarly as the spawning stock of another species declines, so does its reproduction rate, leading to further decline. In spite of moderating non-linear effects in the model, the general outcome is extinctions.

We can see the phenomenon in our North Sea example. If we simply run the dynamics, starting with the initial state set up by newMultispeciesParams(), first Sprat goes extinct, and Herring follows soon after. Just click the play button on the animation below.

params <- newMultispeciesParams(species_params = species_params,
                                gear_params = gear_params,
                                initial_effort = 1)

Because you have n != p, the default value for `h` is not very good.
Because the age at maturity is not known, I need to fall back to using
von Bertalanffy parameters, where available, and this is not reliable.
No ks column so calculating from critical feeding level.
Using z0 = z0pre * w_max ^ z0exp for missing z0 values.
Using f0, h, lambda, kappa and the predation kernel to calculate gamma.

sim <- project(params, t_max = 12)
animateSpectra(sim, power = 2)

The constant reproduction trick

So the trick is to cut the destabilising feedback loop by decoupling the reproductive rate from the spawning stock biomass. We do this by simply keeping the reproduction rate constant. The size spectrum model with constant reproduction turns out to be very stable and quickly approach a steady state, due to the smoothing effect of the feeding kernel. Once the steady state is found, we can simply adjust the reproductive efficiency of each species so that the steady state spawning stock produces the chosen reproduction rate. With that choice of the reproductive efficiency the steady state of the restricted dynamics is also the steady state of the full size spectrum model.

Here is the code that does that. Run the animation that it produces by clicking the play button.

params <- newMultispeciesParams(species_params = species_params,
                                gear_params = gear_params,
                                initial_effort = 1)

Because you have n != p, the default value for `h` is not very good.
Because the age at maturity is not known, I need to fall back to using
von Bertalanffy parameters, where available, and this is not reliable.
No ks column so calculating from critical feeding level.
Using z0 = z0pre * w_max ^ z0exp for missing z0 values.
Using f0, h, lambda, kappa and the predation kernel to calculate gamma.

# Keep reproduction constant at the initial level
params@species_params$constant_reproduction <- getRDD(params)
params <- setReproduction(params, RDD = "constantRDD")
# Run the dynamics with this constant reproduction
sim <- project(params, t_max = 15)
animateSpectra(sim, power = 2)

Mizer has a function called steady() that does the same as the above code, namely run to steady state with constant reproduction and then adjust the reproduction parameters, and then sets the resulting steady state as the initial state of the MizerParams object.

params <- newMultispeciesParams(species_params = species_params,
                                gear_params = gear_params,
                                initial_effort = 1)

Because you have n != p, the default value for `h` is not very good.
Because the age at maturity is not known, I need to fall back to using
von Bertalanffy parameters, where available, and this is not reliable.
No ks column so calculating from critical feeding level.
Using z0 = z0pre * w_max ^ z0exp for missing z0 values.
Using f0, h, lambda, kappa and the predation kernel to calculate gamma.

params <- steady(params)

Convergence was achieved in 18 years.

plotlySpectra(params, power = 2)

We now have a MizerParams object whose initial state is a steady state. Running a simulation starting with these initial conditions will show no change over time. For example the biomasses of all species will stay constant.

sim <- project(params, t_max = 5)
plotBiomass(sim)

But how do these biomasses compare to our observed biomasses?

plotBiomassObservedVsModel(params, ratio = FALSE)

They don’t agree at all, but that is no surprise. It would actually have been quite a coincidence if they did agree, because the newMultispeciesParams() function did not know how big our ecosystem is. It did not know that we wanted the biomasses in the entire North Sea. So initially the scale is arbitrary. The dynamics of the model are obviously independent of the scale of the system. So we have the freedom to change that scale. The calibrateBiomass() function chooses the scale so that the total biomass in the model agrees with the total observed biomass.

params <- calibrateBiomass(params) 
plotBiomassObservedVsModel(params, ratio = FALSE)

So now the total biomass is correct, but for some species the biomass in the model is too high, for others it is too low.

Actually, that the size spectrum is too low for Saithe and Cod and too high for Dab and Haddock might also be suspected from the fact that they are outliers in the size-spectrum plot above. We expect in a healthy ecosystem that the total spectrum roughly follows a power law, i.e., a straight line on the log-log plot. Those species currently spoil that.

So we want to lower the spectra of the species whose biomass is too high in the model and raise those of the species whose biomass is too low. This is what the matchBiomasses() function does.

params <- matchBiomasses(params)

Warning in setBevertonHolt.MizerParams(params): For the following species `erepro` has been increased to the smallest possible value: erepro[Sprat] = 0.574; erepro[Sandeel] = 0.0125; erepro[Cod] = 7.94e-05; erepro[Saithe] = 1.28e-05

plotlySpectra(params, power = 2, total = TRUE)

In fact, it has raised and lowered the spectra by exactly the factor needed to get the model biomasses to match the observed biomasses.

plotBiomassObservedVsModel(params, ratio = FALSE)

Of course this is not the end of the story, because just rescaling the size spectra by constants will not again produce a steady state. All species now experience a new prey distribution and a new predator distribution, so their growth and death rates have changed. We will have to again run the dynamics to steady state.

params <- steady(params)

Convergence was achieved in 12 years.

plotBiomassObservedVsModel(params, ratio = FALSE)

This has now spoiled the agreement between observed and model biomasses. But we can simply calibrate and match again and run to steady state again.

params <- params |> calibrateBiomass() |> matchBiomasses() |> steady()

Warning in setBevertonHolt.MizerParams(params): For the following species `erepro` has been increased to the smallest possible value: erepro[Cod] = 3.65e-05; erepro[Saithe] = 8.51e-06

Convergence was achieved in 10.5 years.

plotBiomassObservedVsModel(params, ratio = FALSE)

The discrepancies are now quite small. We could iterate to get them even smaller:

params <- params |> calibrateBiomass() |> matchBiomasses() |> steady() |>
    calibrateBiomass() |> matchBiomasses() |> steady()

Warning in setBevertonHolt.MizerParams(params): For the following species `erepro` has been increased to the smallest possible value: erepro[Cod] = 3.96e-05

Convergence was achieved in 7.5 years.

Convergence was achieved in 6 years.

plotBiomassObservedVsModel(params, ratio = FALSE)

So here is the picture of the steady state that matches the observed biomasses:

plotlySpectra(params, power = 2)

Actually, even the growth rates in the steady state match the von Bertalanffy growth curves pretty well:

plotGrowthCurves(params, species_panel = TRUE)

But this is a bit of a coincidence. Mizer has to choose values for the coefficient gamma of the ‘search volume’ for each species and for the coefficient ‘h’ of the maximum intake rate, both of which affect the growth rates. Because mizer has to choose them before it knows what the steady state prey distribution is for each species, it can not guarantee to choose them so as to give the correct growth rates in the steady state. You usually will have to retune them by hand. The mizerExperimental package provides a convenient shiny gadget that allows you to do that interactively, and I will talk about that in future blog posts.

Also remember that getting the steady state to agree with time-averaged observations is just the second stage in tuning a mizer model. Next you will want to tune the sensitivity to changes away from steady state. This will in particular involve tuning the density dependence in reproduction, among other things.

Summary of the recipe

We have seen how to proceed if you have your species parameters and gear parameters and also have averaged observed biomasses for each species that you want the steady state of your model to match:

1. Create a MizerParams object from your species parameters and gear parameters with newMultispeciesParams().

2. Find a coexistence steady state with steady().

3. Set the scale of the model to agree with the observed total biomass with calibrateBiomass(). This does not spoil the steady state.

4. Use matchBiomass() to move the size spectra of the species up or down to match the observed biomasses. This will spoil the steady state.

5. Go back to step 2 to again find the steady state. Iterate steps 2, 3 and 4 as often as you like to get the steady-state biomasses to agree as precisely with your observations as you like.

There are several interesting ways in which the above recipe can fail. I’ll blog about them in the future. But it will be more fun if you share your attempt at following the above recipe with your species parameters and your observed biomasses. Email me at gustav.delius@gmail.com. I can then use your example to explain what to do when problems arise.

Put your code into an R notebook

You probably have a jumble of R script files with the code for setting up your model and running your analysis. Now that you are done, it makes sense to organise this code a bit. A nice way of doing that is to open a new R notebook (the second entry on the “New File” menu in RStudio) and pasting your code into R chunks (you create R chunks with Ctrl-Alt-I). Then in between the R chunks you can put explanations of what the code is for. The result will look something like my example

In the example I modified the header to include a table of contents and to limit the height of the figures:

---
title: "Regulation of fish stocks without ..."
output: 
  html_notebook:
    toc: true
fig_height: 4
---

You will want to load all the libraries you need in a setup chunk like

knitr::opts_chunk$set(echo = TRUE)
library(mizer)
library(magrittr)
library(plotly)

The first line ensures that your code in the R chunks will be included when the notebook is typeset.

The explanatory text between the R chunks is using Markdown syntax. So for example you create section headers with #, headers of subsections with ## and so on. You can include LaTeX equations with the usual syntax. So $x^2$ produces the inline expression and $$x^2$$ produces the displayed equation For more information see the R Markdown Reference Guide and the R Markdown Cheat Sheet, both of which are accessible via ’Help -> Cheat Sheets` in RStudio.

If you have a rather large chunk of code, it may be a good idea to split it into smaller chunks, with more explanation in between. Just put your cursor at the place where you want to split the chunk and hit ‘Ctrl-Alt-I’.

The advice is to not be too perfectionist. Just put in enough explanations so that you yourself will still be able to remember in a year’s time what you were doing. You can always add more explanations for others later if there are requests. The point is that just by having your code out there, people will be more encouraged to engage with you if they are interested.

Put your notebook on GitHub

I think it is fair to say that GitHub has become the most popular place to share research code. So if you do not have an account there yet, sign up for free. Then create a new repository there for sharing your notebook.

If you have not used Git and GitHub before, it will really pay off in the long run for you to put in some time familiarising yourself with them and setting things up nicely. For a short introduction I recommend the chapter on Git and GitHub in the “R packages” book. Even though the book is about developing R packages, that chapter is not restricted to that use case. For a longer introduction, I recommend Happy Git and GitHub for the useR.

But if now you are in a hurry, you can also cheat and simply upload your R notebook and your data files using the “Add file” button on your new GitHub repository.

Publish your R notebook on RPubs

Now that your notebook is on GitHub, it is accessible to others, but GitHub does not display the typeset version of the notebook. For that you can use RPubs, which is a free hosting site for R notebooks.

RStudio makes publishing on RPubs very easy: When you click on “Preview”, RStudio will open a new window with the preview of your rendered notebook, and on that window at the top right there is a “Publish” button. Click that button and then make sure to choose “RPubs” (rather than RStudio Connect). You’ll be guided through the process.

Doing that with my example notebook leads to this. Note the “Code” button at the top right of the notebook on RPubs. It allows people to conveniently download your code.

Make it executable on mybinder.org

Now this step I think is amazing. It allows people to play with your code without having to install anything. Take a look at what this looks like for my example. Be a bit patient — after a few seconds you will see RStudio open in your browser. Click on “plankton-anchovy.nb.html” in the File pane and select “Open in Editor”. You will now be able to execute the code chunks as well as modify them at will. In fact, you can do anything that you can do in your local RStudio.

You have to only do three things to make this magic possible:

1. Add a file to you repository called “install.R” which contains only an install.packages() command for installing all the packages that your notebook needs. See my example. You will want to include at least

install.packages(c("mizer", "knitr", "rmarkdown"))

but extend the list with any other packages that you load with library() in your notebook. You can create this file straight on GitHub via the “Add file” button or you can do it locally and then push to GitHub.

2. Add a file to your repository called “runtime.txt” with yesterday’s date in the format r-yyyy-mm-dd. See this example This will have the effect of setting up the environment with the current version of all packages. That means that if the packages change in the future, this will not break your notebook. The reason I recommend using yesterday’s date rather than today’s is that this feature uses the MRAN snap shots and the snapshot for today may not yet be available.

3. Create the URL for your binder. It will have the form https://mybinder.org/v2/gh/your-github-username/your-repository-name/HEAD?urlpath=rstudio where you need to replace your-github-username/your-repository-name with your GitHub user name and repository name. For my example the URL is (https://mybinder.org/v2/gh/sizespectrum/plankton-anchovy/HEAD?urlpath=rstudio).

The first time you visit your binder URL, mybinder will take a long time to create a Docker image. When it is done, you will see an RStudio session running in your browser, with the files from your GitHub repository available in the Files pane. When people visit the URL after you they will not have to wait so long because mybinder.org will be able to use the Docker image to start the server more quickly.

Each time you make a change to your GitHub repository, mybinder will rebuild the Docker image the next time someone visits the URL. To save the first visitor from a long wait, you may want to visit the URL yourself each time you push a change to your GitHub repository.

Let the world know

You will probably want to put the URLs to your notebook on RPubs and to your binder into the README.md file of your GitHub repository. You will want to put the link to your GitHub repository into your published paper.

And then you will want to let your social networks know. If you twitter about it, include @mizer_model in your post. Also, consider writing a summary of your work for this blog.

Last but not least, please email mizer@sizespectrum.org. We’ll include your publication in the list of publications using mizer.

Species parameters

Let’s start with the species_params data frame. This holds species-specific parameters that are used by mizer to calculate physiological rates according to specific assumptions about the size-dependence of these rates. (The details do not concern us here, but you can find all the information on the help page of species_params(). These size-dependent rates are then stored as large arrays in the slots of the MizerParams object, to be efficiently used during model projections. But also the species parameters are stored, and can therefore be used to recalculate the rates when some species parameters change.

You can get the species parameters out of a MizerParams object in two ways, both giving identical results:

# Using function
sp <- species_params(params)
# Using @
spa <- params@species_params
# These are identical
identical(sp, spa)

[1] TRUE

The fact that these are identical is not surprising if you look at the code for the species_params() function:

species_params

function(params) {
    params@species_params
}
<bytecode: 0x5e5e9e269690>
<environment: namespace:mizer>

The function actually only contains one statement, which accesses the species_params slot using the @ notation.

The difference between the two notations becomes apparent only when you want to make a change to the species parameters. Let’s assume we want to change the h parameter for the first species in our example model. It currently has the value

species_params(params)$h[1]

[1] 18.20276

As you know, this parameter h is used to calculate the maximum intake rate as a power-law function of size: . So for example the maximum intake rate at the smallest size is

getMaxIntakeRate(params)[1, 1]

[1] 0.1820276

Now let’s increase the value of the h parameter using the @ notation:

params@species_params$h[1] <- 20

If we look at the maximum intake rate, we see that it has not changed:

getMaxIntakeRate(params)[1, 1]

[1] 0.1820276

All we have done is change the value in the species parameter data frame, but this did not trigger a recalculation of the maximum intake rate. We should instead have used

species_params(params)$h[1] <- 20

Take a look at the syntax, which is really a bit weird when compared to other programming languages. If you want to dig deeper into this, a good place to look is https://adv-r.hadley.nz/functions.html#replacement-functions.

This way of changing does indeed change the maximum intake rate:

getMaxIntakeRate(params)[1, 1]

[1] 0.2

The reason is clear if we look at the code:

`species_params<-`

function(params, value) {
    value <- validSpeciesParams(value)
    if (!all(value$species == params@species_params$species)) {
        stop("The species names in the new species parameter data frame do not match the species names in the model.")
    }
    params@species_params <- value
    suppressMessages(setParams(params))
}
<bytecode: 0x5e5e9efb9158>
<environment: namespace:mizer>

So three things actually happen when you change a species parameter via the setter function:

1. Your new value is checked for validity
2. Your new value is saved in the species_params slot
3. The other slots in the MizerParams object are updated by calling setParams().

Gear parameters

Similar comments apply to the gear parameters. The gear parameters are used by mizer to set up the catchability and selectivity arrays. You can find more details on the help page for setting fishing. You can get the current gear parameters in two equivalent ways:

# Using function
gp <- gear_params(params)
# Using @
gpa <- params@gear_params
# These are identical
identical(gp, gpa)

[1] TRUE

But if you want to actually change the selectivity or catchability by changing the gear parameters you need to use the functional form. Here is the current gear_params data frame in the example model:

gear_params(params)

                          gear species   sel_func knife_edge_size catchability
Sprat, Industrial   Industrial   Sprat knife_edge              13            1
Sandeel, Industrial Industrial Sandeel knife_edge               4            1
N.pout, Industrial  Industrial  N.pout knife_edge              23            1
Herring, Pelagic       Pelagic Herring knife_edge              99            1
Dab, Beam                 Beam     Dab knife_edge              21            1
Whiting, Otter           Otter Whiting knife_edge              75            1
Sole, Beam                Beam    Sole knife_edge              78            1
Gurnard, Otter           Otter Gurnard knife_edge              39            1
Plaice, Beam              Beam  Plaice knife_edge             105            1
Haddock, Otter           Otter Haddock knife_edge             165            1
Cod, Otter               Otter     Cod knife_edge            1606            1
Saithe, Otter            Otter  Saithe knife_edge            1076            1

If, for example, we want to reduce the catchability of Sprat with the Industrial gear to 0.8 we would do

gear_params(params)$catchability[1] <- 0.8

Note that changing gear parameters in the species_params data frame will not have the desired effect. You need to change them in the gear_params data frame.

Resource parameters

Not surprisingly, the same applies to the resource parameters. These are used to set up the size-dependent carrying capacity and replenishment rate for the resource. You should access them with

resource_params(params)

$kappa
[1] 1e+11

$lambda
[1] 2.133333

$r_pp
[1] 10

$n
[1] 0.6666667

$w_pp_cutoff
[1] 9.820907

and change them with, for example,

resource_params(params)$r_pp <- 4

Rate arrays

When you call newMultispeciesParams(), then mizer uses the information in species_params, gear_params and resource_params to set up various arrays that will later make it much faster to run simulations of the model. If you are not happy with how mizer fills these arrays, you can also change them directly. And again you can do that either with @ notation or without.

Let’s take the example of the maximum intake rate that we already discussed earlier. This is stored in the intake_max slot of the MizerParams object, as a two-dimensional array, with one row for each species and one column for each size bin. You can get at this way in the two equivalent ways:

identical(getMaxIntakeRate(params), params@intake_max)

[1] FALSE

You may wonder, why the function is called getMaxIntakeRate() rather than intake_max(), and I am wondering too. Naming things is difficult, and I now think that I made a bad choice when choosing those names. It gets worse when we now look at the syntax for changing intake_max.

We can either do it with the @ notation, for example

params@intake_max <- 2 * params@intake_max

or we can do it without @ notation

params <- setMaxIntakeRate(params, intake_max = 2 * getMaxIntakeRate(params))

This is ugly, and in future versions of mizer I think we will also allow

intake_max(params) <- 2 * intake_max(params)

But for now we are stuck with the functions that are all listed on the [help page] for setParams(). Note that these functions do not modify the params object in place, but create a new MizerParams object, which we then have to assign to a variable.

Again there are benefits in avoiding directly accessing the slot with @. These are:

1. The new value you assign is checked for validity. If you make a mistake in an assignment using @ you will not get any warning and instead will run into mysterious and cryptic error messages later.

2. The new value gets protected from automatically being overwritten when you make changes to other parameters.

We illustrate the second point with a simple example. Let’s set one entry in the metab slot, which holds the size-dependent metabolic rates, to a particular value.

params@metab[1, 1] <- 2
params@metab[1, 1]

[1] 2

Let us then make a totally unrelated change, say by changing the reproductive efficiency of the 5th species and look again at our entry in metab.

species_params(params)$erepro[5] <- 0.1
params@metab[1, 1]

[1] 0.02891793

The reason for this is that the change in the species parameter has triggered a recalculation of the rate arrays from the species parameters, overwriting our manual change.

Now let’s try the same with the proper way of changing the metabolic rate.

metab <- getMetabolicRate(params)
metab[1, 1] <- 2
params <- setMetabolicRate(params, metab = metab)

Now this will not get overwritten when some other parameter changes.

species_params(params)$erepro[5] <- 0.1
params@metab[1, 1]

[1] 2

The way that was done internally is by attaching a comment to the metab slot.

comment(params@metab)

[1] "set manually"

You could have chosen a more informative comment, for example

comment <- "Just changed the [1, 1] entry for test purposes."
params <- setMetabolicRate(params, metab = metab,
                           comment_metab = comment)

All that matters is that there is a comment. This also tells us how we can un-protect a slot so that it can be auto-computed from the species parameters again:

comment(params@metab) <- NULL

species_params(params)$erepro[5] <- 0.1
params@metab[1, 1]

[1] 0.02891793

Summary

We have seen how to change species parameters, gear parameters, resource parameters or other slots in a MizerParams object by using the appropriate functions. You can find a complete list of these functions in the mizer reference pages. We discussed how this avoids the pitfalls that arise when accessing slots directly with the @ notation. I hope this will be useful to you when you explore your own mizer model.

This blog post was motivated by a question by Leslie Garay-Narváez. Please keep the questions coming.

Stock-recruitment relationship

Usually, in a fisheries model, density dependence is specified via a stock-recruitment relationship, which gives a non-linear relationship between the spawning stock biomass and the recruitment. This relationship could, for example, be described by a Beverton-Holt curve. In that case for low spawning stock biomass the recruitment is assumed to be linearly proportional to the spawning stock biomass but for higher spawning stock biomass the curve flattens and asymptotically approaches a maximum recruitment rate that will never be exceeded, no matter how high the spawning stock biomass.

In a mizer model things are different because many of the causes of the density dependence in recruitment are explicitly modelled mechanistically, so don’t need to be imposed externally. These causes are:

1. The rate at which a spawner invests energy into reproduction depends on its food intake. So if there is a high abundance of fish and hence a lot of competition for prey, each spawner will produce fewer offspring.

2. Fish larvae are exposed to mortality from predation by larger fish. So the higher the abundance of larger fish, the higher the mortality and the fewer of the offspring will reach recruitment size.

3. The rate at which fish larvae grow, and hence the time they take to reach recruitment size, will depend on the availability of resources. If there are many fish larvae competing for limited resources, they will be exposed to mortality for longer, meaning fewer of them will reach recruitment size.

All these causes of density dependence are automatically taken into account in mizer, because growth depends on the abundance of prey and mortality depends on the abundance of predators. This dynamically generates fully multi-species stock-recruitment relationships.

However, there are other causes of density dependence besides the three listed above, and these are not explicitly modelled mechanistically by mizer. An example would be the limited carrying capacity of suitable spawning grounds and other spatial effects. The way such additional density dependencies can be taken into account in a mizer model is by specifying a non-linear relationship between the energy that the spawners invest into reproduction and the number of larvae this results in. It is this extra density-dependence that we will be concerned with in this blog post.

An example model

To make things concrete in this blog post we will use the example MizerParams object NS_params, included in mizer, that describes the fish community in the North Sea. Let’s have a quick look at that MizerParams object.

First we load the mizer package. We are using the currently latest version of mizer, version 2.2.1.

library(mizer)
packageVersion("mizer")

[1] '2.5.4.9011'

A MizerParams object comes with initial size spectra for all species and the resource. Let’s plot these for the North Sea params object.

params <- NS_params
plotSpectra(params, power = 2)

These initial spectra were chosen to describe a steady state of the model, meaning that if we project forward in time with constant fishing effort, the abundances stay constant. Let’s verify that.

sim <- project(NS_params, t_max = 20)
plotBiomass(sim)

We’ll use this model below

Beverton-Holt curves

By default, mizer uses a Beverton-Holt curve to describe the relationship between the rate at which energy is invested into reproduction and the rate at which offspring are produced.

To make this concrete, we’ll look at an example. I have written a function for the purpose of this blog post called plotBevertonHolt() which we can use to look at the Beverton-Holt curve for a given species in a model.

library(ggplot2)
plotBevertonHolt <- function(params, species) {
  select <- species_params(params)$species == species
  erepro <- species_params(params)$erepro[select]
  w0 <- params@w[params@w_min_idx[select]]
  E_R_ss <- getRDI(params)[select] / erepro * 2 * w0
  R_dd_ss <- getRDD(params)[select]
  R_max  <- species_params(params)$R_max[select]
  E_R <- seq(0, 2 * E_R_ss, length.out = 50)
  R_di = erepro * E_R / 2 / w0
  R_dd <- R_di / (1 + R_di / R_max)
  df <- melt(data.frame(E_R, R_dd, R_di, R_max), id.vars = "E_R")
  ggplot(df) +
    geom_line(aes(x = E_R, y = value, linetype = variable)) +
    geom_point(aes(x = E_R_ss, y = R_dd_ss), size = 3, color = "red") +
    ylim(NA, 1.1 * R_max) +
    ylab("Reproduction rate [eggs/year]") +
    xlab("Energy invested [g/year]")
}

We use that function to plot the Beverton-Holt curve for Gurnard in our example model

plotBevertonHolt(params, "Gurnard")

The solid line is the Beverton-Holt curve. The horizontal dashed line shows the maximum reproduction rate that the Beverton-Holt curve approaches for large and the dotted line shows the density-independent reproduction. The current reproduction rate is marked on the curve by a red dot. The curve shows us how the reproduction rate would change as the rate of investment into reproduction changes.

There are two parameters involved in determining this curve:

1. The reproductive efficiency erepro determines the slope of the curve when reproduction is low,

2. The maximum reproduction rate R_max determines the asymptote to which the curve levels off eventually.

Let us look up the values to which the reproductive efficiency erepro and the maximal recruitment rate R_max are set for Gurnard in this example model.

select_gurnard <- species_params(params)$species == "Gurnard"
species_params(params)[select_gurnard, c("erepro", "R_max")]

        erepro    R_max
Gurnard      1 1.65e+12

The reproduction level

We define the reproduction level as the ratio between the current reproduction rate and the maximum reproduction rate. Thus it is a number between 0 and 1. It is similar to the feeding level which in mizer is defined as the ratio between tha actual feeding rate and the maximum feeding rate.

Since version 2.2.1 of mizer there is a function getReproductionLevel() for calculating the reproduction level.

reproduction_level <- getReproductionLevel(params)
reproduction_level

     Sprat    Sandeel     N.pout    Herring        Dab    Whiting       Sole 
0.99074238 0.99987053 0.92829319 0.99198802 0.99578514 0.98718674 0.99643774 
   Gurnard     Plaice    Haddock        Cod     Saithe 
0.44189813 0.08022106 0.94443443 0.99993658 0.99767830 

We see that the reproduction level of Gurnard is 0.4418981, which agrees with the height of the red dot in relation to the maximum in the above plot of the Beverton Holt curve for Gurnard.

Most of the other species have unrealistically large reproduction levels, very close to 1. To see why that is bad let’s look for example at the curve for Cod:

plotBevertonHolt(params, "Cod")

This looks so strange because the actual reproduction rate is very close to the maximum reproduction rate, so that we are very far to the right of the Beverton-Holt curve where it is almost flat. The density dependence here is so strong that an increase or decrease in the energy invested into reproduction leads to almost no change in the reproduction. In other words, the spawning stock biomass has almost no effect on the number of eggs produced. That is not realistic, so before using this model we should reduce the reproduction level.

Changing the reproduction level

We could reduce the reproduction level by either reducing the reproductive efficiency erepro or by increasing R_max, but there is a subtlety. Given that the reproduction level is the ratio of the actual reproduction rate and the maximum reproduction rate R_max, we might think that doubling R_max would reduce the reproduction level by a factor of 2. Let’s check that in the example of Cod:

select_cod <- species_params(params)$species == "Cod"
params_changed_R_max <- params
species_params(params_changed_R_max)$R_max[select_cod] <- 
    2 * species_params(params_changed_R_max)$R_max[select_cod]
getReproductionLevel(params_changed_R_max)[select_cod]

      Cod 
0.9998732 

The reproduction level has changed very little. The reason is that besides raising the maximum reproduction, we have also changed the Beverton-Holt curve and the actual reproduction has also increased.

The other problem with changing either erepro or R_max in isolation is that we will move away from the steady state. We can see that by projecting our changed params object forward in time:

sim_changed_R_max <- project(params_changed_R_max, t_max = 20)
plotBiomass(sim_changed_R_max, species = "Cod")

This is bad news if we had carefully calibrated our model to observed biomasses for example.

What we need to do is change both erepro and R_max at the same time in such a way that the actual reproduction does not change. This is what the function setBevertonHolt() does.

params2 <- setBevertonHolt(params, reproduction_level = c(Cod = 0.5))
plotBevertonHolt(params2, "Cod")

Warning in geom_point(aes(x = E_R_ss, y = R_dd_ss), size = 3, color = "red"): All aesthetics have length 1, but the data has 150 rows.
ℹ Please consider using `annotate()` or provide this layer with data containing
  a single row.

Warning: Removed 23 rows containing missing values or values outside the scale range
(`geom_line()`).

To see more clearly what has happened, we extend our plotBevertonHolt() function to show both the old and the new Beverton-Holt curve in the same graph.

plotBevertonHolt2 <- function(params, params2, species) {
  select <- species_params(params)$species == species
  erepro <- species_params(params)$erepro[select]
  w0 <- params@w[params@w_min_idx[select]]
  E_R_ss <- getRDI(params)[select] / erepro * 2 * w0
  R_dd_ss <- getRDD(params)[select]
  E_R <- seq(0, 2 * E_R_ss, length.out = 50)
  
  R_max  <- species_params(params)$R_max[select]
  R_di = erepro * E_R / 2 / w0
  R_dd <- R_di / (1 + R_di / R_max)
  df <- melt(data.frame(E_R, R_dd, R_di, R_max), id.vars = "E_R")
  df$Model <- "Model 1"
  
  erepro <- species_params(params2)$erepro[select]
  R_max  <- species_params(params2)$R_max[select]
  R_di = erepro * E_R / 2 / w0
  R_dd <- R_di / (1 + R_di / R_max)
  df2 <- melt(data.frame(E_R, R_dd, R_di, R_max), id.vars = "E_R")
  df2$Model <- "Model 2"
  
  ggplot(rbind(df, df2)) +
    geom_line(aes(x = E_R, y = value, linetype = variable,
                  colour = Model, size = Model)) +
    geom_point(aes(x = E_R_ss, y = R_dd_ss), size = 3, color = "red") +
    ylim(NA, 1.1 * R_max) +
    ylab("Reproduction rate [eggs/year]") +
    xlab("Energy invested [g/year]") +
    labs(linetype = "", size = "R_max", colour = "R_max") +
    scale_size_manual(values = c(0.5, 1)) +
    scale_colour_manual(values = c("blue", "black")) +
    scale_linetype_manual(values = c("solid", "dashed", "dotted"))
}

plotBevertonHolt2(params, params2, "Cod")

Warning: Using `size` aesthetic for lines was deprecated in ggplot2 3.4.0.
ℹ Please use `linewidth` instead.

Warning in geom_point(aes(x = E_R_ss, y = R_dd_ss), size = 3, color = "red"): All aesthetics have length 1, but the data has 300 rows.
ℹ Please consider using `annotate()` or provide this layer with data containing
  a single row.

Warning: Removed 72 rows containing missing values or values outside the scale range
(`geom_line()`).

This shows that the red dot that marks the steady state value lies on both the old (blue) and the new (black) curve. This was achieved by lowering erepro at the same time as increasing R_max. The old values were

species_params(params)[select_cod, c("erepro", "R_max")]

    erepro    R_max
Cod      1 8.26e+09

and the new values are

species_params(params2)[select_cod, c("erepro", "R_max")]

          erepro       R_max
Cod 0.0001270809 16549691091

So the change in the reproduction level has been achieved without a change to the steady state. We can verify this:

sim2 <- project(params2, t_max = 20)
plotBiomass(sim2)

Sensitivity to fishing

The reason why it matters what level of density dependence in reproduction is chosen for the model is that it affects the sensitivity of the model to perturbations, for example to changes in fishing pressure. To illustrate this we will plot the sustainable fishing yield as a function of fishing mortality.

The mizerExperimental package contains a function plotYieldVsF() that creates such a Yield versus F plot. The mizerExperimental package is updated frequently and thus it is a good idea to install the latest version

remotes::install_github("sizespectrum/mizerExperimental")

library(mizerExperimental)
packageVersion("mizerExperimental")

[1] '2.5.3.9000'

Here is the Yield versus F plot for Cod in the old model with the high reproduction level:

plotYieldVsF(params, "Cod")

This plot shows the sustainable fishing yields at different levels of imposed fishing mortality. This is calculated by running the model with each level of fishing mortalit for long enough to reach a steady state. Then the yield in that steady state is plotted. For high fishing mortality the stock should collapse and the yield in the steady state should therefore be very low at high fishing mortalities. However in this model we see that the stock can sustain unrealistically high fishing mortalities without collapsing.

For the new model, with a reproduction level of 1/2, the curve looks more realistic:

plotYieldVsF(params2, "Cod")

In this model at a fishing mortality of 2 per year the stock collapses completely, leading to zero yield.

More about setBevertonHolt()

As you can see from the help page of setBevertonHolt(), you can adjust the density dependence in the reproduction of several species at once. For example we can try to set the reproduction level to 1/2 for all species:

params3 <- setBevertonHolt(params, reproduction_level = 0.5)

Warning in setBevertonHolt.MizerParams(params, reproduction_level = 0.5): The following species require an unrealistic value greater than 1 for `erepro`: Gurnard, Plaice

This gave us a warning. Let’s take a look at plaice, for example:

select_plaice <- species_params(params)$species == "Plaice"
species_params(params3)[select_plaice, c("erepro", "R_max")]

         erepro        R_max
Plaice 1.842465 6.556383e+13

We see that to achieve a reproduction level of 1/2 while maintaining plaice at its initial abundance, it would need a very high reproductive efficiency.

Let’s see what happens if we try to force the reproductive efficiency to a more realistic level of 0.1:

params3 <- setBevertonHolt(params, erepro = c("Plaice" = 0.1))

Warning in setBevertonHolt.MizerParams(params, erepro = c(Plaice = 0.1)): For the following species `erepro` has been increased to the smallest possible value: erepro[Plaice] = 0.921

species_params(params3)[select_plaice, c("erepro", "R_max")]

          erepro R_max
Plaice 0.9212325   Inf

To understand what is going on here we have to recall that setBevertonHolt() will not make changes that would change the abundances in the model. The level of abundance for plaice specified in the model can only be achieved with a high reproductive efficiency.

If we want to force the change in erepro we can do that but have to accept that the steady state will change:

species_params(params3)$erepro[select_plaice] <- 0.1
sim3 <- project(params3, t_max = 20)
plotlyBiomass(sim3)

We see that this change also affects the abundances of the other species. I think this nicely illustrates the differences of adjusting reproduction parameters with setBevertonHolt() as opposed to changing them directly.

Turning off density dependence

We can also set the reproduction level to 0.

params4 <- setBevertonHolt(params, reproduction_level = 0)

This does not mean that we have set reproduction to 0, but rather that we have turned off the density dependence in reproduction. In other words, the reproduction level is zero because we have set the maximum reproduction rate to infinity.

species_params(params4)$R_max

 [1] Inf Inf Inf Inf Inf Inf Inf Inf Inf Inf Inf Inf

I want to stress that the fact that we have turned off all the density dependence in reproduction does not mean that the stock-recruitment relationship is linear. All the density dependencies mentioned at the start of this blog post are still operating. We are simply not imposing any additional density dependence that is not already captured by the model.

The built-in density dependencies are enough to keep the model stable, in the sense that if we make changes to the initial abundances, after a time the system will settle down to a steady state again:

params5 <- params4
initialN(params5) <- 4 * initialN(params4)
sim5 <- project(params5)
plotlyBiomass(sim5)

Summary

We have discussed that in the mizer model many sources of density dependence in recruitment are captured automatically but that one can take into account additional density dependence in recruitment by imposing a density dependence on the reproduction, by which we mean to impose a non-linear relation between the rate at which energy is invested into reproduction and the rate at which offspring are produced.

We looked at some Beverton-Holt curves which are used in mizer by default to encode this non-linearity. These curves are specified by two parameters: the reproductive efficiency erepro and the maximum reproduction rate R_max. The setBevertonHolt() function allows us to change both of these parameters together without changing the current reproduction rate. It only affects the behaviour of the model when it is perturbed away from the current state.

Therefore the setBevertonHolt() function allows us to control the sensitivity of the model to perturbations, like changes in fishing for example, without changing the steady-state properties. This allows a two-stage approach to calibrating a mizer model: in a first step one calibrates the steady state properties to reproduce averaged observations, like growth rates and biomasses or yields of species for example. In a second step on the calibrates the sensitivity of the model, for example by matching it to time series observations.