Load candidates into Slick

Explore the Ten CMP Comparison Cases in Slick

Slick is an interactive tool for exploring MSE results. The simulation is run in jmMSE; this repository converts the resulting performance table into a Slick file.

1 Open the current file

1.1 In the hosted app

Download the current jm_candidates.slick.
Open the Blue Matter Slick app.
If the app has stopped, select Restart app.
Under Load your MSE Results, select the downloaded .slick file.
When the Overview appears, use the MP and OM filters to explore the results. The current file opens with All CMPs selected, so HS-20 and PR-20 should be visible immediately.

If only HS+20 and PR+20 appear, open the MPs filter and select All CMPs. That indicates either that the Advanced candidates preset is active or that an older copy of the same-named file was loaded. The current file contains ten MPs and has SHA-256 fingerprint 6b17b0b0bb5483611f82f97c9d368dddcf2a69934ec2fd2bb110129b32685a8f.

The hosted app accepts file uploads but does not currently provide a field for loading a file directly from a GitHub URL.

1.2 From R

Show implementation detail

install.packages("Slick") # needed only once
library(Slick)

url <- paste0(
  "https://raw.githubusercontent.com/SPRFMO/jmMSE26/",
  "main/",
  "output/jm_candidates.slick"
)
file <- tempfile(fileext = ".slick")
download.file(url, file, mode = "wb")

slick <- readRDS(file)
Check(slick)
App(slick = slick)

1.3 Make it a selectable case study

Slick’s case-study menu is populated from the Blue-Matter/SlickLibrary repository. To request direct integration, copy the file to Slick_Objects/SPRFMO_Jack_Mackerel.slick in a fork of that repository and submit a pull request. Once the SlickLibrary maintainers merge it, SPRFMO Jack Mackerel will appear in the hosted app’s case-study menu. See the official contribution instructions.

2 What is needed

The conversion can use either:

the table of performance results produced by jmMSE; or
a saved jmMSE results object that already contains those performance results.

The results must include the ten CMPs listed below, the operating-model and stock names, simulation year and replicate, and the calculated performance measures. At a minimum, the results must include spawning biomass relative to $SB_{MSY}$, fishing mortality relative to $F_{MSY}$, and catch. Interannual catch change (IACC) is included when available. The published Slick file also requires vulnerable biomass relative to its 2025 level and relative to equilibrium vulnerable biomass at the fishing mortality that produces MSY.

The current reference comparison has been completed for ten CMPs with 100 simulation replicates through 2050. It is stored locally in jmMSE as:

model/candidates/reference/runs.rds: the complete simulation object; and
model/candidates/reference/performance.rds: the original four-metric performance table.

The augmented six-metric tables used for the published Slick file are retained in this repository as output/candidate-performance/reference/performance_with_vb.rds and output/candidate-performance/robustness/performance_with_vb.rds.

These are reference-operating-model results. They are suitable for checking the candidate calculations and comparing the rule and data contrasts, but they are not a substitute for robustness testing across the full set of operating models.

The nine-OM robustness set has also been completed and is stored locally in jmMSE/model/candidates/robustness/. It contains all ten CMPs, 100 simulation replicates, and annual results through 2050 for every operating model.

3 CMPs included

HS+20 (MP29) and PR+20 (MP32) remain the two advanced candidates. HS-20 (MP43) and PR-20 (MP44) are tuned annual-limit comparison cases based on those candidates. The other six procedures help show which part of a procedure causes a change in performance.

CMP	Role in the comparison
HS+20 (MP29)	Optimal hockeystick case: target 2000, limit 0.1, all selected indices.
HS-20 (MP43)	MP29 structure with a 20% maximum annual decrease and 15% maximum increase; retuned trigger 3.0625.
PR+20 (MP32)	Alternative powerramp case: target 1500, limit 0.1, all selected indices.
PR-20 (MP44)	MP32 structure with a 20% maximum annual decrease and 15% maximum increase; retuned trigger 1.9140625.
MP18	Extreme high-target case: hockeystick target 5000.
MP24	Low-target case: hockeystick target 1750 and limit 0.
MP31	Higher-limit case: hockeystick target 2000 and limit 0.3.
MP23	Different rule shape: slope HCR with its original five-year averaging window.
MP35	CPUE-only powerramp contrast: target 1500 and limit 0.1.
MP36	CPUE-only hockeystick contrast: target 2000 and limit 0.1.

The MP filter includes one-click selections for the advanced candidates, both annual-limit comparisons, each parent-and-variant pair, target contrasts, the limit contrast, rule-shape contrasts, CPUE-only contrasts, all CMPs, and each individual CMP.

