Update Roxygen documentation for inclusion in repo R package.

Reference-Points-and-Projections/P-star.basic.model.R

@@ -1,8 +1,7 @@
 #' @title Conduct the P* projections for the MAFMC
 #' 
 #' @description Conducts the P* projections, which incorporates uncertainty and risk in ABC calculation from OFL using a fitted WHAM model 
-#' @source from C Adams for butterfish 7-5-2022
-#' @expanded by E Liljestrand 7-19-2024
+#' @author E Liljestrand 7-19-2024, expanded code provided by C Adams for butterfish 7-5-2022
 #' 
 #' @param mod An rds from a WHAM fit
 #' @param SSBmsy the SSBmsy proxy used to calculate ratio between biomass and reference point
@@ -13,7 +12,7 @@
 #' 
 #' @return a model object with the years of projected values based on P* catch advice 
 #' 
-#' @example
+#' @examples
 #' mod <- readRDS("Modeling/Run3/fit.RDS")
 #' SSBmsy <- 11225        
 #' catch.year1 <- 7557
@@ -69,4 +68,4 @@ pstarmodel <- function(mod=NULL,SSBmsy=NULL,catch.year1=NULL,projyr=3,CV=1.5,avg
   # Return the final projection model
   return(mod.proj)
 
-}
+}

Reference-Points-and-Projections/P-star.basic.table.R

@@ -1,8 +1,7 @@
 #' @title Conduct the P* projections for the MAFMC
 #' 
 #' @description Conducts the P* projections, which incorporates uncertainty and risk in ABC calculation from OFL using a fitted WHAM model 
-#' @source from C Adams for butterfish 7-5-2022
-#' @expanded by E Liljestrand 7-19-2024
+#' @author E Liljestrand 7-19-2024, expanded code provided by C Adams for butterfish 7-5-2022
 #'
 #' @param mod An rds from a WHAM fit
 #' @param SSBmsy the SSBmsy proxy used to calculate ratio between biomass and reference point
@@ -22,7 +21,7 @@
 #'   \item{P* - Pstar value}
 #' }
 #' 
-#' @example
+#' @examples
 #' mod <- readRDS("Modeling/Run3/fit.RDS")
 #' SSBmsy <- 11225        
 #' catch.year1 <- 7557
@@ -104,4 +103,4 @@ pstartable <- function(mod=NULL,SSBmsy=NULL,catch.year1=NULL,projyr=3,CV=1.5,avg
 
   return(pstartable.df)
 
-}
+}

Reference-Points-and-Projections/abccalc.R

@@ -1,15 +1,15 @@
 #' @title Function to calculate the ABC using a lognormal distribution
 #' 
 #' @description Calculates ABC using inputs of the OFL, biomass relative to target and assumed CV for OFL 
-#' @source from M. Wilberg, originally 7-26-2011, updated with new MAFMC P* policy 5-10-2022
+#' @author E Liljestrand, expanded code from M. Wilberg, originally 7-26-2011, updated with new MAFMC P* policy 5-10-2022
 #' 
 #' @param OFL OFL for the stock
 #' @param relB B/Bmsy
 #' @param CV Coefficient of variation for OFL
 #' 
 #' @return ABC - allowable biological catch 
 #' 
-#' @example
+#' @examples
 #' catch <- ABC(12345,1.11,0.6)
 
 ABC <- function(OFL, relB, CV)

Reference-Points-and-Projections/invabccalc.R

@@ -1,7 +1,7 @@
 #' @title Inverse function to calculate P* from ABC and OFL
 #' 
 #' @description takes as inputs the OFL, biomass relative to its target, and the assumed CV for the OFL
-#' @source from M. Wilberg, originally 7-26-2011, updated with new MAFMC P* policy 5-10-2022
+#' @author E Liljestrand, expanded code from M. Wilberg, originally 7-26-2011, updated with new MAFMC P* policy 5-10-2022
 #' 
 #' 
 #' @param relB ABC - allowable biological catch 
@@ -10,7 +10,7 @@
 #' 
 #' @return P* value
 #' 
-#' @example
+#' @examples
 #' inv_ABC <- inv_ABC(11456,13234,1.0)
 
 inv_ABC <- function(ABC,OFL, CV)
