Skip to contents

Processing MSE Results

05_processing_mse_results.Rmd

The run_mse() and its associated wrapper functions return large quantities of data, inlcuding:

  • Landed catch-at-age
  • Fishing mortality-at-age
  • Numbers-at-age
  • Recommended F from the harvest control rule
  • Computed TACs
  • etc.

These data objects are all multi-dimensional arrays of dimensions [nyears, nages, nsexes, nregions, nfleets, nsims].

Owing to the large number of outputs, their complex dimensions, and the frequency with which multiple MSE simulations that are compared, processing MSE results can be challenging. The SablefishMSE package provides a specific helper function for coercing output MSE data into a form that is useable for deriving additional quantities (e.g. spawning stock biomass), computing performance metrics, and plotting results.

bind_mse_results

The function bind_mse_results(model_runs, var, extra_columns) takes a list of completed MSE simulation objects, a vector of variable names (as characters), and a named list of additional columns, and returns a dataframe in long-format. It is intended to be used as below:

mse1 <- run_mse(om, hcr, mse_options, nyears_input=100)

model_runs <- list(mse1)
extra_columns <- list(om="hcr1")
vars <- c("naa")

results <- bind_mse_outputs(model_runs, vars, extra_columns)

The resulting object will be a data frame with at least six columns:

  • time
  • age
  • sex
  • region
  • value
  • L1

Note that the “L1” column will contain name of the variable each piece of data (“value”) is associated with. In the above example, the “L1” column will be “naa”.

If extra_columns are specified, additional columns will be appended to the end of the dataframe. If mse object(s) in model_runs contain results from multiple somulations, a “sim” column will also be a part of the dataframe. Any combination of output variables can be supplied as part of the “vars” parameter vector, though the resulting dataframe may contain NA entries if mixing between variables that are defined “at-age” (e.g. numbers-at-age or F-at-age), and variables that are defined annualy (e.g. TAC or recommended F from the HCR function).

From here, users may interact with the MSE outputs with standard R dataframe commands, or via typical tidyverse functions.

How to Use the extra_columns Parameter

The extra_columns parameter doesn’t make a lot of sense in the above the example, as only a single MSE object is being processed. However, in the case where multiple MSE objects, with different combinations of OMs and HCRs are being processed simultaneously, users need a way to differentiate between which data belongs to which MSE simualtions. The extra_columns parameter provides a means for users to explicitly identfiy between MSE simulations.

mse1 <- run_mse(om1, hcr1, mse_options, nyears_input=100)
mse2 <- run_mse(om1, hcr2, mse_options, nyears_input=100)
mse3 <- run_mse(om2, hcr1, mse_options, nyears_input=100)
mse4 <- run_mse(om2, hcr2, mse_options, nyears_input=100)

model_runs <- list(mse1, mse2, mse3, mse4)
extra_columns <- list(
    om = rep(c("om1", "om2"), each=2),
    hcr = rep(c("hcr1", "hcr2"), 2)
)
vars <- c("naa")

results <- bind_mse_outputs(model_runs, vars, extra_columns)

In the above example, four MSE simulations, spanning two OMs and two HCR functions, are all being processed together (presumably for comparing the performance of the different HCRs across both OMs later on). The extra_columns list defines that two additional columns, “om” and “hcr” (the names of the list), should be added to the resulting output dataframe. The values of each list obect are vectors of the same length as the model_runs object.

Additional Helper Functions

Three helper functions are provided for quickly computing common derived quantities:

  • get_ssb_biomass() - computes spawning biomass and total biomass from the true and estimated numbers-at-age matrices
  • get_fishing_mortalities() - computes the fully selected fishing mortality for each fleet and jointly across all fleets from the true and estimated F-at-age matrices
  • get_recruits() - computed annual recruitment from the true and estimated numbers-at-age matrices

The resulting tibble from each of these function remains in long format with the appropriately columns retained. For plotting, additional processing is likely needed.

NOTE: Additional helper functions will likely be added throughout the lifecycle of this package to streamline common calculations. A get_landings() function is in development to allow simplified processing of landings data.