Animate size-dependent quantities through time

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.

Value

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

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.

Examples

# \donttest{
# 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))

# }