@@ -20,4 +20,4 @@ inv_ABC <- function(ABC,OFL, CV)
 
   #Calculate ABC using inverse of the lognormal dist
   return(plnorm(ABC, meanlog = log(OFL), sdlog = sd))
-}
+}

Reference-Points-and-Projections/pstarcalc.R

@@ -1,13 +1,13 @@
 #' @title Function to calculate P* FROM RELATIVE BIOMASS AND COUNCIL POLICY
 #' 
 #' @description Calculates P* using input of the Biomass relative to target 
-#' @source from M. Wilberg, originally 7-26-2011, updated with new MAFMC P* policy 5-10-2022
+#' @author E Liljestrand, expanded code from M. Wilberg, originally 7-26-2011, updated with new MAFMC P* policy 5-10-2022
 #' 
 #' @param relB B/Bmsy
 #' 
 #' @return P* 
 #' 
-#' @example
+#' @examples
 #' Pstar <- calc_pstar(1.55)
 
 calc_pstar <- function(relB)
@@ -32,4 +32,4 @@ calc_pstar <- function(relB)
     }
   }
   return(P)
-}
+}

Reports/calc.rho.adj.ests.R

@@ -1,10 +1,10 @@
 #' @title calc.rho.adj.ests
 #' @description Calculate rho-adjusted time series based on 90% CI
 #' @param series A data frame containing the following columns:
-#' \itemise{
-#'   \item{est - Estimated time series}
-#'   \item{lo_90 Lower 90% CI for estimates}
-#'   \item{hi_90 Upper 90% CI for estimates}
+#' * est -  Estimated time series
+#' * lo_90 - Lower 90% CI for estimates
+#' * hi_90 - Upper 90% CI for estimates
+#' @md
 #' @param rho Mohn's rho value associated with the time series.
 #' 
 #' @return A data table containing original and rho-adjusted time series with accompanying 90% CI. 
@@ -18,4 +18,4 @@ calc.rho.adj.ests <- function(series = NULL,
     )
 
   return(result)
-}
+}

Reports/calc.uncertainty.R

@@ -1,6 +1,5 @@
-#' @param log.est An estimated time series in log space, no default.
-#' @param log.se A vector of log standard errors corresponding to the estimated time series, no default. 
-#' 
+#' @title Calculate uncertainty
+#' @description Calculate CV, 90% and 95% CI given a model estimate and standard error.
 #' @param log.est An estimated time series in log space, no default.
 #' @param log.se A vector of log standard errors corresponding to the estimated time series, no default. 
 #' 
@@ -11,9 +10,12 @@
 #'   \item{CV - Accompanying CVs}
 #'   \item{lo_95 - Lower 95% confidence intervals}
 #'   \item{hi_95 - Upper 95% confidence intervals}
-#'   \item{lo_90 - Lower 99% confidence intervals}
-#'   \item{hi_90 - Upper 99% confidence intervals}
+#'   \item{lo_90 - Lower 90% confidence intervals}
+#'   \item{hi_90 - Upper 90% confidence intervals}
 #' }
