From 6d806c875bcf00eed2591911ab527a8edadbe643 Mon Sep 17 00:00:00 2001 From: Joshua Zahner Date: Mon, 20 May 2024 22:58:00 -0700 Subject: [PATCH] docs: pkgdown site articles --- R/recruitment.R | 84 ++++++ docs/404.html | 17 +- docs/LICENSE-text.html | 17 +- docs/LICENSE.html | 17 +- docs/articles/afscOM.html | 249 ++++++++++++++++++ docs/articles/index.html | 29 +- docs/articles/model_dimensions.html | 146 ++++++++++ docs/articles/model_options.html | 205 ++++++++++++++ docs/articles/multiyear_projections.html | 141 ++++++++++ docs/articles/observation_processes.html | 126 +++++++++ .../specifying_demographic_parameters.html | 209 +++++++++++++++ docs/authors.html | 17 +- docs/index.html | 17 +- docs/pkgdown.yml | 9 +- docs/reference/F_to_mu.html | 17 +- docs/reference/Rplot001.png | Bin 0 -> 1011 bytes docs/reference/assessment.html | 17 +- docs/reference/baranov.html | 36 ++- docs/reference/catch_at_age.html | 17 +- docs/reference/discard_F.html | 17 +- docs/reference/extend_years.html | 17 +- docs/reference/findF_bisection.html | 26 +- docs/reference/find_F.html | 26 +- docs/reference/generate_param_matrix.html | 17 +- docs/reference/get_model_dimensions.html | 17 +- docs/reference/index.html | 17 +- docs/reference/listN.html | 17 +- docs/reference/mu_to_F.html | 17 +- docs/reference/project.html | 17 +- docs/reference/retained_F.html | 17 +- docs/reference/set_model_params.html | 17 +- docs/reference/simulate_ac.html | 17 +- docs/reference/simulate_caa.html | 17 +- docs/reference/simulate_catch.html | 17 +- docs/reference/simulate_lognormal_obs.html | 26 +- docs/reference/simulate_multinomial_obs.html | 26 +- docs/reference/simulate_observations.html | 17 +- docs/reference/simulate_population.html | 24 +- docs/reference/simulate_rpn.html | 17 +- docs/reference/simulate_rpw.html | 17 +- docs/reference/subset_dem_params.html | 17 +- docs/reference/subset_matrix.html | 17 +- docs/sitemap.xml | 18 ++ vignettes/{intro.Rmd => afscOM.Rmd} | 4 +- vignettes/model_dimensions.Rmd | 26 ++ vignettes/model_options.Rmd | 84 ++++++ vignettes/multiyear_projections.Rmd | 31 +++ .../specifying_demographic_parameters.Rmd | 98 +++++++ 48 files changed, 1999 insertions(+), 66 deletions(-) create mode 100644 R/recruitment.R create mode 100644 docs/articles/afscOM.html create mode 100644 docs/articles/model_dimensions.html create mode 100644 docs/articles/model_options.html create mode 100644 docs/articles/multiyear_projections.html create mode 100644 docs/articles/observation_processes.html create mode 100644 docs/articles/specifying_demographic_parameters.html create mode 100644 docs/reference/Rplot001.png rename vignettes/{intro.Rmd => afscOM.Rmd} (99%) create mode 100644 vignettes/model_dimensions.Rmd create mode 100644 vignettes/model_options.Rmd create mode 100644 vignettes/multiyear_projections.Rmd create mode 100644 vignettes/specifying_demographic_parameters.Rmd diff --git a/R/recruitment.R b/R/recruitment.R new file mode 100644 index 0000000..8fe94b1 --- /dev/null +++ b/R/recruitment.R @@ -0,0 +1,84 @@ +#' Resample from historical recruitment timeseries +#' +#' Draw `n` random samples, with replacement, from the +#' historical recruitment timeseries. +#' +#' @param n number of samples to draw +#' @param hist.rec historical recruitment vector +#' @param seed a random seed (optional) +#' +#' @return `n` random samples from the historical +#' recruitment timeseries. +#' +#' @export resample_recruitment +#' +#' @example +#' set.seed(1120) +#' n <- 100 +#' hist.rec <- c(100, 200, 50, 100, 120) +#' resample.recruitment(n, hist.rec) +#' +resample_recruitment <- function(n, hist_rec, seed=NA){ + if(!is.na(seed)){ + set.seed(seed) + } + return(sample(hist_rec, n, replace=TRUE)) +} + +mean_recruitment <- function(n, log.mu, sd, seed=NA){ + if(!is.na(seed)){ + set.seed(seed) + } + return(exp(log.mu + rnorm(n, 0, sd) - sd^2/2)) +} + +#' Generate log-recruitment from two defined regimes of a specified length +#' +#' Description +#' +#' @param n number of recruitment events +#' @param mu.rec vector of mean log-recruitment levels, one for each regime +#' @param sd.rec vector of recruitment variation, one for each regime +#' @param dur duration of regimes +#' @param start which regime to start in +#' @param seed a random seed (optional) +#' +#' @return `n` log-recruitment levels from two different regimes of +#' length `dur`. +#' @export cyclic.recruitment +#' +#' @example +cyclic.recruitment <- function(n, mu_rec, sd_rec, dur, start=1, seed=NA){ + + if(!is.na(seed)){ + set.seed(seed) + } + + curr_regime <- start + duration <- dur[curr_regime] + recs <- rep(NA, n) + for(i in 0:n){ + recs[i] <- exp(mu_rec[curr_regime+1] + rnorm(1, 0, sd_rec[curr_regime+1]) - (sd_rec[curr_regime+1]^2)/2) + if(i %% duration == 0){ + curr_regime <- as.numeric(!curr_regime) + duration <- dur[curr_regime+1] + } + } + return(recs) + +} + +beverton_holt <- function(h, R0, S0){ + function(ssb){ + return( + (4*R0*h*ssb)/((1-h)*R0*(S0/R0) + (5*h - 1)*ssb) + ) + } +} + +bh <- beverton_holt(0.7, 25, 300) + +bh +is.function(bh) + +bh <- 1 diff --git a/docs/404.html b/docs/404.html index 06c29c9..fba11aa 100644 --- a/docs/404.html +++ b/docs/404.html @@ -38,6 +38,9 @@ diff --git a/docs/articles/model_dimensions.html b/docs/articles/model_dimensions.html new file mode 100644 index 0000000..62fd4b2 --- /dev/null +++ b/docs/articles/model_dimensions.html @@ -0,0 +1,146 @@ + + + + + + + +Model Dimensions • afscOM + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Model Dimensions

