From 7dc23057b6e05a57ccee5b02c1a43fb3c0b89e2d Mon Sep 17 00:00:00 2001
From: Ben Williams <ben.williams@noaa.gov>
Date: Wed, 2 Oct 2024 08:51:05 -0800
Subject: [PATCH] update documentation

---
 NAMESPACE                                     |  3 +-
 R/derived_quantities.R                        | 24 +++++------
 R/plotting.R                                  | 42 ++++++++-----------
 R/project_multi.R                             | 12 +++---
 R/recruitment.R                               | 22 +++++-----
 R/utils.R                                     |  7 ++--
 R/validate_dem_params.R                       | 21 +++++-----
 man/beverton_holt.Rd                          | 19 ---------
 ...c.recruitment.Rd => cyclic_recruitment.Rd} | 14 +++----
 man/plot_mort.Rd                              |  2 +-
 man/project_multi.Rd                          |  2 +-
 man/resample_recruitment.Rd                   |  9 +++-
 man/setup_model_options.Rd                    |  7 ++++
 man/validate_dem_params.Rd                    | 22 +++++++++-
 14 files changed, 105 insertions(+), 101 deletions(-)
 delete mode 100644 man/beverton_holt.Rd
 rename man/{cyclic.recruitment.Rd => cyclic_recruitment.Rd} (65%)

diff --git a/NAMESPACE b/NAMESPACE
index 6309230..9cd3262 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -2,14 +2,13 @@
 
 export(F_to_mu)
 export(baranov)
-export(beverton_holt)
 export(catch_at_age)
 export(compute_bio)
 export(compute_fleet_catch)
 export(compute_ssb)
 export(compute_total_catch)
 export(compute_total_f)
-export(cyclic.recruitment)
+export(cyclic_recruitment)
 export(discard_F)
 export(extend_years)
 export(findF_bisection)
diff --git a/R/derived_quantities.R b/R/derived_quantities.R
index b26272c..580e174 100644
--- a/R/derived_quantities.R
+++ b/R/derived_quantities.R
@@ -1,5 +1,5 @@
 #' Compute Spawning Stock Biomass
-#' 
+#'
 #' Compute SSB from a matrix of NAA and a set of demographic
 #' parameters.
 #'
@@ -8,7 +8,7 @@
 #'
 #' @export compute_ssb
 #'