MP23 retains the five-year averaging window used in its original tuning code. MP29 and MP32 use three years, so the MP23 comparison changes both rule shape and averaging window; it should not be interpreted as a pure test of shape alone.

MP43 and MP44 were retuned under reference OM11 to the same objective used for the established candidates: mean probability of being in the dynamic Kobe green zone equal to 0.60 over 2041–2050. The achieved values were 0.606 for MP43 and 0.603 for MP44. The repeatable tuning script is tune_candidate_change_limits.R in jmMSE.

4 Run or extend the reference comparison

From the jmMSE folder on branch devel:

Rscript run_candidate_mps.R \
  --candidates=tun29,tun43,tun32,tun44,tun18,tun24,tun31,tun23,tun35,tun36 \
  --mode=reference \
  --cores=1

The candidate codes come from candidate_mps.csv. Additional hockeystick or powerramp trials can be included for contrast, for example:

Rscript run_candidate_mps.R \
  --candidates=tun25,tun29,tun32 \
  --mode=reference \
  --cores=1

The runner uses the recorded definitions in candidate_mps.csv together with the original estimator and rule functions in jmMSE. Shortcut-assessment errors are generated from the original error model using fixed seeds so the comparison can be repeated. Each CMP starts from the same fixed random stream within an operating model, so adding or reordering CMPs does not change the other CMP results. Moving to a newer combined-index implementation should be treated as a method change requiring the operating models to be rebuilt and the candidates to be retuned and revalidated.

The validated reference run used R 4.6.1 with FLCore 2.6.30, FLFishery 0.4.0, mse 2.4.8.9004, msemodules 0.2.2, and FLjjm 0.3.4. The run folder contains the complete sessionInfo.txt record.

5 Prepare the combined Slick file

From the main jmMSE26 folder:

Show implementation detail

source("R/build_candidate_slick.R")

reference_slick <- build_candidate_slick(
  performance_file =
    "output/candidate-performance/reference/performance_with_vb.rds",
  out_file = NULL,
  historical_om_files = candidate_reference_om_files("../jmMSE"),
  require_vb = TRUE
)

The script organizes the results by:

management procedure (one of the ten CMP comparison cases);
operating model and stock;
simulation replicate and year; and
performance measure, including Kobe-plot values for $SB/SB_{MSY}$ and $F/F_{MSY}$, plus $VB/VB_{2025}$ and $VB/VB_{\mathrm{MSY}}$.

It also prepares three summary views using the comparison periods already used in jmMSE:

Boxplots show the distribution among simulation replicates in the final year, 2050.
Quilts compare stock status, fishing pressure, catch, and catch stability among operating models and MPs. They also include both vulnerable-biomass ratios. Long-term results use 2036–2040; short-term catch uses 2026–2030.
Trade-off plots use the same periods to compare conservation, catch, and catch-stability measures directly, including both vulnerable-biomass ratios.

The vulnerable-biomass time series are available from 2024 through 2050; earlier years are intentionally missing. VB/VB[2025] uses each simulated stock’s 2025 vulnerable biomass as its denominator. VB/VB[MSY] uses equilibrium vulnerable biomass at the fishing mortality that produces MSY, not MSY catch.

Kobe quadrant probabilities are calculated from $SB/SB_{MSY}$ and $F/F_{MSY}$. When $F_{MSY}$ is zero, $F/F_{MSY}$ is undefined and is treated as missing. Finite $F/F_{MSY}$ values above 4 are shown at 4 so that a small number of post-collapse numerical values do not make the plots unreadable. This is a display rule only: the original jmMSE performance tables are not changed.

The OM metadata is kept in exactly the same order as the OM dimension in each Slick value array. This ensures that Northern and Southern stock results retain the correct labels in the two-stock operating models.

Before saving the Slick file, the script checks that the expected dimensions and labels agree. The technical checks are shown in the code for analysts who maintain the export.

The reference is labelled om11 in Slick. Its source name, h1_0.16, remains in the OM metadata for traceability.

5.1 Add the robustness sets

The robustness operating models and candidate runs can be reproduced from jmMSE branch devel with:

Rscript prepare_candidate_robustness_oms.R
Rscript run_candidate_mps.R \
  --candidates=tun29,tun43,tun32,tun44,tun18,tun24,tun31,tun23,tun35,tun36 \
  --mode=robustness \
  --cores=1

Then build the robustness component and combine it with the reference:

Show implementation detail

source("R/build_candidate_slick.R")