+ + + + + +
+ + + +

The afscOM model is an age-structured, multi-sex, multi-fleet, spatially-explicit population dynamics model. The model has been designed to handle any number of age-classes, up to 2 sexes, any number of fishing fleets, and any number of spatial regions, so long as the model parameters are appropriately dimensioned. In order to parameterize an OM using this package, the following model dimensions should be defined:

+
    +
  1. +nyears: the number of years over which the user intends to run the model for
    2. +
  2. +nages: the number of age classes in the population
    3. +
  3. +nsexes: the number of sexes to model (1 = females only, 2 = females and males)
    4. +
  4. +nregions: the number of spatial regions in the model
    5. +
  5. +nfleets: the number of fishing fleets to simulate catch from
    6. +
+

The model is not sensitive to what true age corresponds to the initial age class, so there is no difference between starting a model at age-2 and starting a model at age-0, so long as recruitment is appropriately scaled.

+

If users wish to generate observations from scientific surveys, an additional model dimension must also be defined:

+
    +
  1. +nsurveys: the number of survey fleets to simulate observations from
    2. +
+

Throughout the documentation for this package, model dimensions will be routintely referred to in the following format: [nyears, nages, nsexes, nregions, nfleets].

+

NOTE: At present, the model has not been thoroughly tested with more than 1 spatial region.

+
+ + + +
+ + + +
+

+

Developed by Benjamin Williams, Joshua Zahner, Matt Cheng, Dan Goethel, Curry Cunningham.

+
+ +
+

+

Site built with pkgdown 2.0.7.

+
+ +
+
+ + + + + + + + diff --git a/docs/articles/model_options.html b/docs/articles/model_options.html new file mode 100644 index 0000000..5b037b1 --- /dev/null +++ b/docs/articles/model_options.html @@ -0,0 +1,205 @@ + + + + + + + +Model Options • afscOM + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Model Options

+ + + + + +
+ + + +

A vareity of model options also need to be specified to ensure the projection model works as expected. Required options are:

+
    +
  • +removals_input: input units of removals (either “catch” is inputs are a TAC, or “F” if an instantenous fishing mortality rate)
    • +
  • +simulate_observations: whethr to simulate observations from the OM (TRUE/FALSE)
    • +
