plotSpectra: Plot abundance and biomass spectra
In mizer: Dynamic Multi-Species Size Spectrum Modelling

plotSpectra

R Documentation

Plot abundance and biomass spectra

Description

plotSpectra() plots either a number density or a biomass density, either with respect to size or with respect to logarithmic size. Those two choices are made with the biomass and per_log_size arguments. When called with a MizerSim object, the abundance is averaged over the specified time range (a single value for the time range can be used to plot a single time step). When called with a MizerParams object the initial abundance is plotted. With size_axis = "l", densities are converted from per unit weight to per unit length; densities with respect to logarithmic size are instead converted between logarithmic weight and logarithmic length intervals.

Usage

plotSpectra(
  object,
  species = NULL,
  wlim = c(NA, NA),
  llim = c(NA, NA),
  ylim = c(NA, NA),
  power = NULL,
  biomass = NULL,
  per_log_size = NULL,
  total = FALSE,
  resource = TRUE,
  background = TRUE,
  highlight = NULL,
  log_x = TRUE,
  log_y = TRUE,
  log = NULL,
  size_axis = c("w", "l"),
  return_data = FALSE,
  ...
)

Arguments

`object`	An object of class MizerSim or MizerParams.
`species`	The species to be selected. Optional. By default all target species are selected. A vector of species names, or a numeric vector with the species indices, or a logical vector indicating for each species whether it is to be selected (TRUE) or not.
`wlim`	A numeric vector of length two providing lower and upper limits for the w axis. Use NA for the default: the lower default is `min(params@w) / 100` when `resource = TRUE` (to show some resource below the fish grid) or `min(params@w)` when `resource = FALSE`; the upper default is `max(params@w_full)`. Data is filtered to this range and the axis limits are set accordingly.
`llim`	A numeric vector of length two providing lower and upper limits for the length axis when `size_axis = "l"`. Use `NA` to auto-scale to the data range. Data is filtered to this range and the axis limits are set accordingly.
`ylim`	A numeric vector of length two providing lower and upper limits for the y axis. Use NA to auto-scale to the data range. Values below 1e-20 are always filtered out from the data regardless of `ylim[1]`. Data above `ylim[2]` is filtered and the upper axis limit is set accordingly.
`power`	The abundance is plotted as the number density times the weight raised to `power`. An alternative to the `biomass` and `per_log_size` arguments, with which it must agree if they are given as well; see Details. The default is `power = 1`, the biomass density.
`biomass`	Whether to plot the biomass density (`TRUE`, the default) or the number density (`FALSE`).
`per_log_size`	Whether to plot the density with respect to logarithmic size (`TRUE`) or with respect to size (`FALSE`, the default).
`total`	A boolean value that determines whether the total is plotted as well. The total is the total of everything the object holds — every species and the resource — whatever is drawn, so it does not move when `species`, `resource` or `background` change. Default is FALSE.
`resource`	A boolean value that determines whether resource is included. Default is TRUE.
`background`	A boolean value that determines whether background species are included. Ignored if the model does not contain background species. Default is TRUE.
`highlight`	Name or vector of names of the species to be highlighted by being plotted with thicker lines.
`log_x`	If `TRUE` (default), use a log10 x-axis.
`log_y`	If `TRUE` (default), use a log10 y-axis.
`log`	Character string specifying which axes should use log10 scales, in the same form as the base `plot()` argument. For example, `"x"`, `"y"`, `"xy"` or `""`. If supplied, this overrides `log_x` and `log_y`.
`size_axis`	Whether to plot size as weight (`"w"`, default) or length (`"l"`), using the allometric weight-length relationship. Spectrum densities and their units are transformed to match the chosen axis.
`return_data`	A boolean value that determines whether the formatted data used for the plot is returned instead of the plot itself. Default value is FALSE
`...`	Further arguments used by only some of the methods: For `MizerSim` methods: `time_range`: The time range (either a vector of values, a vector of min and max time, or a single value) to average the abundances over. Default is the final time step. `geometric_mean`: If `TRUE` then the average of the abundances over the time range is a geometric mean instead of the default arithmetic mean.

Details

The plotted quantity is the number density multiplied by w^power, where the power is the sum of the two choices above: a biomass density carries one factor of the weight and a density with respect to logarithmic size carries another:

	`per_log_size = FALSE`	`per_log_size = TRUE`
`biomass = FALSE`	`power = 0`	`power = 1`
`biomass = TRUE`	`power = 1`	`power = 2`

The power argument can still be given instead, and is the only way to ask for a power that is not the sum of the two flags. But note that power on its own does not distinguish the two entries with power = 1: it is taken to mean the biomass density with respect to weight, which is what determines the y-axis label and the Jacobian used for a length axis. Supplying power together with a flag that contradicts it is an error.

The log_x argument only controls how the size axis is displayed; it does not change the density on the y-axis. In particular, showing weight on a logarithmic axis does not by itself convert a density per unit weight into a density per logarithmic weight interval. That choice is made with per_log_size, and the conversion from weight to length then uses the logarithmic Jacobian, irrespective of the value of log_x.

plotlySpectra() is the interactive plotly version. To compare spectra from two objects use plotSpectra2(). To show relative differences use plotSpectraRelative().

Value

A ggplot2 object, unless return_data = TRUE, in which case a data frame with the four variables 'w' (or 'l' if size_axis = "l"), 'value', 'Species', 'Legend' is returned. plotlySpectra() returns a plotly object.

Examples


params <-  NS_params
sim <- project(params, effort=1, t_max=20, t_save = 2, progress_bar = FALSE)
plotSpectra(sim)
plotSpectra(sim, wlim = c(1e-6, NA))
plotSpectra(sim, time_range = 10:20)
plotSpectra(sim, time_range = 10:20, biomass = FALSE)
plotSpectra(sim, species = c("Cod", "Herring"), per_log_size = TRUE)
plotSpectra(sim, species = c("Cod", "Herring"), size_axis = "l")

# Returning the data frame
fr <- plotSpectra(sim, return_data = TRUE)
str(fr)

mizer documentation built on Aug. 31, 2026, 5:08 p.m.