-#' @example
+
 #'
 compute_ssb <- function(naa, dem_params){
     return(
@@ -17,7 +17,7 @@ compute_ssb <- function(naa, dem_params){
 }
 
 #' Compute Total Stock Biomass
-#' 
+#'
 #' Compute biomass from a matrix of NAA and a set of demographic
 #' parameters. This computes the sum of male and female biomass
 #' across all age classes. For mature female biomass, see
@@ -26,9 +26,9 @@ compute_ssb <- function(naa, dem_params){
 #' @param naa numbers-at-age matrix [nyears, nages, nsexes, nregions]
 #' @param dem_params demagraphic parameters list
 #'
-#' @export compute_bio 
+#' @export compute_bio
 #'
-#' @example
+
 #'
 compute_bio <- function(naa, dem_params){
     return(
@@ -37,14 +37,14 @@ compute_bio <- function(naa, dem_params){
 }
 
 #' Compute Total Catch
-#' 
+#'
 #' Compute total catch volume (in mt) from a matrix of CAA.
 #'
 #' @param caa catch-at-age matrix [nyears, nages, nsexes, nregions, nfleets]
 #'
-#' @export compute_total_catch 
+#' @export compute_total_catch
 #'
-#' @example
+
 #'
 compute_total_catch <- function(caa){
     return(
@@ -53,7 +53,7 @@ compute_total_catch <- function(caa){
 }
 
 #' Compute Catch by Fishing Fleet
-#' 
+#'
 #' Compute total catch volume (in mt) for each fishing
 #' fleet from a matrix of CAA.
 #'
@@ -61,7 +61,7 @@ compute_total_catch <- function(caa){
 #'
 #' @export compute_fleet_catch
 #'
-#' @example
+
 #'
 compute_fleet_catch <- function(caa){
     return(
@@ -70,7 +70,7 @@ compute_fleet_catch <- function(caa){
 }
 
 #' Compute Total Fishing Mortality
-#' 
+#'
 #' Compute total fishing mortality from a matrix of FAA.
 #' Note that this is an approximation of total fishing mortality,
 #' and assumes that selectivity = 1 for some age class.
@@ -79,7 +79,7 @@ compute_fleet_catch <- function(caa){
 #'
 #' @export compute_total_f
 #'
-#' @example
+
 #'
 compute_total_f <- function(faa){
     return(
diff --git a/R/plotting.R b/R/plotting.R
index af1162c..5b891cf 100644
--- a/R/plotting.R
+++ b/R/plotting.R
@@ -1,5 +1,5 @@
 #' Plot demographic parameters
-#' 
+#'
 #' Generate standard plot for all demographic
 #' parameter matrices. Output plots will include:
 #' - weight-at-age
@@ -16,12 +16,11 @@
 #' @param out_dir optional directory to save plots to
 #' @param ... additional parameters to be passed to `ggsave`
 #'
-#' @export plot_demographic_parameters
+#' @export
 #'
-#' @example
 #'
 plot_demographic_parameters <- function(dem_params, params=NA, show_plots=TRUE, out_dir=NA, ...){
-    
+
     waa_plot  <- plot_waa(dem_params$waa)
     mat_plot  <- plot_mat(dem_params$mat)
     mort_plot <- plot_mort(dem_params$mort, is_dmr=FALSE)
@@ -55,15 +54,14 @@ plot_demographic_parameters <- function(dem_params, params=NA, show_plots=TRUE,
 }
 
 #' Plot Weight-at-Age
-#' 
+#'
 #' Generates plot of weight-at-age across time, age, sex,
 #' and region as appropriate.
 #'
 #' @param waa four-dimensional weight-at-age matrix
 #'
-#' @export plot_waa
+#' @export
 #'
-#' @example
 #'
 plot_waa <- function(waa){
 
@@ -82,7 +80,7 @@ plot_waa <- function(waa){
         coord_cartesian(expand=0)+
         labs(x="Age", y="Weight", color="Sex", linetype="Time Block", title="Weight-at-Age")+
         theme_bw()
-    
+
     if(dimensions$nregions > 1){
         plot <- plot + facet_wrap(~region, scales="free_y")
     }
@@ -92,16 +90,14 @@ plot_waa <- function(waa){
 }
 
 #' Plot Maturity-at-Age
-#' 
+#'
 #' Generates plot of maturity-at-age across time, age, sex,
 #' and region as appropriate. Only the female maturity ogive
 #' is plotted.
 #'
 #' @param mat four-dimensional maturity-at-age matrix
 #'
-#' @export plot_mat
-#'
-#' @example
+#' @export
 #'
 plot_mat <- function(mat){
 
@@ -131,16 +127,14 @@ plot_mat <- function(mat){
 }
 
 #' Plot Mortality
-#' 
+#'
 #' Generates plot of mortality-at-age across time, age, sex,
-#' and region as appropriate. This function can be used for 
+#' and region as appropriate. This function can be used for
 #' both natural and discard mortality
 #'
 #' @param waa four-dimensional mortality-at-age matrix
 #'
-#' @export plot_mort
-#'
-#' @example
+#' @export
 #'
 plot_mort <- function(mort, is_dmr=FALSE){
 
@@ -169,16 +163,14 @@ plot_mort <- function(mort, is_dmr=FALSE){
 }
 
 #' Plot Selectivity-at-Age and Retention-at-Age
-#' 
+#'
 #' Generates plot of selectivity-at-age or retention-at-age
 #' across time, age, sex, region, and fleet as appropriate.
 #'
 #' @param selret five-dimensional selectivity-at-age or
 #' retention-at-age matrix
 #'
-#' @export plot_selret
-#'
-#' @example
+#' @export
 #'
 plot_selret <- function(selret, is_selectivity=TRUE){
 
@@ -342,15 +334,15 @@ plot_atage <- function(atage){
         mutate(total_naa = sum(naa)) %>%
         mutate(prop = naa/total_naa) %>%
         mutate(avg_age = weighted.mean(age, prop))
-        
+
 
     plot <- ggplot(atage_df)+
         geom_point(aes(x=time, y=age, size=prop, color=prop))+
         geom_line(
-            data=atage_df %>% distinct(time, avg_age), 
+            data=atage_df %>% distinct(time, avg_age),
             aes(x=time, y=avg_age),
-            linewidth=2, 
-            color='red', 
+            linewidth=2,
+            color='red',
             show.legend = FALSE
         )+
         coord_cartesian(expand=0.01)+
diff --git a/R/project_multi.R b/R/project_multi.R
index 870044b..a654138 100644
--- a/R/project_multi.R
+++ b/R/project_multi.R
@@ -1,7 +1,7 @@
 #' Project Population Forward Multiple Years
-#' 
+#'
 #' A wrapper function around the base `project` function that handles
-#' projecting forward multiple years given a removals timeseries and a 
+#' projecting forward multiple years given a removals timeseries and a
 #' recruitment timeseries.
 #'
 #' @param init_naa numbers-at-age matrix in starting year ([1, nages, nsexes, nregions])
@@ -11,9 +11,7 @@
 #' @param nyears number of projection yeas
 #' @param model_option list of additional model options
 #'
-#' @export project_multi
-#'
-#' @example
+#' @export
 #'
 project_multi <- function(init_naa, removals_timeseries, recruitment, dem_params, nyears, model_options){
 
@@ -50,7 +48,7 @@ project_multi <- function(init_naa, removals_timeseries, recruitment, dem_params
 
     # full_recruitment <- array(NA, dim=c(nyears, 1, 1, nregions))
     r <- apportion_recruitment(
-        rec_timeseries = recruitment, 
+        rec_timeseries = recruitment,
         apportionment = model_options$recruit_apportionment,
         nyears = nyears,
         nregions = nregions
@@ -87,7 +85,7 @@ project_multi <- function(init_naa, removals_timeseries, recruitment, dem_params
             nregions = nregions,
             list(naa=naa[y,,,,drop=FALSE], dem_params=dp.y)
         )
-        
+
         out_vars <- project(
             removals = removals_input,
             dem_params=dp.y,
diff --git a/R/recruitment.R b/R/recruitment.R
index 8fe94b1..ef6bc49 100644
--- a/R/recruitment.R
+++ b/R/recruitment.R
@@ -1,6 +1,6 @@
 #' Resample from historical recruitment timeseries
 #'
-#' Draw `n` random samples, with replacement, from the 
+#' Draw `n` random samples, with replacement, from the
 #' historical recruitment timeseries.
 #'
 #' @param n number of samples to draw
@@ -9,10 +9,10 @@
 #'
 #' @return `n` random samples from the historical
 #' recruitment timeseries.
-#' 
-#' @export resample_recruitment
 #'
-#' @example
+#' @export
+#'
+#' @examples
 #' set.seed(1120)
 #' n <- 100
 #' hist.rec <- c(100, 200, 50, 100, 120)
@@ -37,19 +37,19 @@ mean_recruitment <- function(n, log.mu, sd, seed=NA){
 #' 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 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){
-    
+#' @export
+#'
+
+cyclic_recruitment <- function(n, mu_rec, sd_rec, dur, start=1, seed=NA){
+
     if(!is.na(seed)){
         set.seed(seed)
     }
diff --git a/R/utils.R b/R/utils.R
index c59aaf5..477c34e 100644
--- a/R/utils.R
+++ b/R/utils.R
@@ -144,15 +144,16 @@ extend_years <- function(dem_params, dimension, e, new.dimnames=NA){
 
 
 #' Set Default Values for Model Options
-#' 
+#'
 #' Set up a fully formed model_options list object with all
 #' required elements set to sensible default values.
 #'
 #' @param model_dimensions model dimensions list object
 #'
-#' @export setup_model_options
+#' @export
 #'
-#' @example \dontrun{
+#' @examples
+#' \dontrun{
 #'      dimensions = list(nyears=60, nages=50, nsexes=2, nregions=1, nfleets=1)
 #'      model_options = setup_model_options(dimensions)
 #' }
diff --git a/R/validate_dem_params.R b/R/validate_dem_params.R
index 9f1e650..f06f3ed 100644
--- a/R/validate_dem_params.R
+++ b/R/validate_dem_params.R
@@ -1,12 +1,12 @@
 #' Validate Demographic Parameter Matrices
-#' 
+#'
 #' Helper function for validating that all required demographic
-#' parameter matrices have been defined and that they are all of 
-#' the correct dimension. 
-#' 
-#' Required demographic parameters are: mort, waa, sexrat, sel, 
+#' parameter matrices have been defined and that they are all of
+#' the correct dimension.
+#'
+#' Required demographic parameters are: mort, waa, sexrat, sel,
 #' ret, dmr, and surv_sel
-#' 
+#'
 #' Expected dimensions are: [nyears, nages, nsexes, nregions, nfleets]
 #'
 #' @param dem_params a named list containing the demographic rate matrices.
@@ -16,10 +16,11 @@
 #'
 #' @return unmodified dem_params object; if dem_params list is invalid, will
 #' return a descriptive error message
-#' @export validate_dem_params
+#' @export
+#'
+#' @examples
+#' \dontrun{
 #'
-#' @example \dontrun{
-#'      
 #'      model_dims = list(nyears=64, nages=30, nsexes=2, nregions=1, nfleets=2)
 #'      dem_params = list(
 #'          mort = mortality_matrix,
@@ -31,7 +32,7 @@
 #'          surv_sel = survey_selectivity_matrix
 #'      )
 #'      dem_params = validate_dem_params(dem_params, model_dims)
-#' 
+#'
 #' }
 #'
 validate_dem_params <- function(dem_params, model_dims){
diff --git a/man/beverton_holt.Rd b/man/beverton_holt.Rd
deleted file mode 100644
index 146800d..0000000
--- a/man/beverton_holt.Rd
+++ /dev/null
@@ -1,19 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/recruitment_utils.R
-\name{beverton_holt}
-\alias{beverton_holt}
-\title{Beverton-Holt Stock Recruit Relationship}
-\usage{
-beverton_holt(naa, dem_params, h, R0, S0, sigR)
-}
-\arguments{
-\item{naa}{numbers-at-age array (dimensions [1, nages, nsexes, nregions])}
-
-\item{dem_params}{demographic parameters list susbet to a 
-single year (dimensions [1, nages, nsexes, nregions, nfleets])}
-}
-\description{
-Classic beverton-holt SRR parameterized using steepness,
-unfished recruitment (R0), and unfished spawning biomass
-(S0).
-}
diff --git a/man/cyclic.recruitment.Rd b/man/cyclic_recruitment.Rd
similarity index 65%
rename from man/cyclic.recruitment.Rd
rename to man/cyclic_recruitment.Rd
index 2e890f0..79f940b 100644
--- a/man/cyclic.recruitment.Rd
+++ b/man/cyclic_recruitment.Rd
@@ -1,23 +1,23 @@
 % Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/recruitment.R
-\name{cyclic.recruitment}
-\alias{cyclic.recruitment}
+\name{cyclic_recruitment}
+\alias{cyclic_recruitment}
 \title{Generate log-recruitment from two defined regimes of a specified length}
 \usage{
-cyclic.recruitment(n, mu_rec, sd_rec, dur, start = 1, seed = NA)
+cyclic_recruitment(n, mu_rec, sd_rec, dur, start = 1, seed = NA)
 }
 \arguments{
 \item{n}{number of recruitment events}
 
+\item{mu_rec}{vector of mean log-recruitment levels, one for each regime}
+
+\item{sd_rec}{vector of recruitment variation, one for each regime}
+
 \item{dur}{duration of regimes}
 
 \item{start}{which regime to start in}
 
 \item{seed}{a random seed (optional)}
-
-\item{mu.rec}{vector of mean log-recruitment levels, one for each regime}
-
-\item{sd.rec}{vector of recruitment variation, one for each regime}
 }
 \value{
 `n` log-recruitment levels from two different regimes of
diff --git a/man/plot_mort.Rd b/man/plot_mort.Rd
index 4b997f0..3cffda1 100644
--- a/man/plot_mort.Rd
+++ b/man/plot_mort.Rd
@@ -11,6 +11,6 @@ plot_mort(mort, is_dmr = FALSE)
 }
 \description{
 Generates plot of mortality-at-age across time, age, sex,
-and region as appropriate. This function can be used for 
+and region as appropriate. This function can be used for
 both natural and discard mortality
 }
diff --git a/man/project_multi.Rd b/man/project_multi.Rd
index 9daec1a..fccf5af 100644
--- a/man/project_multi.Rd
+++ b/man/project_multi.Rd
@@ -28,6 +28,6 @@ project_multi(
 }
 \description{
 A wrapper function around the base `project` function that handles
-projecting forward multiple years given a removals timeseries and a 
+projecting forward multiple years given a removals timeseries and a
 recruitment timeseries.
 }
diff --git a/man/resample_recruitment.Rd b/man/resample_recruitment.Rd
index 5284323..86bd099 100644
--- a/man/resample_recruitment.Rd
+++ b/man/resample_recruitment.Rd
@@ -18,6 +18,13 @@ resample_recruitment(n, hist_rec, seed = NA)
 recruitment timeseries.
 }
 \description{
-Draw `n` random samples, with replacement, from the 
+Draw `n` random samples, with replacement, from the
 historical recruitment timeseries.
 }
+\examples{
+set.seed(1120)
+n <- 100
+hist.rec <- c(100, 200, 50, 100, 120)
+resample.recruitment(n, hist.rec)
+
+}
diff --git a/man/setup_model_options.Rd b/man/setup_model_options.Rd
index a652037..4efef05 100644
--- a/man/setup_model_options.Rd
+++ b/man/setup_model_options.Rd
@@ -13,3 +13,10 @@ setup_model_options(model_dimensions)
 Set up a fully formed model_options list object with all
 required elements set to sensible default values.
 }
+\examples{
+\dontrun{
+     dimensions = list(nyears=60, nages=50, nsexes=2, nregions=1, nfleets=1)
+     model_options = setup_model_options(dimensions)
+}
+
+}
diff --git a/man/validate_dem_params.Rd b/man/validate_dem_params.Rd
index 9564f29..d28a5eb 100644
--- a/man/validate_dem_params.Rd
+++ b/man/validate_dem_params.Rd
@@ -19,12 +19,30 @@ return a descriptive error message
 }
 \description{
 Helper function for validating that all required demographic
-parameter matrices have been defined and that they are all of 
+parameter matrices have been defined and that they are all of
 the correct dimension.
 }
 \details{
-Required demographic parameters are: mort, waa, sexrat, sel, 
+Required demographic parameters are: mort, waa, sexrat, sel,
 ret, dmr, and surv_sel
 
 Expected dimensions are: [nyears, nages, nsexes, nregions, nfleets]
 }
+\examples{
+\dontrun{
+
+     model_dims = list(nyears=64, nages=30, nsexes=2, nregions=1, nfleets=2)
+     dem_params = list(
+         mort = mortality_matrix,
+         waa = weight_matrix,
+         sexrat = sexratio_matrix,
+         sel = selectivity_matrix,
+         ret = retention_matrix
+         dmr = disard_mortality_matrix,
+         surv_sel = survey_selectivity_matrix
+     )
+     dem_params = validate_dem_params(dem_params, model_dims)
+
+}
+
+}