Package 'FLOSS'

Description

Counts aged fish by length bin and age, from the biological samples.

Usage

alk_obs(
  data,
  species,
  iter = 1,
  source = NULL,
  years = NULL,
  bin_mm = NULL,
  prop = FALSE
)

Arguments

Value

a matrix, length bins (lower limit, mm) x ages.

Description

Converts the observations of one species and iteration into FLR objects:

Usage

as_flr(data, species = NULL, iter = 1, all = FALSE)

Arguments

Details

• catch: FLQuants, observed catch (t) by fleet (age "all"), and catch_total (FLQuant, all fleets), as jb3_data() of JABBA3 takes them;

• indices: FLIndices of FLIndexBiomass, one per fleet CPUE and the survey, with the log-scale standard error (from the sampling CV) in index.var, as JABBA3 expects;

• effort: FLQuants of effort by fleet (fishing days), for JABBA3's auxiliary data;

• lfd: FLQuants, one per gear (fleets and survey), length (lower bin limit, cm) x year, counts summed over seasons, as FLicc's fiticc() and stocklen() take them; lfd_raised the same raised to the catch (lfd_aggregate());

• lhpar: FLPar with linf, k, t0, M, L50, a, b, tmax and s (steepness), with a converted so that weight is in kg (FLicc convention; FLOSS uses g);

