7. Converting from Stock Synthesis

This vignette is a working guide for converting a Stock Synthesis (SS3) model into the Rceattle data structure. It is written from the perspective of reading the SS files top-to-bottom and copying each block into the corresponding Rceattle data sheet. Rceattle column / sheet names are shown in code font.

The example below references the 2019 Pacific hake assessment, which is publicly available on Nis Sand Jacobsen’s PacifichakeMSE GitHub repo. With the exception of consumption / diet (which SS does not estimate), every input Rceattle needs is somewhere in the SS data, weight-at-age, or control file.

Updated for Rceattle 4.0+ data structure. Several data_list columns and sheet names changed in 4.0.1 (Pyrs → ration_data, UobsWtAge → stom_prop_data, fsh_biom → catch_data, srv_biom → index_data, Nselages → N_sel_bins, Age_first_selected → Bin_first_selected, Age_max_selected / _upper → Sel_norm_bin1 / Sel_norm_bin2). The instructions below use the current names. The sheet meta_data inside the Rceattle Excel template is the authoritative column reference.

Model controls

From the SS data file (hake_data.ss) into the Rceattle Excel sheet control:

SS field	Rceattle (`control` sheet)	Notes
`styr` (1966)	`styr`	First year of hindcast
`endyr` (2019)	`endyr`	Last year of hindcast
`Nsexes` (1)	`nsex`	1 = combined-sex; 2 = sex-structured
`Nages` (20)	`nages`	Maximum age class
`_spawn_month`	`spawn_month`	Calendar month of spawning
—	`minage`	Set to 1; age 0 is currently first-age only
—	`projyr`	Pick a projection terminal year

Fleets

From #fleetinfo in the SS data file into the Rceattle fleet_control sheet — one row per fleet:

SS field	Rceattle (`fleet_control`)	Notes
`fleetname`	`Fleet_name`
(assign)	`Fleet_code`	Unique integer; must be in order
`fleet_type`	`Fleet_type`	`1` = fishery, `2` = survey, `0` = ignore
(associate)	`Species`	Species the fleet observes
(per-fleet)	`Month`	Month of observation (added in 4.0.1)

The meta_data sheet in the Rceattle Excel template documents every remaining column on fleet_control (selectivity, catchability, composition likelihood, etc.).

Catch data

SS catch data → Rceattle catch_data sheet:

SS field	Rceattle (`catch_data`)	Notes
`year`	`Year`
`seas`	`Month`	Currently informational; Baranov is annual
`fleet`	`Fleet_code`	Re-map if the codes differ from SS
`catch`	`Catch`	Units flexible (typically 1000 mt)
`catch_se`	`Log_sd`	Lognormal F-dev SD

Survey indices

The CPUE / survey configuration is split across two Rceattle sheets:

fleet_control for the fleet-level options (units, SD estimation, catchability formulation):

SS / behaviour	Rceattle (`fleet_control`)	Notes
Units (numbers / biomass)	`Weight1_Numbers2`	`1` = biomass, `2` = numbers
(estimate index SD?)	`Estimate_index_sd`	`0` = supplied, `1` = estimated
Q estimation	`Catchability`, `Q_prior`, `Q_sd_prior`	See vignette 0 §4 for the option table
Time-varying q	`Time_varying_q`, `Time_varying_q_sd_prior`

index_data for the year-level observations:

SS field	Rceattle (`index_data`)	Notes
`index`	`Fleet_code`
`year`	`Year`	Make `Year` negative to predict but exclude from likelihood (parallel to SS’s negative `index` convention)
`seas`	`Month`	Adjusts biomass / numbers by mortality up to that month
`OBS`	`Observation`
`se_log`	`Log_sd`	Lognormal observation SD

Discards are not a first-class concept in Rceattle 4.x; treat them as a separate fishery fleet with its own selectivity if needed.

Composition data

SS _lencomp and _agecomp blocks → Rceattle comp_data sheet (one table for both age and length comps; the Age0_Length1 column distinguishes them).

fleet_control:

SS field	Rceattle (`fleet_control`)	Notes
`_N_lbins` (26)	`nlengths` (on `control` sheet)	Number of length bins
Sex aggregation	`Sex` column on `comp_data`	Hake is single-sex
Comp likelihood	`Comp_loglike`	`0` = multinomial, `1` = Dirichlet-multinomial. (`-1` = legacy AFSC convention.)
Selectivity bin range	`Sel_norm_bin1`, `Sel_norm_bin2`, `Bin_first_selected`	Replaces the old `Age_max_selected` / `Age_first_selected` columns

comp_data:

SS field	Rceattle (`comp_data`)	Notes
`FltSvy`	`Fleet_code`
`year`	`Year`
`seas`	`Month`
`gender`	`Sex`	See `meta_data` for sex codings
`Nsamp`	`Sample_size`
`a1, a2, …`	`Comp_1, Comp_2, …`	One column per age (or length) bin
—	`Age0_Length1`	`0` = age comp, `1` = length comp

If the SS comp data covers fewer ages than nages (e.g. comps to age 15 in a 20-age model), set Sel_norm_bin1 / Sel_norm_bin2 and N_sel_bins to control how the missing ages are accumulated. Check the assessment document or contact the authors before deciding whether to zero-pad or accumulate at the upper age.

Part, Ageerr, Lbin_lo, Lbin_hi, CompressBins, CompError, ParmSelect, and minsamplesize from SS do not have direct Rceattle equivalents.

Ageing error

SS allows year- and sex-varying age-error matrices. Rceattle currently supports one species-specific, time- and sex-invariant matrix per species, on the age_error sheet. For hake the matrices are time- invariant, so no aggregation is needed; convert per the SS manual and copy the result into age_error.

Weight-at-age

SS weight-at-age (wtatage.ss) → Rceattle weight sheet (note: the in-package list slot is wt).

For each weight-at-age matrix in SS, generate a Wt_name and Wt_index for Rceattle.
year → Year; gender → Sex (see meta_data); SS columns a1, a2, … → Age1, Age2, ….
On fleet_control, point Weight_index for each fleet at the appropriate Wt_index.
On control, point pop_wt_index and ssb_wt_index for each species at the appropriate Wt_index.

SSB hack for SS weight-at-age: SSB is computed as Σ_a(N · weight · maturity). If the SS wtatage.ss already bakes maturity into a weight-at-age schedule, point ssb_wt_index at that schedule and set every entry of the maturity sheet to 1.

If SS estimates weight-at-age (rather than reading it from data), copy from wtatage_new.ss instead — bearing in mind the estimates are conditional on the SS population dynamics and are therefore mildly circular when ported to Rceattle.

Other inputs

sex_ratio sheet — typically 0.5 for all ages. Hake assessments use this convention.
M1_base sheet — values from the assessment document. To estimate M rather than fix it, configure M1Fun = build_M1(M1_model = …) on fit_mod(). See vignette 0 §7 for the option table.
age_trans_matrix sheet — converts age-at-length to length-at-age. Set every entry to 0 if the assessment has no length data; for models with length comps, fill from the SS age-length transition.
ration_data and stom_prop_data (multi-species only) — diet / consumption inputs. SS does not provide these; derive externally if fitting a multi-species CEATTLE.

Verifying the conversion against SS

The most common check is to feed Rceattle the SS-estimated selectivity and numbers-at-age and confirm the resulting catches and indices match SS:

Run the SS model (or use the SS report file).
Copy SS selectivity per fleet to the emp_sel sheet.
Copy SS numbers-at-age to the NByageFixed sheet.
Set Selectivity = 0 (“Fixed”) for each fleet on fleet_control and estDynamics = 1 for each species on control (this fixes N-at-age to NByageFixed).
Run fit_mod(estimateMode = 1, ...) to evaluate without re-fitting.

Differences between Rceattle and SS at this stage trace back to either (a) a coercion bug in the data port, (b) a different mortality convention (Rceattle’s Baranov is annual, SS allows seasonal), or (c) a likelihood difference (Rceattle currently supports multinomial and Dirichlet-multinomial for comps; not the SS lognormal-on-comp forms).