Plot improvements

NAMESPACE

@@ -125,9 +125,14 @@ S3method(plot,ArrayTimeBySpecies)
 S3method(plot,ArrayTimeBySpeciesBySize)
 S3method(plot,MizerParams)
 S3method(plot,MizerSim)
+S3method(plot2,ArraySpeciesBySize)
+S3method(plot2,ArrayTimeBySpecies)
+S3method(plot2,ArrayTimeBySpeciesBySize)
 S3method(plotBiomass,MizerSim)
 S3method(plotBiomassObservedVsModel,MizerParams)
 S3method(plotBiomassObservedVsModel,MizerSim)
+S3method(plotCDF,MizerParams)
+S3method(plotCDF,MizerSim)
 S3method(plotDiet,MizerParams)
 S3method(plotDiet,MizerSim)
 S3method(plotFMort,MizerParams)
@@ -138,6 +143,9 @@ S3method(plotGrowthCurves,MizerParams)
 S3method(plotGrowthCurves,MizerSim)
 S3method(plotPredMort,MizerParams)
 S3method(plotPredMort,MizerSim)
+S3method(plotRelative,ArraySpeciesBySize)
+S3method(plotRelative,ArrayTimeBySpecies)
+S3method(plotRelative,ArrayTimeBySpeciesBySize)
 S3method(plotSpectra,MizerParams)
 S3method(plotSpectra,MizerSim)
 S3method(plotYield,MizerSim)
@@ -147,6 +155,7 @@ S3method(plotYieldObservedVsModel,MizerSim)
 S3method(plotly::ggplotly,ArraySpeciesBySize)
 S3method(plotly::ggplotly,ArrayTimeBySpecies)
 S3method(plotly::ggplotly,ArrayTimeBySpeciesBySize)
+S3method(plotly::ggplotly,mizer_plot)
 S3method(print,ArraySpeciesBySize)
 S3method(print,ArrayTimeBySpecies)
 S3method(print,ArrayTimeBySpeciesBySize)
@@ -396,26 +405,37 @@ export(newSingleSpeciesParams)
 export(newTraitParams)
 export(noRDD)
 export(other_params)
+export(plot2)
 export(plotBiomass)
 export(plotBiomassObservedVsModel)
+export(plotCDF)
+export(plotCDF2)
 export(plotDataFrame)
 export(plotDiet)
 export(plotFMort)
 export(plotFeedingLevel)
 export(plotGrowthCurves)
 export(plotM2)
 export(plotPredMort)
+export(plotRelative)
 export(plotSpectra)
+export(plotSpectra2)
+export(plotSpectraRelative)
 export(plotYield)
 export(plotYieldGear)
 export(plotYieldObservedVsModel)
 export(plotlyBiomass)
 export(plotlyBiomassObservedVsModel)
+export(plotlyCDF)
+export(plotlyCDF2)
+export(plotlyDiet)
 export(plotlyFMort)
 export(plotlyFeedingLevel)
 export(plotlyGrowthCurves)
 export(plotlyPredMort)
 export(plotlySpectra)
+export(plotlySpectra2)
+export(plotlySpectraRelative)
 export(plotlyYield)
 export(plotlyYieldGear)
 export(plotlyYieldObservedVsModel)

NEWS.md

@@ -112,6 +112,10 @@ individual variability in growth to be modelled.
   `ArrayTimeBySpeciesBySize`. An `animate()` method allows interactive
   playback.
 
+- Subsetting an `ArrayTimeBySpeciesBySize` object returns an
+  `ArraySpeciesBySize` object when a single time is selected, and an
+  `ArrayTimeBySpecies` object when a single size is selected.
+
 - New `ggplotly()` methods for `ArraySpeciesBySize`, `ArrayTimeBySpecies`, and
   `ArrayTimeBySpeciesBySize` convert the `ggplot2` output of `plot()` into
   interactive plotly figures.
@@ -125,6 +129,23 @@ individual variability in growth to be modelled.
 - New `addPlot()` generic with methods for adding `ArraySpeciesBySize` and
   `ArrayTimeBySpecies` values as extra lines on an existing compatible ggplot.
 
+- New `plot2()` generic with methods for comparing two compatible mizer array
+  objects in one plot, with species or group shown by colour and model by
+  linetype. The `plotSpectra2()` helper has moved from `mizerExperimental` into
+  mizer for comparing two abundance spectra.
+
+- New `plotRelative()` generic with methods for plotting the symmetric relative
+  difference between two compatible mizer array objects. The
+  `plotSpectraRelative()` and `plotlySpectraRelative()` helpers have moved from
+  `mizerExperimental` into mizer.
+
+- New `plotCDF()` and `plotCDF2()` generics for plotting cumulative abundance
+  or biomass distributions from `MizerParams` and `MizerSim` objects, together
+  with `plotlyCDF()` and `plotlyCDF2()` wrappers.
+
+- `plotSpectra()` now accepts `log_x`, `log_y`, and `log` arguments for
+  controlling axis scaling, matching the mizer array `plot()` methods.
+
 - The `plot()` and `summary()` methods for `MizerParams`, `MizerSim`, and the
   mizer array classes are now registered as S3 methods rather than S4 methods,
   so `plot()` and `summary()` remain plain S3 generics when mizer is loaded,

