A list of functions available in the SpatialSablefishAssessment package

All of these functions have descriptions and details on expected input parameters using the standard ? R query methods. You can also use help(package = "SpatialSablefishAssessment") to get a list of functions available in this package.

Most of the functions will ask for an optional input parameter called region_key which will add a label for regions. This is a data.frame which is shown in the following code chunk. Note how the column TMB_ndx is an index made for C++ syntax not R i.e., it starts at 0 not 1.

region_key = data.frame(area = c("BS","AI","WGOA","CGOA","EGOA"), TMB_ndx = c(0:4))
region_key
##   area TMB_ndx
## 1   BS       0
## 2   AI       1
## 3 WGOA       2
## 4 CGOA       3
## 5 EGOA       4

Validate functions

  • validate_input_data_and_parameters This should always be run on data and parameters applying TMB::MakeADFun. It should catch any issues that will likely cause your R session to crash.

Accessor functions

  • get_AF get age-frequency observed and predicted values from a model
  • get_LF get length-frequency observed and predicted values from a model
  • get_catches get observed and predicted catches from a fitted model
  • get_fishing_mortalities get annual fishing mortalities from a model
  • get_index get survey index from a model
  • get_partition get numbers at age (units 1 = 1e6) from a fitted model
  • get_SSB get SSBS (kilo tonnes) from a fitted model
  • get_tag_recovery_obs_fitted_values
  • get_tag_release_AF get age-frequency of tag-releases
  • get_negloglike get negative log likelihoods for each contribution
  • get_comp_sample_size get composition sample size
  • simulate_observations this function will take a TMB object and simulate a number of observations, used to create simulated residuals.
  • calculate_simulated_residuals this function will take an element from an object created from simulate_observations. This will use DHARMa’s createDHARMa function to calculated simulated residuals

Plotting functions

  • plot_AF plot age frequency observation
  • plot_age_length_matrix plot input age-length transition matrices
  • plot_catch_fit plot the fit to catches
  • plot_fishing_mortalities plot fishing mortalities
  • plot_frequency_of_tag_release_and_recoveries
  • plot_index_fit plot survey index
  • plot_init_nage plot initial numbers at age
  • plot_input_catches plot input catches
  • plot_input_observations plot input observations
  • plot_input_timeblocks plot selectivity and catchability time-blocks in a model
  • plot_comp_sample_size plot composition sample size
  • plot_LF plot length frequency observation
  • plot_mean_age plot mean age observations
  • plot_mean_length plot mean length observations
  • plot_mean_weight plot mean weight over time for males and females
  • plot_movement plot movement matrix from a model
  • plot_partition plot numbers at age by year and sex
  • plot_recruitment plot annual recruitment by region
  • plot_selectivities plot selectivity curves
  • plot_SSB plot regional SSBs
  • plot_tag_recovery_obs plot tag-recovery obs
  • plot_tag_recovery_fits an alternative plotting function for tag-recovery obs
  • plot_tag_release_AF plot the numbers at age by sex for each release event

Estimation functions

  • estimate_with_phases Estimate a model where parameters are estimated with phases
  • profile_param Run log-likelihood profiles on an estimated parameter
  • set_up_parameters Fix parameters, uses fix_pars and set_pars_to_be_the_same for the TagIntegrated model
  • pre_optim_sanity_checks run some checks on a TMB model of type TagIntegrated before optimization
  • post_optim_sanity_checks run some checks on a TMB model of type TagIntegrated after optimization
  • check_gradients check all parameter gradients are not zero
  • Francis_reweighting calculate stage-two weights for composition data
  • get_tmb_fixed_effects return fixed effect parameters from a model
  • fix_pars turn off parameters so they aren’t estimated, there are many parameters that shouldn’t be estimated
  • set_pars_to_be_the_same set parameters to be estimated at the same value i.e., male female have the same selectivity parameters. or tag-reporting to be the same among regions.
  • rmvnorm_prec simulate from a multivariate normal distribution using the precision matrix.

Projection/Reference point functions

  • setup_proj_data this function will take an estimation model and create a data list that when built with TMB::MakeADFun creates a model that will projections for a user defined number of projection years.

  • find_regional_Fspr this will attempt to find an F for each region and fishery assuming future deterministic (mean) recruitment that achieves some specified target percent \(B_{0}\) in each region.