+
+model_options <- list(
+  removals_input = "catch",
+  simulate_observations = TRUE
+)
+
+

Catch Apportionment +

+

If removals_input="catch", then region and fleet-level apportionment must also be specified:

+
    +

  • region_apportionment: an unnamed list of vectors (of length nyears) specifying what proportion of the TAC should be allocated to each spatial region. There should be as many vector as there are regions. The sum across all regions in a given year should be 1.0, but the model will not make this check internally.

    • +

  • fleet_apportionment: an unnamed list of vectors (of length nyears) specifying what proportion of the TAC should be allocated to each fishing fleet. There should be as many vectors as there are fishing fleets. For multi-region models, the fleet_apportionment proportions will be applied across all regions. There is not currently support for specifying unique fleet apportionments per spatial region.

    • +
+
+# For a single region model, 100% of the catch is apportioned to the single region
+model_options$regional_apportionment <- list(1)
+
+# Define a 70%-30% apportionment split between fleet 1 and fleet 2
+model_options$fleet_apportionment <- list(rep(0.70, nyears), rep(30, nyears))
+
+
+

Observation Processes +

+

If simulate_observations=TRUE, then a set of parameters that govern how observations are simulated must also be defined. This option, obs_pars takes the form of a complex list, where each named element of the list refers to a specific survey or fishery from which observations are being simulated. Currently, there is support for a longline survey (surv_ll), a trawl survy (surv_tw), a fixed gear fishery (fish_fx), and a trawl fishery (fish_tw).

+

Within each survey/fishery, specific parameter values that define the observation processes must be defined. The parameters supported for survey and fishery fleets differ somewhat.

+

For surveys, the following observation parameters must all be defined:

+
    +
  • +q: a catchability coefficient
    • +
  • +rpn_cv: coefficient of variation of RPN observations
    • +
  • +rpw_cv: coefficient of variation of RPW observations
    • +
  • +ac_samps: the number of samples, across all sexes, from which age composition data is simulated
    • +
  • +as_integers: whether to return age composition observations as integer or proportions
    • +
+

For fishery fleets, only the following observation parameters need to be defined:

+
    +
  • +ac_samps: the number of samples, across all sexes, from which age composition data is simulated
    • +
  • +as_integers: whether to return age composition observations as integer or proportions
    • +
+

For additional information on how all of these parameters are used to generate observations, see “Observation Processes”.

+
+obs_pars <- list(
+    surv_ll = list(
+        q = 6.41338,
+        rpn_cv = 0.20,
+        rpw_cv = 0.10,
+        ac_samps = 1000,
+        as_integers = TRUE
+    ),
+    surv_tw = list(
+        q = 0.8580,
+        rpw_cv = 0.10,
+        ac_samps = 1000,
+        as_integers = TRUE
+    ),
+    fish_fx = list(
+        ac_samps = 1000,
+        as_integers = TRUE
+    ),
+    fish_tw = list(
+        ac_samps = 1000,
+        as_integers = TRUE
+    )
+)
+
+model_options$obs_pars <- obs_pars
+
+
+ + + +
+ + + +
+

+

Developed by Benjamin Williams, Joshua Zahner, Matt Cheng, Dan Goethel, Curry Cunningham.

+
+ +
+

+

Site built with pkgdown 2.0.7.

+
+ +
+
+ + + + + + + + diff --git a/docs/articles/multiyear_projections.html b/docs/articles/multiyear_projections.html new file mode 100644 index 0000000..48743ef --- /dev/null +++ b/docs/articles/multiyear_projections.html @@ -0,0 +1,141 @@ + + + + + + + +Conducting Multiyear Projections • afscOM + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Conducting Multiyear Projections

+ + + + + +
+ + + +

The basal component of the afscOM packages is the project() function.

+
+om <- project(removals, fleet.props, dem_params, prev_naa, recruitment, options)
+

This function projects a population forward a single year based on the previous year’s age structure, and the current year’s demographic parameters, removals, and recruitment.

+
+

The project_multi() Function +

+

However, it is often desirable to conduct multi-year forward projections. This is as simple as wrapping the project() function as shown above in a for loop and doing some careful indexing. The afscOM package provides an additional project_multi() function that handles such projection simulation.

+
+om <- project_multi(init_naa, removals, recruitment, dem_params, nyears, model_options)
+

The key differences between the project_multi and basic project function are in how the input parameters are defined.

