Setup survey selectivity and catchability specifications

Usage

Setup_Mod_Srvsel_and_Q(
  input_list,
  cont_tv_srv_sel,
  srv_sel_blocks,
  srv_sel_model,
  Use_srv_q_prior = 0,
  srv_q_prior = NA,
  srv_q_blocks,
  srvsel_pe_pars_spec = NULL,
  srv_fixed_sel_pars_spec,
  srv_q_spec = NULL,
  srv_sel_devs_spec = NULL,
  corr_opt_semipar = NULL,
  ...
)

Arguments

input_list

List containing a data list, parameter list, and map list

cont_tv_srv_sel

Character vector specifying the form of continuous time-varying selectivity for each survey fleet. The vector must be length n_srv_fleets, and each element must follow the structure: "<time variation type>_Fleet_<fleet number>".

Valid time variation types include:

"none": No continuous time variation.
"iid": Independent and identically distributed deviations across years.
"rw": Random walk in time.
"3dmarg": 3D marginal time-varying selectivity.
"3dcond": 3D conditional time-varying selectivity.
"2dar1": Two-dimensional AR1 process.

For example:

"iid_Fleet_1" applies an iid time-varying structure to Fleet 1.
"none_Fleet_2" means no time variation is used for Fleet 2.

Note: If time-block-based selectivity (via srv_sel_blocks) is specified for a fleet, then its corresponding entry here must be "none_Fleet_<fleet number>".

srv_sel_blocks

Character vector specifying the survey selectivity blocks for each region and fleet. Each element must follow the structure: `"Block_<block number>_Year_<start>-<end>_Fleet_<fleet number>"` or `"none_Fleet_<fleet number>"`. This allows users to define time-varying selectivity blocks for specific fleets within a region.

For example:

"Block_1_Year_1-35_Fleet_1" defines selectivity block 1 for Fleet 1 covering years 1 through 35.
"Block_2_Year_36-56_Fleet_1" defines block 2 for Fleet 1 for years 36 to 56.
"Block_3_Year_57-terminal_Fleet_1" assigns block 3 from year 57 through the terminal year for Fleet 1.
"none_Fleet_2" indicates that no survey selectivity blocks are used for Fleet 2.

The blocks must be non-overlapping and sequential in time within each fleet, and block numbers must be unique within each fleet.

srv_sel_model

Character vector specifying the survey selectivity model for each fleet. The vector must be length n_srv_fleets, and each element must follow the structure: "<selectivity model>_Fleet_<fleet number>".

Available selectivity model types include:

"logist1": Logistic function with parameters a50 and k.
"logist2": Logistic function with parameters a50 and a95.
"gamma": Dome-shaped gamma function with parameters amax and delta.
"exponential": Exponential function with a power parameter.
"dbnrml": Double normal function with 6 parameters.

For example:

"logist1_Fleet_1" uses the logistic (a50, k) model for Fleet 1.
"gamma_Fleet_2" uses the gamma dome-shaped model for Fleet 2.

The models are applied by region and year as defined in the overall model array structure (n_regions x n_years x n_srv_fleets), though this vector defines only the functional form for each fleet.

For mathematical definitions and implementation details of each selectivity form, refer to the model equations vignette.

Use_srv_q_prior

Integer specifying whether to use survey q prior or not (0 dont use) (1 use)

srv_q_prior

Survey q priors in normal space, dimensioned by region, block, survey fleet, and 2 (mean, and sd in the 4 dimension of array)

srv_q_blocks

Character vector specifying survey catchability (q) blocks for each fleet. Each element must follow the structure: "Block_<block number>_Year_<start>-<end>_Fleet_<fleet number>" or "none_Fleet_<fleet number>".

This allows users to define time-varying catchability blocks independently of selectivity blocks. The blocks must be non-overlapping and sequential in time within each fleet.

For example:

"Block_1_Year_1-35_Fleet_1" assigns block 1 to Fleet 1 for years 1–35.
"Block_2_Year_36-56_Fleet_1" continues with block 2 for years 36–56.
"Block_3_Year_57-terminal_Fleet_1" assigns block 3 from year 57 to the terminal year for Fleet 1.
"none_Fleet_2" indicates no catchability blocks are used for Fleet 2.

Internally, these specifications are converted to a [n_regions, n_years, n_srv_fleets] array, where each block is mapped to the appropriate years and fleets.

srvsel_pe_pars_spec

Character string specifying how process error parameters for survey selectivity are estimated across regions and sexes. This is only relevant if cont_tv_srv_sel is not set to "none"; otherwise, all process error parameters are treated as fixed.

Available options include:

"est_all": Estimates separate process error parameters for each region and sex.
"est_shared_r": Shares process error parameters across regions (sex-specific parameters are still estimated).
"est_shared_s": Shares process error parameters across sexes (region-specific parameters are still estimated).
"est_shared_r_s": Shares process error parameters across both regions and sexes, estimating a single set of parameters.
"fix" or "none": Does not estimate process error parameters; all are treated as fixed.

srv_fixed_sel_pars_spec

Character string specifying the structure for estimating fixed-effect parameters of the survey selectivity model (e.g., a50, k, amax). This controls whether selectivity parameters are estimated separately or shared across regions and sexes.

Available options include:

"est_all": Estimates separate fixed-effect selectivity parameters for each region and sex.
"est_shared_r": Shares parameters across regions (sex-specific parameters are still estimated).
"est_shared_s": Shares parameters across sexes (region-specific parameters are still estimated).
"est_shared_r_s": Shares parameters across both regions and sexes, estimating a single set of fixed-effect parameters.

srv_q_spec

Character string specifying the structure of survey catchability (q) estimation across regions. This controls whether separate or shared parameters are used.

Available options include:

"est_all": Estimates separate catchability parameters for each region.
"est_shared_r": Estimates a single catchability parameter shared across all regions.

srv_sel_devs_spec

Character string specifying the structure of process error deviations in time-varying survey selectivity dimensioned by the number of survey fleets. This determines how deviations are estimated across regions and sexes.

Available options include:

"est_all": Estimates a separate deviation time series for each region and sex.
"est_shared_r": Shares deviations across regions (sex-specific deviations are still estimated).
"est_shared_s": Shares deviations across sexes (region-specific deviations are still estimated).
"est_shared_r_s": Shares deviations across both regions and sexes, estimating a single deviation time series.

This argument is only used when a continuous time-varying selectivity form is specified (e.g., via cont_tv_srv_sel).

corr_opt_semipar

Character string specifying which correlation structures to suppress when using semi-parametric time-varying selectivity models. Only used if cont_tv_sel is set to one of "3dmarg", "3dcond", or "2dar1".

This option allows users to turn off estimation of specific correlation components in the time-varying selectivity model. This can improve stability or enforce assumptions about independence in the temporal or age structure.

Available options:

"corr_zero_y": Sets year (temporal) correlations to 0.
"corr_zero_a": Sets age correlations to 0.
"corr_zero_y_a": Sets both year and age correlations to 0.
"corr_zero_c": Sets cohort correlations to 0. Only valid for cont_tv_sel = "3dmarg" or "3dcond".
"corr_zero_y_c": Sets year and cohort correlations to 0. Only valid for cont_tv_sel = "3dmarg" or "3dcond".
"corr_zero_a_c": Sets age and cohort correlations to 0. Only valid for cont_tv_sel = "3dmarg" or "3dcond".
"corr_zero_y_a_c": Sets all correlations (year, age, and cohort) to 0. Only valid for cont_tv_sel = "3dmarg" or "3dcond"; equivalent to an iid structure.

These correlation-suppression flags are ignored when cont_tv_sel is set to any other value.

...

Additional arguments specifying starting values for survey selectivity and catchability parameters (srvsel_pe_pars, ln_srvsel_devs, ln_srv_fixed_sel_pars, ln_srv_q)