+#' 
+#' @md
+
 calc.uncertainty <- function(log.est = NULL,
                              log.se = NULL){
   result <- cbind(log.est, log.se) %>% as.data.frame() %>%

Reports/create.brp.text.R

@@ -6,8 +6,8 @@
 #' \itemize{
 #'   \item{BRP - Name of the BRP}
 #'   \item{est - BRP estimates}
-#'   \item{lo_95 - Lower 95% confidence bound}
-#'   \item{hi_95 - Upper 95% confidence bound}
+#'   \item{lo_95 - Lower 95\% confidence bound}
+#'   \item{hi_95 - Upper 95\% confidence bound}
 #'   \item{source - Model source, either "prior" for prior assessment or "MT" for current assessment}
 #' }
 #' 

Reports/makeMTslides.R

@@ -168,7 +168,7 @@ makeMTslides <- function(wham_model = NULL,
   # Bridge runs
   write("## Bridge runs")
 
-  # Model fit to fleet 
+  # Model fit to aggregate fleet 
   for(iregion in 1:n_region){ # If multi_wham == FALSE n_region = 1 so only does this loop once
     for(ifleet in 1:n_fleet){
       # Format slide
@@ -201,7 +201,7 @@ makeMTslides <- function(wham_model = NULL,
   for(iregion in 1:n_region){ # If multi_wham == FALSE n_region = 1 so only does this loop once
     for(ifleet in 1:n_fleet){
       # Format slide
-      write(paste0("## Aggregate fit to ", fleet_names[ifleet], " fleet"), slideOut, append = TRUE) # write title
+      write(paste0("## Fit to ", fleet_names[ifleet], " fleet age composition"), slideOut, append = TRUE) # write title
       write(":::: {.columns}", slideOut, append = TRUE) # Initialize columns
 
       # OSA bubble plot
@@ -222,7 +222,7 @@ makeMTslides <- function(wham_model = NULL,
     } # End loop over fleets
   } # End loop over regions
 
-  # Model fit to indices
+  # Model fit to aggregate indices
   for(iregion in 1:n_region){ # If multi_wham == FALSE n_region = 1 so only does this loop once
     for(index in 1:n_index){
       # Format slide
@@ -251,6 +251,35 @@ makeMTslides <- function(wham_model = NULL,
     } # End loop over indices
   } # End loop over regions
 
+  # Model fit to index age comps
+  for(iregion in 1:n_region){ # If multi_wham == FALSE n_region = 1 so only does this loop once
+    for(index in 1:n_index){
+      # Format slide
+      write(paste0("## Fit to ", index_names[index]," index age composition"), slideOut, append = TRUE) # write title
+      write(":::: {.columns}", slideOut, append = TRUE) # Initialize columns
+
+      # Bubble plot
+      write("::: {.column width='50%'}", slideOut, append = TRUE)
+      #write(index_names[index], slideOut, append = TRUE)
+      write("", slideOut, append = TRUE) # Must have empty space or plots not pulled into powerpoint
+      if(multi_wham == TRUE){
+        write(paste0("![](", paste(plotPath,"diagnostics", paste0("Catch_age_comp_osa_resids_index_", index, "_region_", iregion, ".png"), sep="/"),")"), slideOut, append = TRUE) 
+      } else{
+        write(paste0("![](", paste(plotPath,"diagnostics", paste0("Catch_age_comp_osa_resids_index_", index, ".png"), sep="/"),")"), slideOut, append = TRUE) 
+      }
+      write(":::", slideOut, append = TRUE)
+
+      # OSA column 
+      write("::: {.column width='50%'}", slideOut, append = TRUE)
+      #write(index_names[index], slideOut, append = TRUE)
+      write("", slideOut, append = TRUE) # Must have empty space or plots not pulled into powerpoint
+      write(paste0("![](", paste(plotPath,"diagnostics", paste0("OSA_resid_paa_6panel_index_", index, ".png"), sep="/"),")"), slideOut, append = TRUE)
+      write(":::", slideOut, append = TRUE)
+
+      write("::::", slideOut, append = TRUE) # End columns
+    } # End loop over indices
+  } # End loop over regions
+
   # Retrospective plots: Fbar (don't iterate over stocks in multi-wham so labeled differently)
   for(iregion in 1:n_region){
     for(istock in 1:n_stock){

Reports/makeReportData.R

@@ -1,9 +1,9 @@
+#' @title Extract WHAM results for report
+#' @description Pull WHAM results from the current MT model, projections, and the prior MT assessment, format, and save as an .RDS object for use in generating short reports.
+#' 
 #' @param model_MT The current fitted WHAM assessment model object, no default.
 #' @param model_MTproj The current fitted WHAM assessment with projections implemented, no default.
-#' @param model_prior The prior assessment model provided as a WHAM model object OR as a list containing the following:
-#' \itemize{
-#'   \item{}
-#' }
+#' @param model_prior The prior assessment model provided as a WHAM model object 
 #' @param multiWHAM A vector of booleans for 1) the current MT model and 2) the current MT model with projections applied and 3) the prior assessment, if TRUE, assumes that the model is generated by multi-WHAM and includes additional indexing for region/stock as well as any differences in labels. Default = FALSE.
 #' @param index_names A vector of index names (with NO spaces) that match the order they are listed in the model_MT, default = "index1", "index2"..."index_n". Also used in automatically labeling indices in report unless column names manually overwritten in MT report template. Using spaces or special characters (like "&") in index_names will result in nasty LaTex errors.
 #' @param outdir A file path specifying the directory where MT report data should be saved
@@ -15,12 +15,11 @@
 #'   \item{text_ssb - Text for SSB proxy BRP}
 #'   \item{text_f - Text for F proxy BRP}
 #'   \item{proj_yrs - Projection years, pulled from model_MTproj}
-#'   \item{MT_BRPs - A table of MT BRPs with 95% CI}
+#'   \item{MT_BRPs - A table of MT BRPs with 95\% CI}
 #'   \item{indices - A table of index time series with associated CVs}
 #'   \item{n_indices - The number of indices in model_MT}
 #'   \item{MT_termyr - A table of estimates and rho-adjusted values for F, SSB, and Recruitment terminal year estimates, associated CVs and the BRP ratio}
-#' }
-#' 
+#' }   
 
 library(tidyverse)
 library(wham)

Reports/pullResults_WHAM.R

@@ -6,20 +6,21 @@
 #' 
 #' @return A list containing the following
 #' \itemize{
-#'   \item{brps - A table of BRP estimates with 95% CI for F, SSB and MSY proxies}
+#'   \item{brps - A table of BRP estimates with 95\% CI for F, SSB and MSY proxies}
 #'   \item{NAA - A table of NAA}
-#'   \item{FAA - A table of FAA}
+#'   \item{ FAA - A table of FAA}
 #'   \item{Mohns_rho - A list of Mohn's rho values for F, SSB, and NAA}
 #'   \item{F.yr - A table containing a time series of F estimates and CVs}
 #'   \item{F.yr_adj - F.yr table with Mohn's rho adjustments}
 #'   \item{SSB.yr - A table containing a time series of SSB estimates and CVs}
 #'   \item{SSB.yr_adj - SSB.yr table with Mohn's rho adjustments}
 #'   \item{Rect.yr - A table containing a time series of Recruitment and CVs}
 #'   \item{Rect.yr_adj - Rect.yr table with Mohn's rho adjustments}
-#'   \item{termyr.ests.cis - A table of terminal year estimates of F, SSB, and Recruitment with 95% and 90% CIs}
+#'   \item{termyr.ests.cis - A table of terminal year estimates of F, SSB, and Recruitment with 95\% and 90\% CIs}
 #' }
 
 
+
 #model <- readRDS("C:/Users/amanda.hart/Cod_GBK/MT/Cod_GB_MT_2024/Bridge_runs/9_bridge_reviseCV_NEFSC/9_bridge_model.rds")
 
 

WHAM/Mdeaths.R

@@ -6,7 +6,7 @@
 #' 
 #' @return A dataframe with two columns. Year and Deaths(000s mt)
 #'
-#' @example
+#' @examples
 #' mod.dir="m168"
 #' write.dir <- paste("C:/Herring/2022 Assessment/Assessments/WHAM",mod.dir,sep="/")
 #' setwd(write.dir)

WHAM/check_for_cohort_increase.R

@@ -3,11 +3,11 @@
 #' @description
 #' Random effects can allow a cohort to increase from one year and age to the next year and age. This function makes a plot to quickly identify when this happens.
 #' 
-#' @ param mod A model result from WHAM, can be either single WHAM or multi WHAM.
+#' @param mod A model result from WHAM, can be either single WHAM or multi WHAM.
 #'
-#' @ return A ggplot showing the relative percent change for each cohort (including the plus group) with the number denoting the age and year of the surviving fish. Values above zero (the red dashed line) indicate the cohort has increased. Values above 100 may be cause for concern.
+#' @return A ggplot showing the relative percent change for each cohort (including the plus group) with the number denoting the age and year of the surviving fish. Values above zero (the red dashed line) indicate the cohort has increased. Values above 100 may be cause for concern.
 #'
-#' @ example
+#' @examples
 #' mod <- readRDS("m38.RDS")
 #' p <- check_for_cohort_increase(mod)
 #' ggsave(filename = "my_cohort_check.png", p)

WHAM/compareWHAMslides.R

@@ -23,7 +23,7 @@
 #' 
 #' @return A .qmd and output slides in the selected slideOut directory to compare the specified model runs
 #'
-#' @example 
+#' @examples
 #' # Generalized file paths and labels are purely for demonstration and would need to be updated to run on individual machines
 #' compareWHAMslides(plotPaths = c(here::here("model1_folder/plots_png"),
 #'                                 here::here("model2_folder/plots_png")),

WHAM/do_selftest.R

@@ -1,10 +1,10 @@
-#--------------
+#' @title do_selftest
 #' @description
 #' Perform simulation self-test of a WHAM model.
 #' 
 #' @param mod wham model created with `fit_wham()`
 #' @param n_sim number of simulations to perform
-#' @ return data.frame of annual true and estimated F, R, and SSB
+#' @return data.frame of annual true and estimated F, R, and SSB
 do_selftest <- function(mod, n_sim) {
 
   sim_inputs <- replicate(n_sim, sim_fn(mod), simplify=FALSE)

WHAM/drop_term_index_retro.R

@@ -7,7 +7,7 @@
 #'
 #' @return A list containing the results of each fit. Also saves a png plot of NAA devs from each fit and the SSB retro where the selected index data are missing from each terminal year. Saved to the working directory
 #'
-#' @example 
+#' @examples 
 #' #drops all indices from a fit
 #' droptermIndex=drop_term_index_retro(model=mod,drop=list(indices=1:mod$input$data$n_indices,index_paa=1:mod$input$data$n_indices)) 
 #' drop whatever index 2 is from a fit
@@ -57,4 +57,4 @@ drop_term_index_retro=function(model=NULL,drop=NULL){
   graphics.off()
 
   return(peel)
-}
+}

WHAM/fit_hindcast.R

@@ -8,8 +8,8 @@
 #' 
 #' @return A WHAM model fit
 #'
-#' @example 
-#' fit_hindcast(model=WHAMRUN.rds, peel=1, drop=list(indices=1:2, index_paa=1:2))
+#' @examples
+#'  fit_hindcast(model=WHAMRUN.rds, peel=1, drop=list(indices=1:2, index_paa=1:2))
 
 fit_hindcast <- function(model, peel, drop){
   temp = list(data = model$env$data, par = model$parList, map = model$env$map, random = unique(names(model$env$par[model$env$random])))
@@ -18,4 +18,4 @@ fit_hindcast <- function(model, peel, drop){
   temp$data$use_index_paa[(nyrs - peel+1):nyrs, drop$index_paa] = 0
   mod <- fit_wham(temp, do.retro = FALSE, do.osa = FALSE)
   return(mod)
-}
+}

WHAM/make_simtest_plots.R

@@ -1,4 +1,4 @@
-#--------------
+#' @title make_simtest_plots
 #' @description
 #' Automated creation of plots from a WHAM simulation self-test. Main plot shows mean, median, and 5%, 25%, 75%, 95% quantiles. 
 #' Optional additional plots show only mean with standard error, only median and quantiles, and numerous realizations. 
@@ -11,7 +11,7 @@
 #' @param savepng Boolean (default=FALSE) when TRUE save the selected plot(s) as separate png files
 #' @param myfilename_pdf (default=NULL) name (including filepath if so desired) for pdf to be created
 #' @param mypngprefix (default=NULL) prefix added to default names for all saved png files (including filepath is so desired)
-#' @ return list of 8 figures, main figure is first one  
+#' @return list of 8 figures, main figure is first one  
 
 make_simtest_plots <- function(mod_selftest, saveall=FALSE, savepdf=FALSE, savepng=FALSE, myfilename_pdf=NULL, mypngprefix=NULL){
 

WHAM/plotNAAfxn.R

@@ -7,7 +7,7 @@
 #' 
 #' @return A ggplot. Must use ggsave after running the function to save the plot
 #'
-#' @example 
+#' @examples 
 #' naaplot=plotNAAfxn(mods=mod,cor="NA")
 #' ggsave(paste("YOURNAME","_NAAdevs.jpeg"),naaplot,path=YOURPATH)