+

For the basic project function, the parameters all represent single year inputs. So, the “removals” parameter represents the amount of catch to take in the next projection year, while the “recruitment” parameter represents how many recruits enter the population in the next projection year. Similarly, the “dem_params” input parameter, represents the value of the demographic rates for a single year (so they have dimension [1, nages, nsexes, nregions, nfleets]).

+

The project_multi function, however, expects all inputs as vectors of length nyears. By providing vectors of catch and recruitment, the project_multi function iteratively applies a specific catch level and number of recruits to the population for multiple years.

+

Rarely are catch levels or recruitment levels known in the future, but project_multi() does not currently support generating new catch or recruitment levels based on the current internal state of the population (e.g. recruitment can not be pulled from a stock recruit curve based on annual spawning biomass).

+

Future versions of the afscOM may implement means to dynamically generate recruitment based on internal population state (such as a stock recruit relationship), as well as means of computing future catch levels from simple harvest control rules.

+
+
+ + + +
+ + + +
+

+

Developed by Benjamin Williams, Joshua Zahner, Matt Cheng, Dan Goethel, Curry Cunningham.

+
+ +
+

+

Site built with pkgdown 2.0.7.

+
+ +
+
+ + + + + + + + diff --git a/docs/articles/observation_processes.html b/docs/articles/observation_processes.html new file mode 100644 index 0000000..8619603 --- /dev/null +++ b/docs/articles/observation_processes.html @@ -0,0 +1,126 @@ + + + + + + + +Observation Processes • afscOM + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Observation Processes

+ + + + + +
+ + + + +
+ + + +
+ + + +
+

+

Developed by Benjamin Williams, Joshua Zahner, Matt Cheng, Dan Goethel, Curry Cunningham.

+
+ +
+

+

Site built with pkgdown 2.0.7.

+
+ +
+
+ + + + + + + + diff --git a/docs/articles/specifying_demographic_parameters.html b/docs/articles/specifying_demographic_parameters.html new file mode 100644 index 0000000..fe28e83 --- /dev/null +++ b/docs/articles/specifying_demographic_parameters.html @@ -0,0 +1,209 @@ + + + + + + + +Specifying Demographic Rates • afscOM + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Specifying Demographic Rates

+ + + + + +
+ + + +

To parameterize a model built with afscOM to behave like a specific population, the user needs to specify a set of population demographic parameters. These parameters all take the same computational structure: a multi-dimensional array.

+

These multidimensional arrays MUST always follow the same dimension structure for afscOM to work correctly. Biological parameters, such as natural mortality, maturity, and weight-at-age should all have array dimensions: [nyears, nages, nsexes, nregions]. Fishery and survey fleet parameters, such as selectivity, retention, and discard mortality, should have array dimensions: [nyears, nages, nsexes, nregions, nfleets] (for fishing fleets) or [nyears, nages, nsexes, nregions, nsurveys] (for survey fleets).

+

In this structure the first index along the “sex” dimension (dimension 3) will correspond to parameters for females, while the second index will correspond to parameters for males.

+

Required population parameters include:

+
    +
  1. +mort: Natural mortality [nyears, nages, nsexes, nregions] +
    2. +
  2. +mat: Maturity [nyears, nages, nsexes, nregions] +
    3. +
  3. +waa: Weight-at-age [nyears, nages, nsexes, nregions] +
    4. +
  4. +sexrat: Population sex ratio [nyears, nages, nsexes, nregions] +
    5. +
  5. +sel: Fishery selectivity [nyears, nages, nsexes, nregions, nfleets] +
    6. +
  6. +ret: Fishery retention [nyears, nages, nsexes, nregions, nfleets] +
    7. +
  7. +dmr: Fishery discard mortality (as an instantenous rate) [nyears, nages, nsexes, nregions, nfleets] +
    8. +
  8. +surv_sel: Survey selectivity [nyears, nages, nsexes, nregions, nsurveys] +
    9. +
+
+

Building Parameter Matrices +

+

To facilitate easier creation of these multi-dimensional parameter matrices, a helper function generate_param_matrix(...) has been provided. This function accepts as input a single value, a vector of values, or a matrix/array of values, and a list of dimensions over which to fill a fully-formed parameter matrix with that input.

+

For example, if natural mortality (M) is assumed to be constant across time, age, sex, and space, the following code will create an [nyears, nages, nsexes, nregions] parameter matrix where every value is the same:

+
+dimension_names <- list(
+    "time" = 1:nyears,
+    "age"  = 2:31,
+    "sex"  = c("F", "M"),
+    "region" = "alaska",
+    "fleet" = c("Fixed", "Trawl")
+)
+
+M <- 0.113179
+mort <- generate_param_matrix(M, dimension_names = dimension_names)
+

If maturity is assumed to vary by age, but is otherwise constant across time, sex, and space, the following code will create a properly formed parameter matrix where each age has a different maturity level:

+
+maturity <- c(0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0, 1.0, 1.0, 1.0, 1.0)
+mat <- generate_param_matrix(maturity, dimension_names = dimension_names, by="age")
+

Finally, if weight-at-age (WAA) varies by both age and sex, the following code will create the appropriately formed parameter matrix with different values for WAA by age and sex, but repeated across time and space:

+
+weight_mat <- matrix(NA, nrow=11, ncol=2, dimnames=dimension_names[c("age", "sex")])
+weight_mat[,1] <- c(2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22)
+weight_mat[,2] <- c(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11)
+waa <- generate_param_matrix(weight_mat, dimension_names = dimension_names, by=c("age", "sex"))
+

The generate_param_matrix requires the user to specify as a parameter input the names of each dimension in the output matrix as a list. The function will work correctly regardless of the specific dimension names used, however, when filling across 2-or-more dimensions (as in the above example with weight-at-age), the input matrix (that is being used to fill the larger parameter matrix), must also have the same dimension names along the corresponding axes.

+

In the weight-at-age example above, the weight_mat matrix, which contained the WAAs for each age and sex, has dimension names equivalent to the dimension names along the “age” and “sex” dimensions that are provided to generate_param_matrix. If these names do not match, an error will be returned to the user indicating as such.

+

For fleet parameters, such as selectivity or retention, an extra dimension nfleets is required. generate_param_matrix has an additional, include_fleet_dim parameter that can be specified to indicate that the output array should have a fleet dimension in addition to the other four dimensions. If the parameter is specified to vary across fleets, the include_fleet_dim parameter will be automatically turned on.

+

For example:

+
+selex_mat <- array(NA, dim=c(11, 2, 2), dimnames=dimension_names[c("age", "sex", "fleet")])
+selex_mat[,1,1] <- c(0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0, 1.0, 1.0, 1.0, 1.0)
+selex_mat[,2,1] <- c(0.0, 0.1, 0.2, 0.4, 0.6, 0.7, 0.8, 0.9, 1.0, 1.0, 1.0)
+selex_mat[,1,2] <- c(0.3, 0.7, 1.0, 1.0, 0.9, 0.7, 0.6, 0.5, 0.4, 0.4, 0.4)
+selex_mat[,2,2] <- c(0.2, 0.6, 1.0, 0.95, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3, 0.3)
+sel <- generate_param_matrix(selex_mat, dimension_names = dimension_names, by=c("age", "sex", "fleet"))
+

Once these population parameter matrices have been defined, they need to be added to a list that will be passed as a parameter to the OM:

+
+dem_params <- list(
+    waa=waa,
+    mat=mat,
+    mort=mort,
+    sexrat=sexrat,
+    sel=sel,
+    ret=ret,
+    dmr=dmr,
+    surv_sel=survey_sel
+)
+

An additional helper function validate_dem_params, takes as input a list of population parameter matrices, and the expected dimensions, and will check if all required parameter matrices are present and of appropriate dimensions. If required parameters are missing, or are of incorrect dimensions, an error will be returned. It is recommended that this function be used prior to running the model to verify that the input parameters matrices are correctly specified.

+
+model_dimension <- list(nyears=64, nages=30, nsexes=2, nregions=1, nfleets=2, nsurveys=2)
+dem_params <- validate_dem_params(dem_params, model_dimensions)
+
+
+ + + +
+ + + +
+

+

Developed by Benjamin Williams, Joshua Zahner, Matt Cheng, Dan Goethel, Curry Cunningham.

+
+ +
+

+

Site built with pkgdown 2.0.7.

+
+ +
+
+ + + + + + + + diff --git a/docs/authors.html b/docs/authors.html index cbb6baa..1635423 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -23,6 +23,9 @@ diff --git a/docs/index.html b/docs/index.html index 5429bd3..ddfbbbd 100644 --- a/docs/index.html +++ b/docs/index.html @@ -40,6 +40,9 @@