animate: Animate size-dependent quantities through time
In mizer: Dynamic Multi-Species Size Spectrum Modelling

animate

R Documentation

Animate size-dependent quantities through time

Description

Creates an interactive plotly animation in which a play button steps through time, drawing one line per species at each frame.

Usage

animate(
  x,
  species = NULL,
  log_x = TRUE,
  log_y = TRUE,
  log = NULL,
  wlim = c(NA, NA),
  llim = c(NA, NA),
  ylim = c(NA, NA),
  tlim = c(NA, NA),
  size_axis = c("w", "l"),
  per_log_size = NULL,
  total = FALSE,
  background = TRUE,
  frame_duration = 500,
  transition_duration = frame_duration,
  easing = "linear",
  ...
)

animateSpectra(sim, ...)

Arguments

`x`	A `MizerSim`, `ArrayTimeBySpeciesBySize` or `ArrayTimeByResourceBySize` object.
`species`	Name or vector of names of the species to be plotted. By default all species are plotted. Not used by the `ArrayTimeByResourceBySize` method, which warns if it is set.
`log_x`	If `TRUE` (default), use a log10 x-axis for body size.
`log_y`	If `TRUE` (default), use a log10 y-axis.
`log`	A character string specifying which axes to log-transform: `"x"`, `"y"`, `"xy"` or `""`. If supplied, this overrides `log_x` and `log_y`.
`wlim`	A numeric vector of length two providing lower and upper limits for the body-size (x) axis. Use `NA` to refer to the existing minimum or maximum.
`llim`	A numeric vector of length two providing lower and upper limits for the length (x) axis when `size_axis = "l"`. Use `NA` to refer to the existing minimum or maximum.
`ylim`	A numeric vector of length two providing lower and upper limits for the value (y) axis. Use `NA` to refer to the existing minimum or maximum. Limits are applied as Plotly axis ranges, so points outside the limits are clipped by the viewport rather than removed from the animation frames.
`tlim`	A numeric vector of length two providing lower and upper limits for the animated time window, e.g. `c(1997, 2007)`. Use `NA` to apply no limit at that end. Default is `c(NA, NA)`.
`size_axis`	Whether to plot size as weight (`"w"`, default) or length (`"l"`), using the allometric weight-length relationship of each species, or of the resource, see `resource_params()`. Number and biomass densities are transformed to match the chosen axis.
`per_log_size`	Whether to animate a density per logarithmic size (`TRUE`) rather than per size (`FALSE`). Unlike `size_axis` this needs no weight-length relationship, so the `ArrayTimeByResourceBySize` method takes it too. The two kinds of `x` read the default `NULL` differently. For an array it means animating the density as it stands, and asking for it on an array that does not hold a density is an error. For a `MizerSim` it means `FALSE` unless `power` says otherwise, since there the argument chooses the plotted quantity together with `biomass` and `power`, in the same way as in `plotSpectra()`.
`total`	A boolean value that determines whether the total is plotted as an additional trace called `"Total"`. The total is the total of everything the object holds, whatever is drawn: for a `MizerSim` every species and the resource, for an array every species it holds. Default is `FALSE`. Not used by the `ArrayTimeByResourceBySize` method, which warns if it is set.
`background`	A boolean value that determines whether background species are included. Ignored if the model does not contain background species. Default is `TRUE`. Not used by the `ArrayTimeByResourceBySize` method, which warns if it is set.
`frame_duration`	Duration in milliseconds for which each saved frame is displayed. Default is 500.
`transition_duration`	Duration in milliseconds of the interpolation between frames. Use `transition_duration = 0` to step directly from one saved frame to the next. Default is `frame_duration`.
`easing`	The Plotly easing function to use when interpolating between frames. Default is `"linear"`. Available options are `"linear"`, `"quad"`, `"cubic"`, `"sin"`, `"exp"`, `"circle"`, `"elastic"`, `"back"`, `"bounce"`, and each of those with suffix `"-in"`, `"-out"`, or `"-in-out"` appended, for example `"cubic-in-out"`.
`...`	Further arguments used by only some of the methods: For `MizerSim` methods: `biomass` Whether to animate the biomass density (`TRUE`, the default) or the number density (`FALSE`). `power` The abundance is plotted as the number density times the weight raised to `power`. An alternative to `biomass` and `per_log_size`, with which it must agree if they are given as well. See `plotSpectra()` for details. `resource` A boolean value that determines whether resource is included. If `TRUE`, the resource spectrum is plotted as an additional trace called `"Resource"`. Default is `TRUE`.
`sim`	A `MizerSim` object.

Details

The function dispatches on the class of x:

MizerSim — animates the community abundance spectra (number density or biomass density vs body size). Resource, background species, and a community total can be added via the resource, background, and total arguments. The total is the total of everything the model holds, whatever is drawn. The biomass and per_log_size arguments choose the plotted quantity in the same way as in plotSpectra(), and the power argument is available as the same alternative to them. Both axes are log10 by default and can each be switched to linear with log_x = FALSE or log_y = FALSE.
ArrayTimeBySpeciesBySize — animates any per-species, size-resolved quantity returned by a MizerSim accessor, such as getFMort(), getFeedingLevel(), or getPredMort(). Both axes are log10 by default and can each be switched to linear with log_x = FALSE or log_y = FALSE. Background species and a total can be added via the background and total arguments. The total is the total over every species the array holds, whatever is drawn.
ArrayTimeByResourceBySize — animates the size-resolved resource quantity returned by NResource() on a MizerSim object. There is only a single resource spectrum, so species, total and background do nothing and warn if set.

Species linecolours and linetypes follow params@linecolour and params@linetype.

animateSpectra() is retained as a backward-compatible alias.

Value

A plotly object with one animated line trace per plotted group. Use the play button or the slider to step through time.

Examples


# Animate biomass density spectra, showing only sizes above 0.1 g
animate(NS_sim, power = 2, wlim = c(0.1, NA), tlim = c(1997, 2007))

# Animate fishing mortality through time
animate(getFMort(NS_sim))

# Animate feeding level for two species only
animate(getFeedingLevel(NS_sim), species = c("Cod", "Herring"))

# Animate the resource spectrum
animate(NResource(NS_sim))

mizer documentation built on Aug. 24, 2026, 9:08 a.m.