Diagnose catch-conditioned exploitation without changing population dynamics

Applies to the exploitation-fraction formulation (catch_like = -1), not instantaneous fishing mortality. A numerical guard (raw survival < 0.02) is distinct from overdrawn occupied cells (raw survival < -tolerance). Retained catch and handling deaths are combined across all fisheries before checking each sex/length cell. Empty cells are not counted as overdrawn.

Usage

diagnose_exploitation(
  report,
  catch_ytrf = NULL,
  years = NULL,
  details = TRUE,
  tolerance = 1e-10
)

Arguments

report

Numeric output of do_dynamics() or a decamod obj$report().

catch_ytrf

Optional prescribed catch array, in tonnes, with dimensions year, season, region, and fishery. Omit for projections prescribed in U.

years

Optional integer year indices to inspect (not calendar years).

details

Return cell-level and fishery-level data frames as well.

tolerance

Numerical tolerance on the dimensionless excess over U = 1. Does not alter the existing numerical guard threshold.

Value

List with annual summary, optional cells, and catch_checks. All biomass/catch magnitudes are tonnes. Indices identify the source arrays.

Details

Magnitudes use numbers and biomass at the mid-season fishing event, after half the seasonal natural mortality. Excess removal is the positive part of N * (U_raw - 1); the guard adjustment is N * (U_raw - U_used). These are bookkeeping discrepancies, NOT realised catch shortfalls: no allocation of a shortfall among fisheries or handling deaths is assumed. Annual sums across seasons count removal events, not unique animals.

catch_checks compares predicted retained catch with supplied prescribed catch, by year/season/region/fishery. Independently, the removal-balance check compares predicted retained catch plus handling deaths with raw combined removals, cell by cell. For match_old_u = 1, predictions are converted from their legacy pre-natural-mortality basis to the mid-season basis first. Thus exact catch matching does not hide a guarded population update.

Non-finite or negative population inputs are counted explicitly; affected annual magnitude totals are NA, never silently summed as zero. Unsupported catch modes return applicable = FALSE with NA diagnostics. Older reports lacking the required metadata must be regenerated, not treated as unflagged.