R/ArraySpeciesBySize-class.R

@@ -228,6 +228,145 @@ parsePlotLog <- function(log, log_x = FALSE, log_y = FALSE) {
     )
 }
 
+#' Compare two mizer array objects in one plot
+#'
+#' `plot2()` compares two compatible mizer array objects in a single ggplot.
+#' Colours identify species or groups, and linetype identifies which object the
+#' values came from.
+#'
+#' @param x,y Two compatible mizer array objects of the same class.
+#' @param name1,name2 Labels for the two objects, used in the linetype legend.
+#' @inheritParams plot
+#'
+#' @return A ggplot2 object.
+#' @export
+#' @family plotting functions
+#'
+#' @examples
+#' \donttest{
+#' enc <- getEncounter(NS_params)
+#' plot2(enc, enc, name1 = "Original", name2 = "Changed")
+#' plot2(getBiomass(NS_sim), getBiomass(NS_sim), species = "Cod")
+#' }
+plot2 <- function(x, y, ...) {
+    UseMethod("plot2", x)
+}
+
+#' @rdname plot2
+#' @export
+plot2.ArraySpeciesBySize <- function(x, y, name1 = "First", name2 = "Second",
+                                     species = NULL, all.sizes = FALSE,
+                                     log_x = TRUE, log_y = FALSE, log = NULL,
+                                     wlim = c(NA, NA), ylim = c(NA, NA),
+                                     total = FALSE, background = TRUE,
+                                     y_ticks = 6, ...) {
+    check_plot2_compatible(x, y, "ArraySpeciesBySize")
+    compare_array_metadata(x, y)
+    log_axes <- parsePlotLog(log, log_x = log_x, log_y = log_y)
+    log_x <- log_axes$log_x
+    log_y <- log_axes$log_y
+
+    params <- attr(x, "params")
+    y_label <- array_y_label(x, default = "Rate")
+    plot_dat1 <- prepare_ArraySpeciesBySize_plot_data(
+        x, species = species, all.sizes = all.sizes, wlim = wlim,
+        total = total, background = background)
+    plot_dat2 <- prepare_ArraySpeciesBySize_plot_data(
+        y, species = species, all.sizes = all.sizes, wlim = wlim,
+        total = total, background = background)
+
+    plotComparisonDataFrame(plot_dat1, plot_dat2, params,
+                            name1 = name1, name2 = name2,
+                            xlab = "Size [g]", ylab = y_label,
+                            xtrans = if (log_x) "log10" else "identity",
+                            ytrans = if (log_y) "log10" else "identity",
+                            xlim = wlim, ylim = ylim,
+                            y_ticks = y_ticks, legend_var = "Legend")
+}
+
+#' Plot the relative difference between two mizer array objects
+#'
+#' `plotRelative()` plots the difference between two compatible mizer array
+#' objects relative to their average. If the values in the first object are
+#' \eqn{N_1} and the values in the second are \eqn{N_2}, it plots
+#' \deqn{2 (N_2 - N_1) / (N_1 + N_2).}
+#'
+#' @inheritParams plot2
+#' @param log_x If `TRUE`, use a log10 x-axis. Default is `TRUE` for size
+#'   spectra and `FALSE` for time series.
+#'
+#' @return A ggplot2 object.
+#' @export
+#' @family plotting functions
+#'
+#' @examples
+#' \donttest{
+#' enc <- getEncounter(NS_params)
+#' plotRelative(enc, enc, species = "Cod")
+#' plotRelative(getBiomass(NS_sim), getBiomass(NS_sim), species = "Cod")
+#' }
+plotRelative <- function(x, y, ...) {
+    UseMethod("plotRelative", x)
+}
+
+#' @rdname plotRelative
+#' @export
+plotRelative.ArraySpeciesBySize <- function(x, y, species = NULL,
+                                            all.sizes = FALSE,
+                                            log_x = TRUE,
+                                            wlim = c(NA, NA),
+                                            ylim = c(NA, NA),
+                                            total = FALSE,
+                                            background = TRUE, ...) {
+    check_plot2_compatible(x, y, "ArraySpeciesBySize")
+    compare_array_metadata(x, y)
+    params <- attr(x, "params")
+    plot_dat1 <- prepare_ArraySpeciesBySize_plot_data(
+        x, species = species, all.sizes = all.sizes, wlim = wlim,
+        total = total, background = background)
+    plot_dat2 <- prepare_ArraySpeciesBySize_plot_data(
+        y, species = species, all.sizes = all.sizes, wlim = wlim,
+        total = total, background = background)
+
+    plotRelativeDataFrame(plot_dat1, plot_dat2, params,
+                          xlab = "Size [g]",
+                          xtrans = if (log_x) "log10" else "identity",
+                          xlim = wlim, ylim = ylim, legend_var = "Legend")
+}
+
+check_plot2_compatible <- function(x, y, class) {
+    if (!inherits(y, class)) {
+        stop("Both objects must be of class `", class, "`.")
+    }
+}
+
+compare_array_metadata <- function(x, y) {
+    value_name1 <- attr(x, "value_name")
+    value_name2 <- attr(y, "value_name")
+    if (!is.null(value_name1) && !is.null(value_name2) &&
+            !identical(value_name1, value_name2)) {
+        warning("The first array has value name `", value_name1,
+                "`, but the second array has value name `", value_name2, "`.")
+    }
+    units1 <- attr(x, "units")
+    units2 <- attr(y, "units")
+    if (!is.null(units1) && !is.null(units2) &&
+            nzchar(units1) && nzchar(units2) &&
+            !identical(units1, units2)) {
+        warning("The first array has y units `", units1,
+                "`, but the second array has y units `", units2, "`.")
+    }
+}
+
+array_y_label <- function(x, default = "Value") {
+    value_name <- attr(x, "value_name") %||% default
+    units_str <- attr(x, "units")
+    if (!is.null(units_str) && nzchar(units_str)) {
+        value_name <- paste0(value_name, " [", units_str, "]")
+    }
+    value_name
+}
+
 #' Add values to an existing plot
 #'
 #' `r lifecycle::badge("experimental")`

