Compute Performance Statistics for Management Procedure Evaluation
Source:R/performance.R
performance.RdEvaluates the performance of a management procedure by computing statistical metrics across simulated projections. Supports multiple input types (FLQuants, FLStock, FLStocks, FLom, FLmse, FLmses, and lists) and computes custom statistics defined by formulas that reference metrics and reference points.
Usage
# S4 method for class 'FLQuants'
performance(
x,
statistics = mse::statistics[c("C", "F", "SB", "AAVC")],
refpts = FLPar(),
years = setNames(nm = dimnames(x[[1]])$year[-1]),
om = character(0),
type = character(0),
run = character(0),
mp = paste(c(om, type, run), collapse = "_"),
...
)
# S4 method for class 'FLo'
performance(
x,
refpts = x@refpts,
statistics = mse::statistics[c("C", "F", "HR", "SB")],
metrics = NULL,
om = name(x),
...
)
# S4 method for class 'FLombf'
performance(
x,
refpts = FLCore::refpts(x),
statistics = mse::statistics[c("C", "F", "HR", "SB")],
metrics = NULL,
om = name(x),
...
)
# S4 method for class 'FLmse'
performance(
x,
refpts = FLCore::refpts(x),
statistics = .validStatistics(om(x)),
metrics = NULL,
years = dimnames(om(x))$year[-1],
om = name(x@om),
type = "MP",
run = "1",
control = FALSE,
...
)
# S4 method for class 'FLmses'
performance(x, type = NULL, refpts = NULL, ...)
# S4 method for class 'list'
performance(x, statistics, refpts = NULL, years = "missing", ...)
# S4 method for class 'FLStock'
performance(
x,
statistics,
metrics = list(R = rec, SB = ssb, B = tsb, C = catch, L = landings, D = discards, F =
fbar, HR = hr),
...
)
# S4 method for class 'FLStocks'
performance(x, statistics, ...)Arguments
- x
An object holding simulation results. Supported classes:
FLQuants,FLStock,FLStocks,FLom,FLmse,FLmses, orlist.- statistics
A list of statistics to compute. Each element must be a named list with a formula and metadata (name, desc). See Details.
- refpts
Reference points for calculations, typically an
FLParobject. Defaults to the reference points held by inputs that contain them. ForFLmsesand lists, a suppliedFLParapplies to every member, while a named list supplies one object per member.FLQuantsdefaults to an emptyFLPar().- years
Years on which statistics should be computed. Can be:
A vector of years to use
A named list of year vectors (names become year labels in output) Defaults to last year of input if omitted.
- om
Optional name for the operating model.
- type
Optional name for the MP type.
- run
Optional name for the model run.
- mp
Optional combined MP name. Auto-generated if not provided.
- ...
Additional arguments passed through (e.g., custom metrics, tracking data).
- metrics
Optional metrics object for FLStock/FLStocks input. Can be:
An
FLQuantsobject with pre-computed metricsA list of metric functions
A single function to compute metrics
- control
Logical. For FLmse input, include HCR control arguments in output? Defaults to FALSE.
- probs
Optional numeric vector of quantiles (0-1) to compute on statistic distributions across iterations. If NULL (default), returns mean values.
- mc.cores
Integer. Number of cores for parallel processing when handling lists or FLStocks. Defaults to 1 (sequential).
Value
A data.table containing computed performance statistics with columns:
statistic: Name of the computed statistic
year: Year or period for which statistic was computed
name: Display name of statistic
desc: Description of statistic
iter: Iteration number (or median/quantile if probs specified)
data: The computed value
om, type, run, mp: Identifiers for the analysis
Details
Each statistic is defined as a named list containing:
A formula (unnamed element) using metric and reference point names, e.g.,
~yearMeans(SB/SB0)name: Short name for tables/plots, e.g., "SB/SB0"
desc: Longer description, e.g., "Mean spawner biomass relative to unfished"
Statistics formulas can reference:
Names of
FLQuantselements (metrics from estimation)Parameter names in the
refptsobjectFLQuant dimension names (age, year, unit, season, area)
Functions callable on the source object (for non-FLQuants input)
See also
statistics, refpts(), metrics()
Examples
# LOAD example FLmse object
data(plesim)
# Extract FLQuants using metrics
x <- metrics(om)
performance(x, statistics=statistics[c("SB", "SBMSY", "F", "FMSY")],
refpts=refpts(om), om="ple", run="r00", type="test")
#> om biol mp year statistic name iter data
#> <char> <char> <char> <int> <char> <char> <int> <num>
#> 1: ple <NA> ple_test_r00 1961 SB SB (t) 1 39511.679303
#> 2: ple <NA> ple_test_r00 1961 SB SB (t) 10 39511.679303
#> 3: ple <NA> ple_test_r00 1961 SB SB (t) 100 39511.679303
#> 4: ple <NA> ple_test_r00 1961 SB SB (t) 11 39511.679303
#> 5: ple <NA> ple_test_r00 1961 SB SB (t) 12 39511.679303
#> ---
#> 37996: ple <NA> ple_test_r00 2055 FMSY F/F[MSY] 95 4.301398
#> 37997: ple <NA> ple_test_r00 2055 FMSY F/F[MSY] 96 4.301398
#> 37998: ple <NA> ple_test_r00 2055 FMSY F/F[MSY] 97 4.301398
#> 37999: ple <NA> ple_test_r00 2055 FMSY F/F[MSY] 98 4.301398
#> 38000: ple <NA> ple_test_r00 2055 FMSY F/F[MSY] 99 4.301398
#> type run desc
#> <char> <char> <char>
#> 1: test r00 Spawner biomass
#> 2: test r00 Spawner biomass
#> 3: test r00 Spawner biomass
#> 4: test r00 Spawner biomass
#> 5: test r00 Spawner biomass
#> ---
#> 37996: test r00 Fishing mortality relative to FMSY
#> 37997: test r00 Fishing mortality relative to FMSY
#> 37998: test r00 Fishing mortality relative to FMSY
#> 37999: test r00 Fishing mortality relative to FMSY
#> 38000: test r00 Fishing mortality relative to FMSY
# Compute on OM, name taken from slot
performance(om, statistics=statistics[c("SB", "SBMSY", "F", "FMSY")],
run="r00", type="test")
#> om biol mp year statistic name iter data
#> <char> <char> <char> <int> <char> <char> <int> <num>
#> 1: PLE PLE_test_r00 1961 SB SB (t) 1 39511.679303
#> 2: PLE PLE_test_r00 1961 SB SB (t) 10 39511.679303
#> 3: PLE PLE_test_r00 1961 SB SB (t) 100 39511.679303
#> 4: PLE PLE_test_r00 1961 SB SB (t) 11 39511.679303
#> 5: PLE PLE_test_r00 1961 SB SB (t) 12 39511.679303
#> ---
#> 37996: PLE PLE_test_r00 2055 FMSY F/F[MSY] 95 4.301398
#> 37997: PLE PLE_test_r00 2055 FMSY F/F[MSY] 96 4.301398
#> 37998: PLE PLE_test_r00 2055 FMSY F/F[MSY] 97 4.301398
#> 37999: PLE PLE_test_r00 2055 FMSY F/F[MSY] 98 4.301398
#> 38000: PLE PLE_test_r00 2055 FMSY F/F[MSY] 99 4.301398
#> type run desc
#> <char> <char> <char>
#> 1: test r00 Spawner biomass
#> 2: test r00 Spawner biomass
#> 3: test r00 Spawner biomass
#> 4: test r00 Spawner biomass
#> 5: test r00 Spawner biomass
#> ---
#> 37996: test r00 Fishing mortality relative to FMSY
#> 37997: test r00 Fishing mortality relative to FMSY
#> 37998: test r00 Fishing mortality relative to FMSY
#> 37999: test r00 Fishing mortality relative to FMSY
#> 38000: test r00 Fishing mortality relative to FMSY
# Setup an example MSE
control <- mpCtrl(list(
est = mseCtrl(method=perfect.sa),
hcr = mseCtrl(method=fixedF.hcr, args=list(ftrg=0.15))))
# ... and run it
mse <- mp(om, ctrl=control, args=list(iy=2025, fy=2030))
#> 2025 - 2026 - 2027 - 2028 - 2029 -
# Compute performance using all default statistics, data(statistics)
performance(mse, run="r00", type="test")
#> Key: <mp, type, statistic, year>
#> om biol mp year statistic name iter data
#> <char> <char> <char> <int> <char> <char> <int> <num>
#> 1: PLE PLE_test_r00 2025 C C (t) 1 1261.108
#> 2: PLE PLE_test_r00 2025 C C (t) 10 1303.160
#> 3: PLE PLE_test_r00 2025 C C (t) 100 1703.979
#> 4: PLE PLE_test_r00 2025 C C (t) 11 1402.612
#> 5: PLE PLE_test_r00 2025 C C (t) 12 1453.531
#> ---
#> 7880: PLE PLE_test_r00 2026 yellow P(Yellow) 1 0.890
#> 7881: PLE PLE_test_r00 2027 yellow P(Yellow) 1 0.870
#> 7882: PLE PLE_test_r00 2028 yellow P(Yellow) 1 0.780
#> 7883: PLE PLE_test_r00 2029 yellow P(Yellow) 1 0.740
#> 7884: PLE PLE_test_r00 2030 yellow P(Yellow) 1 0.720
#> type run desc
#> <char> <char> <char>
#> 1: test r00 Catch
#> 2: test r00 Catch
#> 3: test r00 Catch
#> 4: test r00 Catch
#> 5: test r00 Catch
#> ---
#> 7880: test r00 Probability of being in Kobe yellow quadrant
#> 7881: test r00 Probability of being in Kobe yellow quadrant
#> 7882: test r00 Probability of being in Kobe yellow quadrant
#> 7883: test r00 Probability of being in Kobe yellow quadrant
#> 7884: test r00 Probability of being in Kobe yellow quadrant
# or select a few of them
performance(mse, statistics=statistics[c("SBMSY", "FMSY")], run="r00", type="test")
#> Key: <mp, type, statistic, year>
#> om biol mp year statistic name iter data
#> <char> <char> <char> <int> <char> <char> <int> <num>
#> 1: PLE PLE_test_r00 2025 FMSY F/F[MSY] 1 1.2704782
#> 2: PLE PLE_test_r00 2025 FMSY F/F[MSY] 10 1.6370809
#> 3: PLE PLE_test_r00 2025 FMSY F/F[MSY] 100 1.2342225
#> 4: PLE PLE_test_r00 2025 FMSY F/F[MSY] 11 1.4703439
#> 5: PLE PLE_test_r00 2025 FMSY F/F[MSY] 12 1.5022282
#> ---
#> 1196: PLE PLE_test_r00 2030 SBMSY SB/SB[MSY] 95 0.6511697
#> 1197: PLE PLE_test_r00 2030 SBMSY SB/SB[MSY] 96 0.7036977
#> 1198: PLE PLE_test_r00 2030 SBMSY SB/SB[MSY] 97 0.9568992
#> 1199: PLE PLE_test_r00 2030 SBMSY SB/SB[MSY] 98 1.1840236
#> 1200: PLE PLE_test_r00 2030 SBMSY SB/SB[MSY] 99 0.9837542
#> type run desc
#> <char> <char> <char>
#> 1: test r00 Fishing mortality relative to FMSY
#> 2: test r00 Fishing mortality relative to FMSY
#> 3: test r00 Fishing mortality relative to FMSY
#> 4: test r00 Fishing mortality relative to FMSY
#> 5: test r00 Fishing mortality relative to FMSY
#> ---
#> 1196: test r00 Spawnwer biomass relative to SBMSY
#> 1197: test r00 Spawnwer biomass relative to SBMSY
#> 1198: test r00 Spawnwer biomass relative to SBMSY
#> 1199: test r00 Spawnwer biomass relative to SBMSY
#> 1200: test r00 Spawnwer biomass relative to SBMSY