Skip to contents

Animate size-dependent quantities through time

Source: R/ArrayTimeBySpeciesBySize-class.R, R/animateSpectra.R
animate.Rd

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

Usage

# S3 method for class 'ArrayTimeBySpeciesBySize'
animate(
  x,
  species = NULL,
  time_range = NULL,
  log_x = TRUE,
  wlim = c(NA, NA),
  ylim = c(NA, NA),
  log_y = TRUE,
  total = FALSE,
  background = TRUE,
  frame_duration = 500,
  transition_duration = frame_duration,
  easing = "linear",
  ...
)

animate(x, ...)

# S3 method for class 'MizerSim'
animate(
  x,
  species = NULL,
  time_range = NULL,
  log_x = TRUE,
  log_y = TRUE,
  wlim = c(NA, NA),
  ylim = c(NA, NA),
  power = 1,
  total = FALSE,
  resource = TRUE,
  background = TRUE,
  frame_duration = 500,
  transition_duration = frame_duration,
  easing = "linear",
  ...
)

animateSpectra(sim, ...)

Arguments

x

A MizerSim or ArrayTimeBySpeciesBySize object.

species

Name or vector of names of the species to be plotted. By default all species are plotted.

time_range

The time range to animate over. Either a vector of time values to include, or a length-two vector giving the min and max of the range. Default is the entire time range of x.

log_x

If TRUE (default), use a log10 x-axis for body size.

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.

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.

log_y

If TRUE (default), use a log10 y-axis.

total

A boolean value that determines whether the total over all selected species is plotted as an additional trace called "Total". Default is FALSE.

background

A boolean value that determines whether background species are included. Ignored if the model does not contain background species. Default is TRUE.

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".

...

Additional arguments passed to the method.

power

The abundance is plotted as the number density times the weight raised to power. The default power = 1 gives the biomass density, whereas power = 2 gives the biomass density with respect to logarithmic size bins. Only applies to MizerSim.

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. Only applies to MizerSim.

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 power argument controls whether the y-axis shows number density (power = 0), biomass density (power = 1, default), or biomass density in logarithmic size bins (power = 2). 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.

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

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

See also

Other plotting functions: addPlot(), plot, plotBiomass(), plotDiet(), plotFMort(), plotFeedingLevel(), plotGrowthCurves(), plotMizerParams, plotMizerSim, plotPredMort(), plotSpectra(), plotYield(), plotYieldGear(), plotting_functions

Examples

# \donttest{
# Animate biomass density spectra, showing only sizes above 0.1 g
animate(NS_sim, power = 2, wlim = c(0.1, NA), time_range = 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"))


# }