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"),
  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

For an array that holds a density, whether to animate it per logarithmic size (TRUE) rather than per size (FALSE). The default, NULL, animates the density as it stands. Unlike size_axis this needs no weight-length relationship, so the ArrayTimeByResourceBySize method takes it too. An error for an array that does not hold a density. The MizerSim method has its own per_log_size, described below.

total

A boolean value that determines whether the total over all selected species is plotted as an additional trace called "Total". 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).
per_log_size: Whether to animate the density with respect to logarithmic size (TRUE) or with respect to size (FALSE, the default).
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 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 species total can be added via the background and total arguments.
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))

# }