• catch_by_gear: share of the catch by fleet over the years with length samples (FLicc's catch_by_gear).

Value

a list of class floss_flr (or a list of them).

Examples

x <- simulate_fishery("lutjanus_bohar", nsim = 2, iters = 1)
f <- as_flr(x$data)
f$indices
# JABBA3: jb3_data(f$catch, f$indices, auxiliary = f$effort)
# FLicc:  stocklen(f$lfd[c("gillnet", "linefish")], f$lhpar)

Description

Apical fishing mortality of fleet $f$ is $F_{f,y} = q_f\,\eta_{f,y}\,E_{f,y}\,\delta_{f,y}$ with $q_f = relq_f \times F_{MSY}$, nominal effort $E$ and efficiency $\eta$ from effort_sim() (shared by all species), and optional species-specific catchability noise $\delta$ (sigmaQ). Fleet F-at-age is apical F times the fleet's selectivity-at-age; total F-at-age is the sum over fleets. The stock is projected with ffwd() under Fbar control and lognormal (optionally AR1) recruitment deviations. The first two years are dropped as burn-in, as in the reef example.

Usage

build_om(
  sp,
  fishery,
  nsim = 100,
  effort = NULL,
  sigmaQ = 0,
  ar1 = FALSE,
  seed = fishery$seed,
  treatment = NULL
)

Arguments

Details

Reference points are recomputed for the realised exploitation pattern (median F-at-age over iterations, last years) with FLRef::computeFbrp() and stored in the returned FLStockR.

Value

an object of class floss_om: a list with stock (FLStockR), sr (FLSR), brp (calibrated equilibrium), sel (fleet selectivities), fapic and f_fleet (FLQuants of apical F and F-at-age by fleet), effort, efficiency, species, fishery and settings.

Description

All species see the same effort realisation; recruitment deviations differ by species. Pass oms to reuse operating models already built for the same fishery (matched by species id and fishery hash), so adding a species does not rebuild the others.

Usage

build_oms(species_list, fishery, nsim = 100, oms = NULL, ...)

Arguments

Value

a named list of class floss_oms.

Description

Applies an observed age-length key to the length samples of each year, $\hat n_{a,y} = \sum_l n_{l,y} P(a \mid l)$. Length bins without aged fish cannot be assigned an age and are dropped (their share is reported). With raise = "catch" the numbers are raised so that their weight ($W = a L^b$, g) equals the observed catch of the source (t).

Usage

caa_obs(
  data,
  species,
  source,
  iter = 1,
  years = NULL,
  alk = c("pooled", "annual"),
  raise = c("none", "catch")
)

Arguments

Value

a data frame with species, iter, year, source, age, n, and attribute unassigned (share of measured fish per year in length bins without aged fish).

Description

Builds the FLife equilibrium (lhEql, ages 0:tmax, plus group tmax, constant M), applies the joint selectivity-at-age (fleet selectivities weighted by relative catchability, FLRef::combine_sel_age()) and rescales virgin biomass so that equilibrium MSY equals sp$msy (two passes of FLRef::updsr()).

Usage

calibrate_msy(sp, sels = NULL)

Arguments

Value

an FLBRP with reference points.

Description

Regression of $\log n_a$ on age over the descending limb of the catch-at-age (pooled over the selected years); total mortality $Z = -\text{slope}$. By default the fit starts one age after the mode and drops the last (plus-group) age.

Usage

catch_curve(
  x,
  species = NULL,
  source = NULL,
  iter = 1,
  years = NULL,
  ages = NULL,
  om = NULL
)

Arguments

Value

a floss_fit with pars (Z) and, when the true M is known, F = Z - M.

Description

Pauly's length-converted catch curve on the pooled length samples of one source, using growth parameters (e.g. from fit_growth()): relative age $t(L) = t_0 - \log(1 - L/L_\infty)/k$, time to grow through a bin $\Delta t$, and $\log(n/\Delta t)$ against $t$. Z is minus the slope of the descending limb. Selectivity on the ascending limb is the ratio of observed to expected numbers (the descending line extrapolated back), fitted with a logistic curve.

Usage

catch_curve_length(
  data,
  species,
  source,
  linf,
  k,
  t0 = 0,
  iter = 1,
  years = NULL,
  lmax_prop = 0.95
)

Arguments

Value

a floss_fit with pars (Z, L50, L95).

Description

Partial Baranov catch of each fleet from fleet F-at-age, total Z and numbers-at-age of the operating model: $C_{f,a,y} = N_{a,y}\,F_{f,a,y}/Z_{a,y}\,(1 - e^{-Z_{a,y}})$.

Usage

catch_fleet(om, type = c("wt", "n"))

Arguments

Value

FLQuants by fleet.

Description

• catch_table(): observed catch (t) by fleet, summed over fleets ("aggregate"), or summed over fleets and species ("combined").

• effort_table(): observed effort (fishing days) by fleet or summed over fleets.

• nominal_cpue(): catch / effort (kg per fishing day) at the chosen level, and as an index relative to its mean. "aggregate" divides the catch of all fleets by the effort of all fleets, ignoring that a day of trap fishing and a day of linefishing catch differently; "combined" also sums the catch of all species.

Usage

catch_table(data, species = NULL, by = c("fleet", "aggregate", "combined"))

effort_table(data, by = c("fleet", "aggregate"))

nominal_cpue(data, species = NULL, by = c("fleet", "aggregate", "combined"))

Arguments

Details

Nominal CPUE uses all years with catch and effort, unlike the CPUE index of sample_data() (which is a standardised index for the sampled years). With changing fleet mix or effort creep, nominal CPUE drifts away from the stock: compare it with cpue_true (true catch / true effort) and the true biomass.

Value

a data frame with species, iter, year, source (fleet or "all fleets") and the values (observed and true).

Examples

x <- simulate_fishery(nsim = 2, iters = 1)
head(nominal_cpue(x$data, by = "aggregate"))
plot_aggregate(x$data, "Lutjanus bohar", what = "cpue", by = "fleet")

Description

CPUE is assumed proportional to vulnerable biomass, $C/E = qB$. Fits $\log I = \log q + \beta \log B$ ($\beta = 1$: proportional; $< 1$: hyperstable; $> 1$: hyperdepletion) and the trend in $\log(I/B^\beta)$ over years (catchability drift, e.g. effort creep). Needs the answer key (index_true), so it works on a floss_data.

Usage

cpue_check(data, species, source, iter = 1)

Arguments

Value

a floss_fit with pars (beta, q_trend_pct per year, r).

Description

Nominal effort $E_{f,y}$ is the trend times multiplicative lognormal noise with mean one, $\exp(\epsilon - \sigma_E^2/2)$, $\epsilon\sim N(0,\sigma_E^2)$. The noise is drawn once per fishery and iteration, so all species share it. Efficiency (effort creep) is $\eta_{f,y} = (1 + c_f)^{\max(0, y - y^c_f)}$; it scales fishing mortality but not the nominal effort index.

Usage

effort_sim(fishery, nsim = 100, seed = fishery$seed)

Arguments

Value

a list with FLQuants effort (nominal) and efficiency, one element per fleet, each FLQuant(age = "all", year, iter = nsim).

Examples

eff <- effort_sim(reef_fishery(), nsim = 5)
eff$effort$traps

Description

Describes the shape of a fleet's nominal effort over time. "fudc" is the up-down-constant shape of FLRef::fudc(): effort starts at e0 in the first year, rises linearly to ⁠fhi x fref⁠ by the first break, moves linearly to ⁠flo x fref⁠ by the second break and stays there. "values" takes a user-supplied vector, one value per year.

Usage

effort_trend(
  type = c("fudc", "values"),
  e0 = 0.05,
  fhi = 1,
  flo = 0.8,
  fref = 1,
  breaks = c(0.5, 0.75),
  values = NULL
)

Arguments

Value

a list of class floss_trend.

Examples

effort_trend(fhi = 1, flo = 0.8, breaks = c(0.4, 0.6))

Description

Writes one folder (or workbook) per iteration with the observed data, the settings needed to re-create them, and, separately, the answer key:

Usage

export_data(
  data,
  dir,
  give = c("data_lh", "data"),
  format = "csv",
  answer_key = TRUE,
  aggregate = FALSE,
  zip = FALSE
)

Arguments

Details

<dir>/README.txt, settings.yaml
<dir>/iter_01/catch.csv effort.csv cpue.csv survey.csv lfd.csv bio.csv [lhpars.csv]
<dir>/answer_key/README_answer_key.txt truth.csv status.csv refpts.csv
  catch_true.csv bio_true_age.csv planted_artefacts.csv

Value

the folder, invisibly.

Description

Writes the true time series (SSB, recruitment, Fbar, catch, B/Bmsy, F/Fmsy, catch/MSY), the reference points and the status table, without any observed data.

Usage

export_truth(x, dir, format = "csv", year = NULL, iters = NULL)

Arguments

Value

the folder, invisibly.

Description

A fishery is a set of fleets that share a time horizon. Each fleet has a nominal effort trend, process noise on effort that is common to all species (so species caught by the same fleet share effort anomalies) and an optional annual efficiency increase (effort creep) that raises fishing mortality but is not visible in the nominal effort index.

Usage

fishery(
  fleets,
  years,
  trends,
  sigmaE = 0.15,
  creep = 0,
  creep_start = NULL,
  name = "fishery",
  seed = 123
)

validate_fishery(x)

fishery_years(x)

Arguments

Details

Fishing mortality of species $s$ by fleet $f$ in year $y$ is

$F_{s,f,y} = q_{s,f}\,\eta_{f,y}\,E_{f,y},\quad \eta_{f,y} = (1 + c_f)^{\max(0,\,y - y^{c}_f)},$

where $E$ is nominal effort (trend x lognormal noise), $c_f$ the creep rate and $q_{s,f}$ the species catchability, set in species() as relative catchability x $F_{MSY}$.

Value

a list of class floss_fishery.

Examples

fishery(fleets = c("traps", "linefish"), years = 1980:2025,
        trends = list(traps = effort_trend(fhi = 1, flo = 0.8),
                      linefish = effort_trend(fhi = 2, flo = 1)))

Description

Nonlinear least squares, $L = L_\infty(1 - e^{-k(a + \delta - t_0)})$, on the aged fish of the biological samples. Fish are caught during the year, so the observed (integer) age is shifted by age_offset (0.5 = mid-year) to make t0 comparable with the true value.

Usage

fit_growth(
  data,
  species,
  iter = 1,
  source = NULL,
  years = NULL,
  t0 = NULL,
  age_offset = 0.5
)

Arguments

Value

a floss_fit with pars (linf, k, t0).

Description

Linear regression of $\log W$ on $\log L$ (W in g, L in cm), with the lognormal bias correction $a = e^{\alpha + \sigma^2/2}$.

Usage

fit_lw(data, species, iter = 1, source = NULL, years = NULL)

Arguments

Value

a floss_fit with pars (a, b).

Description

Binomial GLM (logit link) of maturity (0/1) on length: $L_{50} = -\beta_0/\beta_1$, $L_{95} = (\log 19 - \beta_0)/\beta_1$.

Usage

fit_maturity(
  data,
  species,
  iter = 1,
  source = NULL,
  years = NULL,
  bin_cm = NULL
)

Arguments

Value

a floss_fit with pars (L50, L95).

Description

Builds FLRef::build_gear() objects (length selectivity, capture- conditioned length key, sample sizes) for every fleet and the survey, on the length grid of the sampling settings.

Usage

floss_gears(om, oem)

Arguments

Value

named list of gears.

Description

The guides are installed with the package (folder guide), whether or not the vignettes were built. floss_guide() writes a guide to dir as a stand-alone R Markdown file that you can edit and knit, plus an R script with its code, and with render = TRUE renders it to HTML.

Usage

floss_guide(
  guide = c("user-guide", "teaching", "cpue-aggregation", "methods", "how-it-works",
    "reef-om", "all"),
  dir = ".",
  render = FALSE,
  script = TRUE,
  open = interactive(),
  overwrite = FALSE
)

Arguments

Value

the paths of the files written, invisibly.

Examples

## Not run: 
floss_guide("user-guide")                 # floss-02-user-guide.Rmd and .R
floss_guide("all", dir = "guides", render = TRUE)

## End(Not run)

Description

The texts used for the information tooltips of the app.

Usage

floss_tip(id = NULL)

Arguments

Value

a character string (or a named list of all tips).

Examples

floss_tip("cpue_rho")

Description

The "rich colours" palette of r4ss and JABBA (rc4(), ss3col(), after rich.colors by Arni Magnusson): dark blue through green and yellow to red. For three colours it returns blue, red and green3, as in JABBA. Available for users who prefer the r4ss look; FLOSS plots use their own muted palette by default.

Usage

floss.r4col(n, alpha = 1)

Arguments

Value

a character vector of colours.

Examples

floss.r4col(4)
barplot(rep(1, 6), col = floss.r4col(6))

Description

From the length samples of each year and source:

Usage

length_indicators(
  x,
  species,
  iter = 1,
  source = NULL,
  Lc = NULL,
  lh = NULL,
  season_weight = c("none", "equal")
)

Arguments

Details

• Lc: length of first full capture, here the mid-point of the modal length bin of the pooled samples of the source (or given).

• Lmean: mean length of fish at or above Lc; L95: 95th percentile; Lmax5: mean length of the largest 5% of fish.

• Pmat, Popt, Pmega (Froese 2004): proportion of fish above the length at maturity, within 10% of the optimum length $L_{opt} = 3L_\infty/(3 + M/k)$, and above 1.1 $L_{opt}$.

• Z_lbar: total mortality from mean length (Beverton and Holt 1956), $Z = k(L_\infty - \bar L)/(\bar L - L_c)$. It assumes equilibrium: constant recruitment and mortality, and flat-topped selectivity.

• Z_true (when the answer key is present): true Fbar + M in that year, to show when and why Z_lbar departs from it.

Value

a data frame, one row per species, iteration, year and source.

Description

• raise = "sample": the counts as measured. Pooled over fleets (by = "aggregate"), each fleet weighs by its sample size, not by its catch: a fleet that is sampled heavily but catches little dominates the pooled distribution.

• raise = "catch": each fleet's (season-weighted) sample is raised to the fleet's observed catch: numbers = sample numbers x catch (t) / sample weight (t), with weights from the length-weight relationship. Pooled over fleets, each fleet then weighs by its catch.

Usage

lfd_aggregate(
  data,
  species = NULL,
  by = c("fleet", "aggregate"),
  raise = c("sample", "catch")
)

Arguments

Details

Seasons are pooled for the year: counts summed for "sample", equal season weights for "catch" (lfd_annual()). The survey is not included.

Value

a data frame like data$lfd without season (n is numeric when raised).

Description

Sums the length samples of all seasons of a year. With weight = "equal" each season gets the same weight whatever its sample size (each season's distribution is rescaled to the mean seasonal sample size before summing), which removes the bias of imbalanced sampling when the catch is spread evenly over the year.

Usage

lfd_annual(lfd, weight = c("none", "equal"))

Arguments

Value

the table without the season column.

Description

Example fishery shipped with the package

Usage

load_fishery(name = "reef_3fleets")

Arguments

Description

Empirical natural mortality estimators

Usage

M_empirical(linf = NULL, k = NULL, tmax = NULL, temp = NULL)

Arguments

Value

a data frame with method, M and inputs.

Examples

M_empirical(linf = 71.4, k = 0.21, tmax = 16)

Description

Collects every setting of the observation model. Arguments that can differ by fleet take one value or a vector named by fleet. Catch and effort cover all years of the operating model; CPUE, length frequencies and biological samples cover the last tail years of each fleet (or years).

Usage

oem_settings(
  fishery,
  tail = 10,
  catch_cv = 0.1,
  catch_bias = 0,
  effort_cv = 0.1,
  effort_days = 1000,
  cpue_cv = 0.2,
  cpue_rho = 0.3,
  cpue_creep = TRUE,
  cpue_beta = 1,
  lfd_ess_age = 30,
  lfd_ess_len = 300,
  lfd_bin = NULL,
  lfd_cv = 0.1,
  bio_n = 100,
  bio_p_aged = 0.5,
  bio_age_scheme = c("random", "stratified"),
  bio_n_per_bin = 5,
  age_cv = 0.1,
  wt_cv = 0.1,
  mat_L95 = 1.15,
  catch_bias_from = NULL,
  cpue_q_step = NULL,
  bio_age_bias = 0,
  survey = survey_settings(),
  years = NULL,
  seasons = season_design(4)
)

Arguments

Details

• Catch by fleet: true catch x (1 - bias) x lognormal error.

• Effort index by fleet: nominal effort x lognormal error (effort creep is not visible).

• CPUE by fleet: vulnerable biomass x efficiency (if cpue_creep) with lognormal AR1 residuals, $\epsilon_y = \rho\,\epsilon_{y-1} + \sqrt{1-\rho^2}\,\delta_y$. Use $\rho > 0$ for non-random (clustered) sampling of the fleet.

• Length frequencies: the two-stage FLRef protocol (FLRef::lfd.sim()): lfd_ess_age clusters drawn from the fleet's catch-at-age, then lfd_ess_len fish measured through the gear's length key.

• Biological samples: bio_n fish per fleet and year with length (mm), age (with ageing error; aged at random or length-stratified), weight (g, with error) and maturity (0/1).

Value

a list of class floss_oem.

Examples

oem_settings(reef_fishery(), tail = c(traps = 5, gillnet = 10, linefish = 15))

Description

A fishery with a single fleet whose effort is directly F/Fmsy when used with one_gear_species(). Use for light vs hard fishing comparisons.

Usage

one_gear_fishery(
  F_rel = 1,
  years = 1969:2025,
  fleet = "handline",
  ramp = 10,
  sigmaE = 0.1,
  seed = 123
)

Arguments

Value

a floss_fishery.

Examples

light <- one_gear_fishery(0.5)
hard  <- one_gear_fishery(2)

Description

Copies a species with a single fleet (default a logistic handline with L50 at the length at maturity) and scales its catchability so that the fishery's effort equals F/Fmsy.

Usage

one_gear_species(sp, fleet = "handline", sel = NULL)

Arguments

Value

a floss_species.

Description

Lists every setting that makes the data depart from the stock in a way a careful analyst should detect (the "warning flags"): effort creep carried by CPUE, non-proportional CPUE, strongly autocorrelated residuals, catch bias, catchability steps, ageing bias and very small length samples, plus treatments applied to the operating model. Written to the answer key by export_data().

Usage

planted_artefacts(oem, fishery = NULL, treatment = NULL)

Arguments

Value

a data frame with artefact, where, detail (empty if none).

Description

One panel per fleet (or one for all fleets); with several iterations the lines are coloured by iteration. With truth = TRUE, true values are dashed: for nominal CPUE, true catch / true effort, and in grey the true spawning biomass relative to its mean, to show how far nominal CPUE is from the stock.

Usage

plot_aggregate(
  data,
  species = NULL,
  iter = 1,
  what = c("cpue", "catch", "effort"),
  by = c("fleet", "aggregate", "combined"),
  truth = FALSE
)

Arguments

Value

a ggplot.

Description

One row per data stream and source, one tile per year with data.

Usage

plot_availability(data, species = NULL, iter = 1)

Arguments

Value

a ggplot.

Description

• "age_length": length against observed age.

• "length_weight": weight against length.

• "maturity": observed proportion mature by length bin (point size = number of fish).

• "alk": observed age-length key (counts; bubble area).

• "length": length composition of the biological samples.

Usage

plot_bio(
  data,
  species = NULL,
  iter = 1,
  what = c("age_length", "length_weight", "maturity", "alk", "length"),
  source = NULL,
  by = c("fleet", "aggregate", "season"),
  truth = FALSE
)

Arguments

Details

Points are always coloured by fleet (or survey); by sets the panels. With truth = TRUE the true relationship of the operating model is drawn over the observations: the von Bertalanffy growth curve (at the middle of the sampling season, or mid-year), the length-weight curve and the maturity ogive.

Value

a ggplot.

Plot catch-at-age from caa_obs()

Description

Plot catch-at-age from caa_obs()

Usage

plot_caa(caa, type = c("bubble", "bar"))

Arguments

Value

a ggplot.

Description

Median and 90% interval of nominal effort by fleet, with a few individual iterations. With efficiency = TRUE the effective effort (nominal x efficiency) is shown as well, to visualise effort creep.

Usage

plot_effort(x, nsim = 100, iters = 1:3, efficiency = FALSE)

Arguments

Value

a ggplot.

Examples

plot_effort(reef_fishery(creep = 0.02), efficiency = TRUE)

Description

Yield, SSB and recruitment against F and SSB at equilibrium (FLRef::ploteq()), with the stock's yearly values as points (obs = TRUE). During a fishing-down phase catches lie above the equilibrium yield curve: high catches are possible only while biomass is being removed. The curves are for the exploitation pattern of the last years; with a changing fleet mix, earlier years belonged to a different equilibrium.

Usage

plot_eq(om, iter = 1, obs = TRUE, rel = FALSE)

Arguments

Value

a ggplot.

Description

The same stock (life history, recruitment, unfished biomass) fished with different selectivities: equilibrium yield and SSB against F (Fbar). Catching fish before they have grown lowers the maximum yield and the F at which it is reached (growth overfishing); protecting small fish raises both. Points mark MSY for each selectivity.

Usage

plot_eq_selectivity(sp, sels, fmax = 10)

Arguments

Value

a ggplot.

Examples

sp <- load_species("lutjanus_bohar")
plot_eq_selectivity(sp, list(
  small = selectivity("logistic", L50 = 25, L95 = 30),
  mature = selectivity("logistic", L50 = 35, L95 = 42),
  large = selectivity("logistic", L50 = 50, L95 = 58)))

Description

Draws the observations, the fitted curve and the estimates; with truth = TRUE (trainers) the true curve or values are added as dashed lines.

Usage

plot_fit(fit, truth = FALSE, what = NULL)

Arguments

Value

a ggplot.

Description

Plot apical fishing mortality or catch by fleet

Usage

plot_fleets(om, what = c("fapic", "catch"), iters = 1:3)

Arguments

Value

a ggplot.

Description

All series of one species on one page, each scaled to its own mean: abundance indices (CPUE by fleet, survey), total catch, and mean length and Pmega by source. Independent indicators of the same stock should broadly agree; where they diverge, one of them is probably not tracking the stock (e.g. effort creep, a gear change, a cohort passing through).

Usage

plot_indicators(data, species = NULL, iter = 1, truth = FALSE)

Arguments

Value

a ggplot.

Description

True B/Bmsy against F/Fmsy, coloured by species. With several iterations, one point per species and iteration in the assessment year. With one iteration (or trajectory = TRUE), the whole history of each species is drawn as a path from the first year (open circle) to the assessment year (filled circle), as in JABBA's Kobe plot.

Usage

plot_kobe(x, year = NULL, iters = NULL, species = NULL, trajectory = NULL)

Arguments

Value

a ggplot.

Description

Mean length (with the optimum length and Lc), the share of mature, optimum-sized and mega-spawning fish, and Z from mean length against the true Z. With several runs (from a floss_treatments), runs are coloured and sources are panels.

Usage

plot_length_indicators(li, source = NULL, stat = c("median", "all"))

Arguments

Value

a ggplot.

Description

• type = "bars" (default): the classic length-frequency histogram, one panel per year (rows) and source (columns), see below.

• type = "ridge": one length distribution per year, drawn as a ridge along the time axis (as FLRef's plot_lfd_ridgeline()), one panel per source; with cohorts = TRUE, von Bertalanffy lines follow each year class, so modes can be followed along them.

• type = "bubble": one row per year, bubble area = proportion of the year's sample at each length. With cohorts = TRUE, von Bertalanffy growth lines follow each year class through the samples: real modes move along these lines; patterns that jump or vanish are sampling noise or selectivity, not dynamics.

• type = "bars": the classic length-frequency histogram, one panel per year (rows) and source (columns), as proportions of each year's sample. With cohorts = TRUE, the mean length of each age class in that year is marked at the top, so modes can be matched to year classes.

Usage

plot_lfd(
  data,
  species = NULL,
  iter = 1,
  source = NULL,
  type = c("bars", "ridge", "bubble"),
  years = NULL,
  cohorts = FALSE,
  season = NULL,
  lfd = NULL,
  by_season = FALSE
)

Arguments

Details

Seasonal samples are pooled for the year (counts summed), unless by_season = TRUE: then each season is shown separately (histogram: a panel per year and season; ridge: one ridge per season within the year, coloured by season, as FLRef's plot_lfd_ridgeline() with seasonal data; bubble: seasons stacked within the year). Fish grow through the year, so modes move to the right from season to season; with imbalanced sampling (season_design()) some seasons have few or no samples.

Value

a ggplot.

Examples

x <- simulate_fishery("lutjanus_bohar", nsim = 2, iters = 1)
plot_lfd(x$data, cohorts = TRUE)
plot_lfd(x$data, type = "bars", source = c("gillnet", "linefish"))

Description

Plot observed catch, CPUE and survey indices

Usage

plot_obs(
  data,
  species = NULL,
  iter = 1,
  what = c("index", "catch"),
  truth = FALSE
)

Arguments

Value

a ggplot.

Description

Thin wrapper around FLRef::plotAdvice(). Several species are shown relative to their own reference points (B/Bmsy, F/Fmsy, C/MSY).

Usage

plot_om(om)

Arguments

Value

a ggplot.

Description

Left: fish measured per season and year (how balanced the sampling is). Right: mean length by season and year, with the pooled annual mean (black) and the mean with equal season weights (dashed). Fish grow through the year, so later seasons have larger fish; when most samples come from one part of the year, the pooled mean follows that season, and a shift in the sampling season looks like a change in the stock.

Usage

plot_seasons(data, species = NULL, iter = 1, source = NULL)

Arguments

Value

a ggplot.

Description

The Beverton-Holt curve of the operating model with the SSB-recruitment pairs of the selected iterations (recruitment at age 0 in the same year). The scatter is the recruitment variability (sigmaR); it is why steepness is hard to estimate from data.

Usage

plot_srr(om, iters = 1:3)

Arguments

Value

a ggplot.

Description

Who reproduces and who is caught are not the same fish. The left panel compares each fleet's selectivity-at-length with the maturity ogive; the right panel compares the trend in spawning biomass (SSB, reproductive potential) with the trend in each fleet's vulnerable biomass (the biomass its catches and CPUE come from), both relative to the first year. With dome-shaped selectivity, large spawners escape: a fleet's CPUE can fall faster or slower than SSB, so an index can be a distorted picture of the reproductive stock.

Usage

plot_ssb_vb(om, iters = NULL)

Arguments

Value

a ggplot (two panels, via facets).

Description

True B/Bmsy, F/Fmsy, catch/MSY and recruitment (relative to the baseline mean) for the baseline and each treatment: median and 90% interval over iterations; the treatment start is marked.

Usage

plot_treatment(x, species = NULL)

Arguments

Value

a ggplot.

Description

B/Bmsy, F/Fmsy and catch/MSY over time by species, one line per dataset (iteration), with the reference level 1 dashed (as FLRef::plotAdvice() on ratios).

Usage

plot_truth(x, species = NULL, iters = NULL)

Arguments

Value

a ggplot.

Description

Reads the csv files of one exported iteration back into a list of data frames, so that trainees (or the plotting functions) can use them.

Usage

read_dataset(dir)

Arguments

Value

a list of data frames (catch, effort, cpue, survey, lfd, bio, lhpars where present), each with an iter column set to 1.

Description

Traps, gillnet and linefish, 1969-2025, with the effort trends of the multi-gear reef operating model (Winker, FLsim multigear reef example).

Usage

reef_fishery(sigmaE = 0.15, creep = 0, seed = 123)

Arguments

Value

a floss_fishery.

Examples

reef_fishery()

Description

Length, CPUE and biological samples cover the most recent 5 years for traps, 10 for gillnet and 15 for linefish; linefish CPUE residuals are more autocorrelated (clustered fishing).

Usage

reef_oem(...)

Arguments

Value

a floss_oem.

Description

Opens the FLOSS Shiny app: build a fishery and species, the operating model, treatments, sampling and export, step by step in the left panel. The app uses the same functions as the package, so everything done in the app can be repeated in a script.

Usage

run_app(...)

Arguments

Value

called for its side effect (runs the app).

Examples

if (interactive()) run_app()

Description

Builds the baseline operating model(s) and one per treatment, all with the same effort noise, recruitment deviations and (when oem is given) sampling random numbers.

Usage

run_treatment(
  species,
  fishery,
  treatments,
  nsim = 20,
  oem = NULL,
  iters = 1,
  seed = fishery$seed,
  ...
)

Arguments

Value

a list of class floss_treatments with oms and (if oem) data, each a named list (baseline, then the treatments).

Description

Samples catch, effort, CPUE, survey index, length frequencies and biological samples from one or several operating models, for the chosen iterations, and returns them with the truth (answer key).

Usage

sample_data(om, oem, iters = 1:10, seed = 123)

sample_catch(om, oem, iters = 1:10)

sample_effort(om, oem, iters = 1:10)

sample_cpue(om, oem, iters = 1:10)

sample_survey(om, oem, iters = 1:10)

sample_lfd(om, oem, iters = 1:10)

sample_bio(om, oem, iters = 1:10)

Arguments

Details

Each data stream of each species uses its own reproducible random stream, so changing e.g. the biological-sample settings does not change the CPUE.

Value

an object of class floss_data: a list of data frames catch, effort, cpue, survey, lfd, bio, lhpars, truth, refpts, plus settings (fishery, species and sampling specs).

Functions

• sample_catch(): observed catch by fleet (t).

• sample_effort(): observed nominal effort by fleet, in fishing days (relative effort x effort_days of the fleet).

• sample_cpue(): CPUE by fleet with AR1 lognormal residuals, scaled to mean 1 over the sampled years; index_true is the true vulnerable biomass (without effort creep).

• sample_survey(): survey biomass index (relative to its mean).

• sample_lfd(): two-stage length samples by fleet and survey, by season (see season_design()); len_mm is the lower bin limit.

• sample_bio(): biological samples: one row per fish, by season.

Description

Describes how the annual length and biological samples of a fleet are spread over seasons. The default, four seasons with equal shares, is a balanced design. Imbalanced designs:

Usage

season_design(
  n = 4,
  share = NULL,
  shift = NULL,
  kappa = Inf,
  n_mult = NULL,
  p_missing = 0,
  labels = NULL
)

Arguments

Details

• fixed imbalance: unequal share, e.g. c(0.5, 0.3, 0.2, 0) (most samples early in the year, none in season 4, e.g. a monsoon closure of the landing site);

• shift: the shares change from a given year (shift), e.g. a new observer programme that samples in the second half of the year only;

• opportunistic: the shares vary at random from year to year around share (kappa, the concentration of a Dirichlet distribution: 50 = small departures, 5 = large ones), as when samples are taken whenever an observer happens to be available.

Sampling intensity over the years:

• intensity change: the annual sample size is multiplied by n_mult from a year on (list(from = 2020, mult = 0.3): a funding cut), with an optional ramp over over years;

• missing years: each year is not sampled at all with probability p_missing.

Within a season, the age composition of the catch is the Baranov catch between the start and end of the season (fishing effort and natural mortality constant through the year), and lengths are those at the middle of the season (von Bertalanffy growth with age + season mid-point). Because effort is constant within the year, the catch of each season is known from the dynamics, and equal season weights (lfd_annual()) are the correct way to pool unevenly spread samples.

Value

a list of class floss_seasons.

Examples

season_design()                                   # balanced, 4 seasons
season_design(share = c(0.6, 0.3, 0.1, 0))         # fixed imbalance
season_design(shift = list(from = 2015, share = c(0, 0, 0.5, 0.5)))
season_design(kappa = 5)                           # opportunistic

Description

Arguments follow FLRef::sel_la(): "logistic" uses L50, L95; "normal" uses Lpeak, sd; "dnormal" uses Lpeak, sd_left, sd_right. Lengths in cm.

Usage

selectivity(
  type = c("logistic", "normal", "dnormal"),
  L50 = NULL,
  L95 = NULL,
  Lpeak = NULL,
  sd = NULL,
  sd_left = NULL,
  sd_right = NULL
)

Arguments

Value

a list of class floss_sel.

Examples

selectivity("dnormal", Lpeak = 20, sd_left = 5, sd_right = 15)

Description

Wrapper around build_oms() and sample_data().

Usage

simulate_fishery(
  species = species_library()$id,
  fishery = load_fishery(),
  oem = NULL,
  nsim = 20,
  iters = 1:min(10, nsim),
  seed = 123,
  ...
)

Arguments

Value

a list with oms (floss_oms) and data (floss_data).

Examples

sim <- simulate_fishery("siganus_sutor", reef_fishery(), nsim = 5, iters = 1)
sim$data

Description

Define a species

Usage

species(
  species,
  common_name = "",
  lh,
  msy,
  sel,
  relq,
  productivity = "",
  id = NULL
)

validate_species(x, fishery = NULL)

Arguments

Value

a list of class floss_species.

Description

Life-history FLPar for FLife

Usage

species_lhpar(sp)

Arguments

Value

FLPar from FLife::lhPar().

Description

The library combines the read-only example species shipped with the package and the species saved by the user with save_species(), which are kept in tools::R_user_dir("FLOSS", "data") (override with options(FLOSS.user_dir = ...)). A user species with the same id as an example takes precedence.

Usage

species_library()

load_species(id)

save_species(x, overwrite = FALSE)

delete_species(id)

Arguments

Value

species_library(): a data frame with one row per species (id, species, common_name, msy, source, file).

Examples

species_library()
load_species("siganus_sutor")

Description

Wraps FLRef::sel_la() for every fleet of the species, over ages 0:tmax.

Usage

species_sel(sp, lhpar = species_lhpar(sp))

Arguments

Value

named list (one per fleet) of sel_la() results.

Description

Summarises the true status of each species in each dataset (iteration): B/Bmsy, F/Fmsy and catch/MSY in a given year, and the Kobe status ("Healthy": B >= Bmsy and F <= Fmsy; "Overfishing": F > Fmsy with B >= Bmsy; "Overfished": B < Bmsy with F <= Fmsy; "Overfished and overfishing": both).

Usage

status_table(x, year = NULL, iters = NULL, summary = FALSE)

Arguments

Value

a data frame.

Description

A fishery-independent survey that samples every species. Because one survey gear meets species of very different size, its selectivity is given relative to each species' L-infinity (e.g. L50 = 0.2 means 50% selected at 20% of Linf).

Usage

survey_settings(
  years = NULL,
  timing = 0,
  cv = 0.25,
  rho = 0,
  sel = list(type = "logistic", L50 = 0.2, L95 = 0.3),
  lfd = TRUE,
  ess_age = 50,
  ess_len = 500,
  bio_n = 0,
  q_step = NULL
)

Arguments

Value

a list of class floss_survey.

Description

A treatment is one or more controlled changes applied to an operating model from a given year. Run with run_treatment(), the baseline and the treated operating models share every random number (effort noise, recruitment deviations, sampling), so all differences come from the treatment.

Usage

treatment(
  name = "treatment",
  effort = NULL,
  recruitment = NULL,
  selectivity = NULL,
  creep = NULL,
  M = NULL
)

Arguments

Details

Components (each optional, NULL = no change):

• effort: list of fleet, from, mult: nominal effort of the fleet is multiplied by mult from year from (mult = 0: fleet leaves; a value0 for a fleet with no effort before has no effect, so use the fisherytrend to add a fleet).

• recruitment: list with type = "pulse" (years, mult), "trend" (from, rate per year, e.g. -0.05) or "regime" (from, mult): multiplies the recruitment deviations.

• selectivity: list of fleet, from, sel (a selectivity()): the fleet's selectivity changes from year from (e.g. a gear switch or a minimum size).

• creep: list of fleet, from, rate: efficiency increases by rate per year from from (in addition to the fishery's own creep).

• M: list of from, mult: natural mortality is multiplied from from.

Several entries of one component are given as a list of lists.

Value

a list of class floss_treatment.

Examples

treatment("halve linefish effort",
          effort = list(fleet = "linefish", from = 2010, mult = 0.5))
treatment("strong 2015 year class",
          recruitment = list(type = "pulse", years = 2015, mult = 5))

Description

Deterministic effort trend values

Usage

trend_values(trend, years)

Arguments

Value

numeric vector, one value per year.

Examples

trend_values(effort_trend(fhi = 2, flo = 1, breaks = c(0.5, 0.8)), 1969:2025)

Description

Species and fishery specs are stored as plain YAML so that they can be edited by hand, shared between trainers and kept under version control.

Usage

write_spec(x, file)

read_spec(file)

Arguments

Value

write_spec() returns file invisibly; read_spec() returns the spec, re-validated through its constructor.

Examples

f <- tempfile(fileext = ".yaml")
write_spec(reef_fishery(), f)
read_spec(f)