A family of utilities for persisting, retrieving, labelling, summarizing,
and reshaping performance statistics tables produced by
mse::performance().
validatePerformance(dat)
hasPerformance(file = "model/performance.dat.gz", om = NULL, type = NULL, run = NULL)
listPerformance(file = "model/performance.dat.gz")
deletePerformance(
file = "model/performance.dat.gz",
om = NULL,
type = NULL,
run = NULL,
mp = NULL,
dry_run = FALSE
)
diffPerformance(dat, file = "model/performance.dat.gz")
writePerformance(dat, file = "model/performance.dat.gz", overwrite = FALSE)
readPerformance(file = "model/performance.dat.gz")
summaryPerformance(file = "model/performance.dat.gz")
labelPerformance(dat, labels = NULL)
setLabelPerformance(file = "model/performance.dat.gz", labels)
periodsPerformance(x, periods)
extractPerformance(dat, mp)
getOMPerformance(path, pattern = "*.rds", fy, ...)
getMSEPerformance(path, pattern = "*.rds")A data.table containing performance statistics, as returned by
mse::performance(), or an object of class FLmse or FLmses from
which performance statistics can be extracted automatically.
A character string giving the path to the performance table
file. Defaults to "model/performance.dat.gz". The .gz extension
causes data.table::fwrite() / data.table::fread() to use gzip
compression transparently.
Logical. If TRUE, any existing file at file is
overwritten entirely. If FALSE (default), existing rows not conflicting
with dat are preserved and new rows are appended; conflicts are resolved
by an anti-join on biol, statistic, year, iter, om, type,
and run.
Character scalar identifiers used to filter the stored table. Any combination may be supplied; unspecified arguments are ignored.
The labelling specification used by labelPerformance() and
setLabelPerformance(). Accepted forms:
NULL (default)Each row is labelled by its mp value if one
is present, or by om otherwise.
"numeric"Management procedures are assigned sequential labels
"MP1", "MP2", … in the order they appear.
listNames are matched against mp (or om) and the
values are used as labels.
data.frame or data.tableMust contain columns element
and label; element is matched against mp (or om).
A data.table containing performance statistics for
periodsPerformance(), as returned by mse::performance() or
readPerformance(). Must contain at least year, data, type, mp,
statistic, name, desc, and iter.
A vector or list whose elements define the years belonging to
each period (used by periodsPerformance()). Named elements use the name
as the period label; unnamed elements are labelled automatically from the
year range (e.g. "2026-35").
A character value (or vector) used by extractPerformance().
Length-1 values are matched with data.table::like() (%like%) so
partial strings and regular-expression patterns are accepted; vectors are
matched exactly with %in%.
A character string giving the directory containing serialized
files, used by getOMPerformance() and getMSEPerformance().
A character string passed to base::list.files() to filter
which files are read. Defaults to "*.rds".
The final year to which each operating model is trimmed with
FLCore::window() before performance is computed
(getOMPerformance() only).
Additional arguments forwarded to mse::performance()
(getOMPerformance() only).
Logical. If TRUE (default FALSE), return the
rows that would be deleted without writing any changes.
writePerformance(), setLabelPerformance()Invisibly TRUE.
deletePerformance()Invisibly, a data.table of the deleted
rows. When dry_run = TRUE, the rows that would be deleted are
returned visibly without modifying the file.
diffPerformance()A named list with elements new,
replace, and unchanged, each a data.table.
readPerformance()A data.table keyed by om, type, run,
biol, mp, statistic, and year, with grouping columns as
factors and column order fixed as om, type, run, mp, biol,
statistic, name, desc, year, iter, data.
summaryPerformance()Invisibly TRUE (called for its printed
side-effect).
labelPerformance()A copy of dat with a label factor column
added or replaced; OM-only rows appear first in the factor levels.
periodsPerformance()A data.table with one row per grouping
combination and period, containing period, year (compact range
string), data (period mean), and the inherited grouping columns.
extractPerformance()A subset of dat containing the matched MP
rows and their corresponding OM baseline rows (mp == "").
getOMPerformance(), getMSEPerformance()A data.table produced
by row-binding the performance results from all matching files.
validatePerformance()Checks required columns, numeric types, NA values in key columns, and key uniqueness; stops or warns on failure.
hasPerformance()Returns TRUE if the file contains rows
matching the supplied identifiers, without loading the full table.
listPerformance()Returns a catalogue data.table of
(om, type, run, mp) combinations with row counts and year ranges.
deletePerformance()Deletes rows matching supplied identifiers;
supports a dry_run preview mode.
diffPerformance()Compares an in-memory table against the stored file and categorises rows as new, replace, or unchanged.
writePerformance()Serializes a table to disk, merging with any existing file.
readPerformance()Reads a stored table and restores column classes, key, and factor levels.
summaryPerformance()Prints a compact console summary.
labelPerformance()Adds or replaces the label column.
setLabelPerformance()Reads, re-labels, and overwrites a stored table.
periodsPerformance()Aggregates annual statistics into user-defined periods.
extractPerformance()Subsets to selected MPs together with their OM baseline rows.
getOMPerformance()Batch-reads OM files and returns a combined performance table.
getMSEPerformance()Batch-reads MSE result files and returns a combined performance table.
writePerformance
Before writing, all columns are coerced to character and then year and
data are restored to numeric to ensure a consistent serialization format.
Optional columns are normalized: if neither type nor run is present,
empty character columns for type, run, and mp are added; if mp is
absent but type and run are present, mp is constructed by pasting
om, type, and run with "_"; if label is absent it is set to mp
when an MP is present, otherwise to om. Column order is standardized to
om, type, run, mp, biol, statistic, name, desc, year,
iter, data before writing.
readPerformance
Reading is performed with data.table::fread() with explicit colClasses
to avoid ambiguous type inference (e.g. when iter contains non-numeric
labels or mp is an empty string). The key set by data.table::setkey()
enables efficient subsetting and is assumed by several downstream functions.
The label column is optional; when absent it is not created — use
labelPerformance() to add it after reading.
periodsPerformance
periods is coerced to a list internally. The compact year label uses only
the last two digits of the final year (2026:2035 → "2026-35"). Missing
values in data are silently ignored (na.rm = TRUE). When x contains a
label column the grouping includes it; otherwise grouping is by type,
mp, statistic, name, desc, and iter.
extractPerformance
Operating model baseline rows are identified by an empty string in mp.
For scalar mp, matching uses %like%; use anchored patterns (e.g.
"^HCR1$") when MP names share substrings. For vectors, exact matching
(%in%) is used.
getOMPerformance
Each .rds file is expected to contain a list-like object with an $om
component compatible with FLCore::window() and mse::performance().
Warnings from mse::performance() are suppressed with
base::suppressWarnings(); re-run individual files interactively if
unexpected results appear.
getMSEPerformance
If a file's deserialized object already inherits from data.table it is
returned directly, allowing pre-computed performance summaries to be mixed
with raw MSE objects. fill = TRUE in data.table::rbindlist() tolerates
minor column-structure differences across files.
validatePerformance(): Validate a performance statistics table,
checking for required columns, correct numeric types, NA values in key
columns, and duplicate rows on the composite primary key.
hasPerformance(): Test whether a stored performance table
contains rows matching the supplied identifiers, without reading the full
table into memory.
listPerformance(): Return a compact catalogue of the
(om, type, run, mp) combinations stored in a performance file,
together with row count, year range, and number of distinct iterations —
without loading the data column.
deletePerformance(): Delete rows from a stored performance table
that match the supplied identifiers. When dry_run = TRUE the rows
that would be deleted are returned without modifying the file.
diffPerformance(): Compare an in-memory performance table against
a stored file and categorise every row as new, replace
(key exists in file), or unchanged (key exists and values are
identical). Returns a named list of three data.tables; the file
is not modified.
readPerformance(): Read a performance statistics table from disk,
restoring column classes, data.table key, column order, and factor levels.
summaryPerformance(): Print a compact console summary of the number
of operating models, MP types, and management procedures, together with
per-group year ranges and iteration counts.
labelPerformance(): Add or replace the label factor column
in a performance statistics table; OM-only rows appear first in the factor
levels.
setLabelPerformance(): Convenience wrapper that reads a stored
performance table, updates its label column via
labelPerformance(), and writes the result back, replacing the previous
contents.
periodsPerformance(): Collapse annual performance statistics into
broader user-defined periods by computing the mean of data over
the years belonging to each period.
extractPerformance(): Subset a performance table to the rows
belonging to management procedures matching a pattern, together with their
corresponding OM baseline rows (mp == "").
getOMPerformance(): Batch-read serialized OM files, trim each to
fy with FLCore::window(), compute mse::performance(), and
row-bind the results into a single table.
getMSEPerformance(): Batch-read serialized MSE result files or
pre-computed performance data.table files and row-bind them into a
single table.
mse::performance(), mse::FLmse, mse::FLmses,
FLCore::window(), performanceFLQuants()
if (FALSE) { # \dontrun{
## writePerformance / readPerformance
writePerformance(perf_dat)
dat <- readPerformance()
dat <- readPerformance("results/performance.dat.gz")
## validatePerformance
validatePerformance(perf_dat)
## hasPerformance
hasPerformance()
hasPerformance(om = "ple.27.420")
if(!hasPerformance(om = "ple.27.420", run = "r01"))
writePerformance(perf_dat)
## listPerformance
listPerformance()
listPerformance("results/performance.dat.gz")
## diffPerformance
d <- diffPerformance(perf_dat)
d$replace
if(nrow(d$replace) == 0) writePerformance(perf_dat)
## deletePerformance
deletePerformance(om = "ple.27.420", run = "r01", dry_run = TRUE)
deletePerformance(om = "ple.27.420", run = "r01")
deletePerformance(mp = "hcr_Fmsy")
## summaryPerformance
summaryPerformance()
summaryPerformance(dat)
## labelPerformance
dat <- labelPerformance(dat)
dat <- labelPerformance(dat, labels = "numeric")
dat <- labelPerformance(dat, labels = list(
hcr01 = "Conservative HCR", hcr02 = "Moderate HCR"))
## setLabelPerformance
setLabelPerformance(labels = "numeric")
setLabelPerformance("results/performance.dat.gz",
labels = list(hcr01 = "Low F", hcr02 = "High F"))
## periodsPerformance
res <- periodsPerformance(dat, periods = list(
short = 2021:2025,
medium = 2026:2035,
long = 2036:2050))
## extractPerformance
sub <- extractPerformance(dat, "HCR1")
sub <- extractPerformance(dat, "^HCR1$")
## getOMPerformance
dat <- getOMPerformance("om", fy = 2025)
dat <- getOMPerformance("om", fy = 2025, probs = c(0.1, 0.5, 0.9))
## getMSEPerformance
dat <- getMSEPerformance("mse")
dat <- getMSEPerformance("mse", pattern = "scenario_.*\\.rds$")
} # }