R/ArrayTimeBySpecies-class.R

@@ -234,6 +234,64 @@ addPlot.ArrayTimeBySpecies <- function(plot, x, species = NULL,
     plot + do.call(geom_line, layer_args)
 }
 
+#' @rdname plot2
+#' @export
+plot2.ArrayTimeBySpecies <- function(x, y, name1 = "First", name2 = "Second",
+                                     species = NULL,
+                                     start_time = NULL, end_time = NULL,
+                                     y_ticks = 6, ylim = c(NA, NA),
+                                     total = FALSE, background = TRUE,
+                                     log_x = FALSE, log_y = TRUE,
+                                     log = NULL, ...) {
+    check_plot2_compatible(x, y, "ArrayTimeBySpecies")
+    compare_array_metadata(x, y)
+    log_axes <- parsePlotLog(log, log_x = log_x, log_y = log_y)
+    log_x <- log_axes$log_x
+    log_y <- log_axes$log_y
+
+    params <- attr(x, "params")
+    y_label <- array_y_label(x, default = "Value")
+    plot_dat1 <- prepare_ArrayTimeBySpecies_plot_data(
+        x, species = species, start_time = start_time, end_time = end_time,
+        ylim = ylim, total = total, background = background)
+    plot_dat2 <- prepare_ArrayTimeBySpecies_plot_data(
+        y, species = species, start_time = start_time, end_time = end_time,
+        ylim = ylim, total = total, background = background)
+
+    plotComparisonDataFrame(plot_dat1, plot_dat2, params,
+                            name1 = name1, name2 = name2,
+                            xlab = "Year", ylab = y_label,
+                            xtrans = if (log_x) "log10" else "identity",
+                            ytrans = if (log_y) "log10" else "identity",
+                            ylim = ylim, y_ticks = y_ticks,
+                            legend_var = "Legend")
+}
+
+#' @rdname plotRelative
+#' @export
+plotRelative.ArrayTimeBySpecies <- function(x, y, species = NULL,
+                                            start_time = NULL,
+                                            end_time = NULL,
+                                            ylim = c(NA, NA),
+                                            total = FALSE,
+                                            background = TRUE,
+                                            log_x = FALSE, ...) {
+    check_plot2_compatible(x, y, "ArrayTimeBySpecies")
+    compare_array_metadata(x, y)
+    params <- attr(x, "params")
+    plot_dat1 <- prepare_ArrayTimeBySpecies_plot_data(
+        x, species = species, start_time = start_time, end_time = end_time,
+        total = total, background = background)
+    plot_dat2 <- prepare_ArrayTimeBySpecies_plot_data(
+        y, species = species, start_time = start_time, end_time = end_time,
+        total = total, background = background)
+
+    plotRelativeDataFrame(plot_dat1, plot_dat2, params,
+                          xlab = "Year",
+                          xtrans = if (log_x) "log10" else "identity",
+                          ylim = ylim, legend_var = "Legend")
+}
+
 prepare_ArrayTimeBySpecies_plot_data <- function(x, species = NULL,
                                                  start_time = NULL,
                                                  end_time = NULL,