Setup fishery selectivity and catchability specifications

Usage

Setup_Mod_Fishsel_and_Q(
  input_list,
  cont_tv_fish_sel,
  fish_sel_blocks,
  fish_sel_model,
  Use_fish_q_prior = 0,
  fish_q_prior = NA,
  fish_q_blocks,
  fishsel_pe_pars_spec = NULL,
  fish_fixed_sel_pars_spec = NULL,
  fish_q_spec = NULL,
  fish_sel_devs_spec = NULL,
  corr_opt_semipar = NULL,
  Use_fish_selex_prior = 0,
  fish_selex_prior = NULL,
  ...
)

Arguments

input_list

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

cont_tv_fish_sel

Character vector specifying the form of continuous time-varying selectivity for each fishery fleet. The vector must be length n_fish_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 fish_sel_blocks) is specified for a fleet, then its corresponding entry here must be "none_Fleet_<fleet number>".

fish_sel_blocks

Character vector specifying the fishery 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 fishery 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.

fish_sel_model

Character vector specifying the fishery selectivity model for each fleet. The vector must be length n_fish_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_fish_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_fish_q_prior

Integer (0 or 1). Flag to enable/disable survey catchability priors. When set to 1, applies log-normal priors to survey selectivity parameters as specified in fish_q_prior. When set to 0, no priors are applied.

fish_q_prior

Data frame containing prior specifications for survey catchability parameters. Must include columns: region (region index), fleet (fleet index), block (time block index), mu (prior mean on natural scale), and sd (prior standard deviation on log scale). Each row specifies a log-normal prior N(log(mu), sd) for a given catchability parameter. Only parameters with rows in this data frame will have priors applied.

fish_q_blocks

Character vector specifying fishery 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_fish_fleets] array, where each block is mapped to the appropriate years and fleets.

fishsel_pe_pars_spec

Character string specifying how process error parameters for fishery selectivity are estimated across regions and sexes. This is only relevant if cont_tv_fish_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.
"est_shared_f_x": Shares process error parameters with another fleet, where x is the fleet number to share with. This option forces multiple fleets to have identical process error variance and correlation structures for their time-varying selectivity. For example, "est_shared_f_2" means the current fleet will use the same process error parameters as fleet 2. The reference fleet (fleet x) must use one of the other sharing options and cannot itself be sharing with another fleet.
"fix" or "none": Does not estimate process error parameters; all are treated as fixed.

fish_fixed_sel_pars_spec

Character string specifying the structure for estimating fixed-effect parameters of the fishery 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.
"est_shared_f_x": Shares fixed-effect selectivity parameters with another fleet, where x is the fleet number to share with. This option forces multiple fleets to have identical selectivity curves by using the same underlying parameters (e.g., same a50, k, amax values). For example, "est_shared_f_2" means the current fleet will use the same fixed-effect selectivity parameters as fleet 2. The reference fleet (fleet x) must use one of the other sharing options and cannot itself be sharing with another fleet.
"fix": Fixes all selectivity parameters to their initial values (no estimation).
"none": No selectivity parameters are estimated (equivalent to "fix").

fish_q_spec

Character string specifying the structure of fishery 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.

fish_sel_devs_spec

Character string specifying the structure of process error deviations in time-varying fishery selectivity dimensioned by the number of fishery 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.
"est_shared_f_x": Shares deviations with another fleet, where x is the fleet number to share with. This option allows multiple fleets to use identical deviation parameters, reducing the number of parameters to estimate. For example, "est_shared_f_2" means the current fleet will use the same deviation parameters as fleet 2. The reference fleet (fleet x) must use one of the other sharing options ("est_all", "est_shared_r", "est_shared_s", or "est_shared_r_s") and cannot itself be sharing with another fleet.
"fix": Fixes all deviation parameters to zero (no time-variation).
"none": No deviation parameters are estimated (equivalent to "fix").

This argument is only used when a continuous time-varying selectivity form is specified (e.g., via cont_tv_fish_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.

Use_fish_selex_prior

Integer (0 or 1). Flag to enable/disable fishery selectivity priors. When set to 1, applies log-normal priors to fishery selectivity parameters as specified in fish_selex_prior. When set to 0, no priors are applied.

fish_selex_prior

Data frame containing prior specifications for fishery selectivity parameters. Must include columns: region (region index), fleet (fleet index), block (time block index), sex (sex index), par (parameter index), mu (prior mean on natural scale), and sd (prior standard deviation on log scale). Each row specifies a log-normal prior N(log(mu), sd) for one selectivity parameter. Only parameters with rows in this data frame will have priors applied.

...

Additional arguments specifying starting values for fishery selectivity and catchability parameters (fishsel_pe_pars, ln_fishsel_devs, ln_fish_fixed_sel_pars, ln_fish_q)