Model comparison functions

Often you will run multiple models to explore alternative assumptions and hypothesis. There are a range of function available for extracting output convenient for plotting and summarizing. In order to use the following functions you need to create a list containing multiple runs e.g.

multi_runs <- list()
multi_runs[[1]] <- low_M_model$report()
multi_runs[[2]] <- high_M_model$report()
run_labels = c("M = 0.08", "M = 0.2")

ssb_df = get_multiple_ssbs(mle_ls = multi_runs, run_labels = run_labels)
  • get_multiple_ssbs get multiple models SSBs
  • get_multiple_catch_fits Get multiple models catch fits
  • get_multiple_nlls get multiple models negative log-likelihood
  • summarise_individual_models this is a function that will build a Bookdown/Rmarkdown book displaying a full summary of each model individually. This functions expect users to save the following objects with these exact names for each model that you want to compare. Then pass the function all the directories with model labels and descriptions. Then it “should” automatically build you a Rmarkdown document.
saveRDS(data, file.path(fig_path, "data.RDS"))
saveRDS(parameters, file.path(fig_path, "parameters.RDS"))
saveRDS(mle_report, file.path(fig_path, "mle_report.RDS"))
saveRDS(sd_report, file.path(fig_path, "sd_report.RDS"))
saveRDS(mle_spatial, file.path(fig_path, "mle_optim.RDS"))
saveRDS(map_fixed_pars, file.path(fig_path, "map_fixed_pars.RDS"))
saveRDS(region_key, file.path(fig_path, "region_key.RDS"))
  • summarise_multiple_models this is a function that will build a Bookdown/Rmarkdown book compareing multiple models fits and quantities on the same plot. This functions expect users to save the following objects with these exact names for each model that you want to compare. Then pass the function all the directories with model labels and descriptions. Then it “should” automatically build you a Rmarkdown document.
saveRDS(data, file.path(fig_path, "data.RDS"))
saveRDS(parameters, file.path(fig_path, "parameters.RDS"))
saveRDS(mle_report, file.path(fig_path, "mle_report.RDS"))
saveRDS(sd_report, file.path(fig_path, "sd_report.RDS"))
saveRDS(mle_spatial, file.path(fig_path, "mle_optim.RDS"))
saveRDS(map_fixed_pars, file.path(fig_path, "map_fixed_pars.RDS"))
saveRDS(region_key, file.path(fig_path, "region_key.RDS"))

Distribution functions

  • ddirichmult Dirichlet-multinomial pdf function
  • dmultinom_upd Multinomial pdf function, which is the same as TMB’s. Differs from Rs base dmultinom by allowing non-integer x values and not rounding the x values.
  • lognormal_CI calculate confidence intervals for the lognormal distribution
  • log_cv calculate cv for the lognormal distribution given standard deviation
  • log_sigma calculate standard deviation for the lognormal distribution given CV

Parameter transformation functions

  • restoresimplex go from simplex to unit vector
  • simplex go from unit vector to simplex
  • logit_general logistic transformation between a specified lower and upper bound
  • logit logistic transformation between 0, 1 similar to qlogis
  • invlogit_general inverse logistic transformation between a specified lower and upper bound
  • invlogit inverse logistic transformation between 0, 1 similar to plogis
  • bound_unit transform a parameter \(X\) bound between -1 and 1 (i.e., correlation parameter) to value \(Y\) which is unbounded as \[ Y = \begin{cases} \sqrt{\frac{X^2}{1 - X^2}}, \ \ & X \geq 0 \\ -\sqrt{\frac{X^2}{1 - X^2}} , \ \ & X < 0 \end{cases} \]
  • inv_bound_unit inverse of bound_unit
  • gm_mean calculate the geometric mean
  • sum_to_zero_QR take an unconstrained vector of length N - 1 and calculate a vector of length N that sums = 1.

Data grooming functions

These aren’t related to the model per se. These are useful when grooming raw data sets that are ultimately used as inputs into the model.

  • record_grooming_rule this will create a table of how much catch and how many records are removed from applying some data grooming rules
  • apply_grooming_rule equivalent to the subset function

Auxillary functions

  • VAlignPlots a plotting function that joins multiple ggplots into a single panel with aligned legends and extents