robustness_slick <- build_candidate_slick(
  performance_file =
    "output/candidate-performance/robustness/performance_with_vb.rds",
  out_file = NULL,
  historical_om_files = candidate_robustness_om_files("../jmMSE"),
  require_vb = TRUE
)

slick <- build_combined_candidate_slick(
  reference_slick = reference_slick,
  robustness_slick = robustness_slick,
  out_file = "output/jm_candidates.slick"
)

The resulting Slick file contains 14 OM–stock series: one reference, five single-stock robustness cases, and eight stock-specific series from four two-stock robustness cases. Slick retains the Southern and Northern results rather than averaging them.

The Set filter provides three main categories:

Reference: om11;
Robustness CJM: the five single-stock robustness OMs; and
Robustness 2-stock: the Southern and Northern results from the four two-stock robustness OMs.

The OM and Stock filters remain available for selecting individual models and stock components. One-click presets provide quick selections for the reference, all CJM cases, the CJM robustness cases, the two-stock robustness cases, all OMs, and each individual alternative OM. Selecting a two-stock OM includes both its Southern and Northern rows.

The dimensions are 100 simulations, 14 OM–stock series, ten management procedures, six performance measures, and 81 annual values from 1970 through 2050. The six measures are $SB/SB_{MSY}$, $F/F_{MSY}$, catch, IACC, $VB/VB_{2025}$, and $VB/VB_{\mathrm{MSY}}$. Each series uses its own conditioned history through 2025; projections under the ten CMPs begin in 2026.

Do not combine results produced under different package sets without first confirming that the candidate calculations are equivalent.

6 Inspect or launch

Show implementation detail

library(Slick)

slick <- readRDS("output/jm_candidates.slick")
Check(slick)
methods::validObject(slick)

dim(Value(Timeseries(slick)))
Metadata(MPs(slick))
Design(slick)

App(slick = slick)

7 What to save with the Slick file

Save the Slick file together with the original performance results, their digital fingerprint, the exact saved versions of jmMSE and jmMSE26, and the versions of the R packages used.

