Skip to contents

Using and adapting the mizer extension template

Source: vignettes/mizerExtensionTemplate.Rmd
mizerExtensionTemplate.Rmd

What this package is

mizerExtensionTemplate is a working mizer extension package that you can clone and adapt. Every line of code is commented to explain what is being done and why. Read the source files alongside this vignette.

For the full conceptual background see:

The extension at a glance

mizerExtensionTemplate adds three things to a standard mizer model:

Mechanism What it adds Where
setExtEncounter() Fixed allometric extra food constructor.R
setExtMort() Fixed background mortality constructor.R
projectEncounter S3 method Seasonal encounter multiplier rate-methods.R
setComponent("plankton") Dynamical plankton spectrum constructor.R + component-functions.R
getBiomass S3 methods Includes plankton in output generic-methods.R
Bundled data object example_params ready to use data/, R/data.R, .onLoad

Bundled example model

The package ships a ready-made example_params object — a three-species (Sprat, Herring, Cod) model built with newExtensionTemplateParams(). It is stored in data/example_params.rda and lazy-loaded by R, but the .onLoad hook replaces the plain binding with an active binding so that every access returns an object with the correct S4 extension class:

class(example_params)   # mizerExtensionTemplate, not plain MizerParams
#> [1] "mizerExtensionTemplate"
#> attr(,"package")
#> [1] "mizerExtensionTemplate"
getBiomass(example_params)  # Plankton entry is present
#>        Sprat      Herring          Cod     Plankton 
#> 1.630305e+08 9.125316e+07 1.494402e+08 2.673020e+12

You can use it directly without calling newExtensionTemplateParams():

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

Quick start (build your own) 

params <- newExtensionTemplateParams(NS_species_params)
sim    <- project(params, t_max = 10)
plotBiomass(sim)   # Plankton column appears automatically
#> Warning in plotDataFrame(plot_dat, params, xlab = "Year", ylab = y_label, :
#> missing legend in params@linecolour, some groups won't be displayed
#> Warning: Removed 11 rows containing missing values or values outside the scale range
#> (`geom_line()`).

How the seasonal encounter works

The seasonal multiplier peaks at t = 0.25 (quarter-year) and troughs at t = 0.75. With the default amplitude of 0.2 the encounter rate varies by ±20 % around its annual mean.

params_s <- newExtensionTemplateParams(NS_species_params, season_amplitude = 0.4)
enc_t0   <- getEncounter(params_s, t = 0)    # multiplier = 1.0
enc_t025 <- getEncounter(params_s, t = 0.25) # multiplier = 1.4
range(enc_t025 / enc_t0, na.rm = TRUE)
#> [1] 1.4 1.4

This seasonal effect is implemented in projectEncounter.mizerExtensionTemplate() (rate-methods.R). It calls NextMethod() to get the base encounter rate (including the plankton contribution), then multiplies by the seasonal factor. Using a project* method rather than setRateFunction() means another extension package can also modify the encounter rate without conflict.

How the plankton component works

The plankton is a vector spectrum stored on the full resource size grid. At each time step:

  1. planktonEncounter() adds the plankton encounter contribution to getEncounter() by presenting the plankton as an extra resource.
  2. planktonDynamics() updates the plankton by solving the ODE dP/dt = r(K − P) − m·P analytically over the time step, where m is the predation mortality on the plankton spectrum.
plotDiet(params, species = "Cod")

Adapting this template for your extension

  1. Rename the package: search and replace mizerExtensionTemplate → your package name throughout all files, including DESCRIPTION, the R files, NAMESPACE, and this vignette.

  2. Decide: metadata-only or dispatching?

    • Metadata-only (like mizerStarvation): delete mizerExtensionTemplate-class.R, remove the setClass() calls, and remove the coerceToExtensionClass() call at the end of the constructor. Keep params@extensions <- getRegisteredExtensions().
    • Dispatching (like mizerShelf): keep everything and define S3 methods for the generics you need to override.

  3. Remove mechanisms you don’t need: each of the five mechanisms in constructor.R is independent. Delete the blocks that do not apply to your extension.

  4. Replace the plankton component with your own component, or remove setComponent() entirely if you don’t need a dynamical state variable.

  5. Run devtools::document() to regenerate NAMESPACE from the roxygen2 tags, then devtools::test() and devtools::check() before publishing.

Checklist for dispatching extension authors