7. Converting from Stock Synthesis

This vignette converts a Stock Synthesis (SS3) model into the Rceattle data structure, following the SS files top-to-bottom and copying each block into the corresponding Rceattle sheet. Rceattle column and sheet names are in code font.

The examples reference the 2019 Pacific hake assessment, in Nis Sand Jacobsen’s PacifichakeMSE repo. Apart from consumption and diet, which SS does not estimate, every input Rceattle needs is somewhere in the SS data, weight-at-age, or control file.

Updated for the Rceattle 4.0+ data structure. Several data_list columns and sheet names changed in 4.0.1 (Pyrs → ration_data, UobsWtAge → diet_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_bin / Sel_norm_bin_upper); the names used below are current. The meta_data sheet in the Rceattle Excel template is the authoritative column reference.

Model controls

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

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`	Number of age bins, not the oldest age: ages run `minage .. minage + nages - 1`, so the two coincide only at `minage = 1`
`_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 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)

meta_data documents every remaining fleet_control column: selectivity, catchability, composition likelihood and the rest.

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`	Convert to mt; Rceattle works in mt and thousands of fish throughout (see `?plot_timeseries`)
`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:

SS / behavior	Rceattle (`fleet_control`)	Notes
Units (numbers / biomass)	`Observation_units`	`1` = biomass, `2` = numbers
(estimate index SD?)	`Estimate_index_sd`	`0` = supplied, `1` = estimated, `2` = analytical (concentrated out of the likelihood)
Q estimation	`Catchability`, `Catchability_init`, `Catchability_prior_sd`	See vignette 0 §4 for the option table
Time-varying q	`Time_varying_q`, `Time_varying_q_sd`

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; treat them as a separate fishery fleet with its own selectivity.

Composition data

SS _lencomp and _agecomp blocks → Rceattle comp_data sheet, one table for both, with Age0_Length1 telling them apart.

Comp options, on fleet_control unless the row says otherwise:

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_distribution`	`0` = multinomial, `1` = Dirichlet-multinomial. (`-1` = legacy AFSC convention.)
Selectivity bin range	`Sel_norm_bin`, `Sel_norm_bin_upper`, `Bin_first_selected`	First selected bin and the bin(s) at which selectivity is normalized to 1

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

Where the SS comp data covers fewer ages than nages (comps to age 15 in a 20-age model, say), Sel_norm_bin / Sel_norm_bin_upper and N_sel_bins control how the missing ages are accumulated. Whether to zero-pad or accumulate at the upper age is a question for the assessment document or its authors, not an inference.

For a two-sex conversion, Sel_norm_scope decides whether the normalization reference is pooled over the sexes ("AcrossSexes", the default, which keeps relative sex-specific selectivity) or taken per sex ("WithinSex"). Rceattle’s equivalent of the SS male apical-selectivity offset is the apical selectivity linkage parameter, added in 5.38.0: name the fleet and the sex that holds it, as the SS male-offset option does. The ratio is informed only by joint (comp_data$Sex = 3) composition data, so it is identified only over the years that hold it; without such a linkage, relative sex selectivity rests on the normalization scope alone.

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’s are time- and sex-invariant: one per species on the age_error sheet, or several selected per fleet through Ageing_error_index. Hake’s are already time-invariant, so no aggregation is needed; convert per the SS manual and copy the result in.

Weight-at-age

SS weight-at-age (wtatage.ss) → Rceattle weight sheet:

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; those estimates are conditional on the SS population dynamics, so they are mildly circular when ported to Rceattle.

Other inputs

sex_ratio sheet, 0.5 at all ages by the usual hake 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 to length for length-composition data. Set every entry to 0 if the assessment has no length data; otherwise fill from the SS age-length transition.
ration_data and diet_data, the diet and consumption inputs, for multi-species models only. SS does not provide these; derive them externally.

Verifying the conversion against SS

The standard check feeds Rceattle the SS-estimated selectivity and numbers-at-age and confirms the 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, which fixes N-at-age to NByageFixed.
Run fit_mod(estimateMode = "DebugBuild", ...), which builds the objective and stops. Mode 1 ("Hindcast") would re-estimate the hindcast and discard the parameters you have just injected.

A remaining difference traces back to a coercion bug in the data port, to a mortality convention (Rceattle’s Baranov is annual, SS allows seasonal), or to a likelihood difference: Rceattle fits comps as multinomial or Dirichlet-multinomial, not in the SS lognormal-on-comp forms.