--- title: "Load candidates into Slick" --- {{< include ../_includes/sprfmo-banner.qmd >}} <div class="paper-title">Explore the Ten CMP Comparison Cases in Slick</div> Slick is an interactive tool for exploring MSE results. The simulation is run in `jmMSE`; this repository converts the resulting performance table into a Slick file. ## Open the current file ### In the hosted app 1. [Download the current `jm_candidates.slick`](https://raw.githubusercontent.com/SPRFMO/jmMSE26/main/output/jm_candidates.slick). 2. Open the [Blue Matter Slick app](https://shiny.bluematterscience.com/app/slick). 3. If the app has stopped, select **Restart app**. 4. Under **Load your MSE Results**, select the downloaded `.slick` file. 5. When the Overview appears, use the MP and OM filters to explore the results. The current file opens with **All CMPs** selected, so HS-20 and PR-20 should be visible immediately. If only HS+20 and PR+20 appear, open the **MPs** filter and select **All CMPs**. That indicates either that the **Advanced candidates** preset is active or that an older copy of the same-named file was loaded. The current file contains ten MPs and has SHA-256 fingerprint `6b17b0b0bb5483611f82f97c9d368dddcf2a69934ec2fd2bb110129b32685a8f`. The hosted app accepts file uploads but does not currently provide a field for loading a file directly from a GitHub URL. ### From R ```{r} #| eval: false install.packages("Slick") # needed only once library(Slick) url <- paste0( "https://raw.githubusercontent.com/SPRFMO/jmMSE26/", "main/", "output/jm_candidates.slick" ) file <- tempfile(fileext = ".slick") download.file(url, file, mode = "wb") slick <- readRDS(file) Check(slick) App(slick = slick) ``` ### Make it a selectable case study Slick's case-study menu is populated from the [`Blue-Matter/SlickLibrary`](https://github.com/Blue-Matter/SlickLibrary) repository. To request direct integration, copy the file to `Slick_Objects/SPRFMO_Jack_Mackerel.slick` in a fork of that repository and submit a pull request. Once the SlickLibrary maintainers merge it, **SPRFMO Jack Mackerel** will appear in the hosted app's case-study menu. See the [official contribution instructions](https://slick.bluematterscience.com/articles/DevelopersGuide.html#slick-object-library). ## What is needed The conversion can use either: - the table of performance results produced by `jmMSE`; or - a saved `jmMSE` results object that already contains those performance results. The results must include the ten CMPs listed below, the operating-model and stock names, simulation year and replicate, and the calculated performance measures. At a minimum, the results must include spawning biomass relative to $SB_{MSY}$, fishing mortality relative to $F_{MSY}$, and catch. Interannual catch change (IACC) is included when available. The published Slick file also requires vulnerable biomass relative to its 2025 level and relative to equilibrium vulnerable biomass at the fishing mortality that produces MSY. The current reference comparison has been completed for ten CMPs with 100 simulation replicates through 2050. It is stored locally in `jmMSE` as: - `model/candidates/reference/runs.rds`: the complete simulation object; and - `model/candidates/reference/performance.rds`: the original four-metric performance table. The augmented six-metric tables used for the published Slick file are retained in this repository as `output/candidate-performance/reference/performance_with_vb.rds` and `output/candidate-performance/robustness/performance_with_vb.rds`. These are reference-operating-model results. They are suitable for checking the candidate calculations and comparing the rule and data contrasts, but they are not a substitute for robustness testing across the full set of operating models. The nine-OM robustness set has also been completed and is stored locally in `jmMSE/model/candidates/robustness/`. It contains all ten CMPs, 100 simulation replicates, and annual results through 2050 for every operating model. ## CMPs included HS+20 (MP29) and PR+20 (MP32) remain the two advanced candidates. HS-20 (MP43) and PR-20 (MP44) are tuned annual-limit comparison cases based on those candidates. The other six procedures help show which part of a procedure causes a change in performance. | CMP | Role in the comparison | |---|---| | HS+20 (MP29) | Optimal hockeystick case: target 2000, limit 0.1, all selected indices. | | HS-20 (MP43) | MP29 structure with a 20% maximum annual decrease and 15% maximum increase; retuned trigger 3.0625. | | PR+20 (MP32) | Alternative powerramp case: target 1500, limit 0.1, all selected indices. | | PR-20 (MP44) | MP32 structure with a 20% maximum annual decrease and 15% maximum increase; retuned trigger 1.9140625. | | MP18 | Extreme high-target case: hockeystick target 5000. | | MP24 | Low-target case: hockeystick target 1750 and limit 0. | | MP31 | Higher-limit case: hockeystick target 2000 and limit 0.3. | | MP23 | Different rule shape: slope HCR with its original five-year averaging window. | | MP35 | CPUE-only powerramp contrast: target 1500 and limit 0.1. | | MP36 | CPUE-only hockeystick contrast: target 2000 and limit 0.1. | The MP filter includes one-click selections for the advanced candidates, both annual-limit comparisons, each parent-and-variant pair, target contrasts, the limit contrast, rule-shape contrasts, CPUE-only contrasts, all CMPs, and each individual CMP. MP23 retains the five-year averaging window used in its original tuning code. MP29 and MP32 use three years, so the MP23 comparison changes both rule shape and averaging window; it should not be interpreted as a pure test of shape alone. MP43 and MP44 were retuned under reference OM11 to the same objective used for the established candidates: mean probability of being in the dynamic Kobe green zone equal to 0.60 over 2041–2050. The achieved values were 0.606 for MP43 and 0.603 for MP44. The repeatable tuning script is `tune_candidate_change_limits.R` in `jmMSE`. ## Run or extend the reference comparison From the `jmMSE` folder on branch `devel`: ```sh Rscript run_candidate_mps.R \ --candidates=tun29,tun43,tun32,tun44,tun18,tun24,tun31,tun23,tun35,tun36 \ --mode=reference \ --cores=1 ``` The candidate codes come from `candidate_mps.csv`. Additional hockeystick or powerramp trials can be included for contrast, for example: ```sh Rscript run_candidate_mps.R \ --candidates=tun25,tun29,tun32 \ --mode=reference \ --cores=1 ``` The runner uses the recorded definitions in `candidate_mps.csv` together with the original estimator and rule functions in `jmMSE`. Shortcut-assessment errors are generated from the original error model using fixed seeds so the comparison can be repeated. Each CMP starts from the same fixed random stream within an operating model, so adding or reordering CMPs does not change the other CMP results. Moving to a newer combined-index implementation should be treated as a method change requiring the operating models to be rebuilt and the candidates to be retuned and revalidated. The validated reference run used R 4.6.1 with FLCore 2.6.30, FLFishery 0.4.0, mse 2.4.8.9004, msemodules 0.2.2, and FLjjm 0.3.4. The run folder contains the complete `sessionInfo.txt` record. ## Prepare the combined Slick file From the main `jmMSE26` folder: ```{r} #| eval: false source("R/build_candidate_slick.R") reference_slick <- build_candidate_slick( performance_file = "output/candidate-performance/reference/performance_with_vb.rds", out_file = NULL, historical_om_files = candidate_reference_om_files("../jmMSE"), require_vb = TRUE ) ``` The script organizes the results by: - management procedure (one of the ten CMP comparison cases); - operating model and stock; - simulation replicate and year; and - performance measure, including Kobe-plot values for $SB/SB_{MSY}$ and $F/F_{MSY}$, plus $VB/VB_{2025}$ and $VB/VB_{\mathrm{MSY}}$. It also prepares three summary views using the comparison periods already used in `jmMSE`: - **Boxplots** show the distribution among simulation replicates in the final year, 2050. - **Quilts** compare stock status, fishing pressure, catch, and catch stability among operating models and MPs. They also include both vulnerable-biomass ratios. Long-term results use 2036–2040; short-term catch uses 2026–2030. - **Trade-off plots** use the same periods to compare conservation, catch, and catch-stability measures directly, including both vulnerable-biomass ratios. The vulnerable-biomass time series are available from 2024 through 2050; earlier years are intentionally missing. `VB/VB[2025]` uses each simulated stock's 2025 vulnerable biomass as its denominator. `VB/VB[MSY]` uses equilibrium vulnerable biomass at the fishing mortality that produces MSY, not MSY catch. Kobe quadrant probabilities are calculated from $SB/SB_{MSY}$ and $F/F_{MSY}$. When $F_{MSY}$ is zero, $F/F_{MSY}$ is undefined and is treated as missing. Finite $F/F_{MSY}$ values above 4 are shown at 4 so that a small number of post-collapse numerical values do not make the plots unreadable. This is a display rule only: the original `jmMSE` performance tables are not changed. The OM metadata is kept in exactly the same order as the OM dimension in each Slick value array. This ensures that Northern and Southern stock results retain the correct labels in the two-stock operating models. Before saving the Slick file, the script checks that the expected dimensions and labels agree. The technical checks are shown in the code for analysts who maintain the export. The reference is labelled `om11` in Slick. Its source name, `h1_0.16`, remains in the OM metadata for traceability. ### Add the robustness sets The robustness operating models and candidate runs can be reproduced from `jmMSE` branch `devel` with: ```sh Rscript prepare_candidate_robustness_oms.R Rscript run_candidate_mps.R \ --candidates=tun29,tun43,tun32,tun44,tun18,tun24,tun31,tun23,tun35,tun36 \ --mode=robustness \ --cores=1 ``` Then build the robustness component and combine it with the reference: ```{r} #| eval: false source("R/build_candidate_slick.R") robustness_slick <- build_candidate_slick( performance_file = "output/candidate-performance/robustness/performance_with_vb.rds", out_file = NULL, historical_om_files = candidate_robustness_om_files("../jmMSE"), require_vb = TRUE ) slick <- build_combined_candidate_slick( reference_slick = reference_slick, robustness_slick = robustness_slick, out_file = "output/jm_candidates.slick" ) ``` The resulting Slick file contains 14 OM–stock series: one reference, five single-stock robustness cases, and eight stock-specific series from four two-stock robustness cases. Slick retains the Southern and Northern results rather than averaging them. The `Set` filter provides three main categories: - **Reference**: om11; - **Robustness CJM**: the five single-stock robustness OMs; and - **Robustness 2-stock**: the Southern and Northern results from the four two-stock robustness OMs. The OM and Stock filters remain available for selecting individual models and stock components. One-click presets provide quick selections for the reference, all CJM cases, the CJM robustness cases, the two-stock robustness cases, all OMs, and each individual alternative OM. Selecting a two-stock OM includes both its Southern and Northern rows. The dimensions are 100 simulations, 14 OM–stock series, ten management procedures, six performance measures, and 81 annual values from 1970 through 2050. The six measures are $SB/SB_{MSY}$, $F/F_{MSY}$, catch, IACC, $VB/VB_{2025}$, and $VB/VB_{\mathrm{MSY}}$. Each series uses its own conditioned history through 2025; projections under the ten CMPs begin in 2026. Do not combine results produced under different package sets without first confirming that the candidate calculations are equivalent. ## Inspect or launch ```{r} #| eval: false library(Slick) slick <- readRDS("output/jm_candidates.slick") Check(slick) methods::validObject(slick) dim(Value(Timeseries(slick))) Metadata(MPs(slick)) Design(slick) App(slick = slick) ``` ## What to save with the Slick file Save the Slick file together with the original performance results, their digital fingerprint, the exact saved versions of `jmMSE` and `jmMSE26`, and the versions of the R packages used.