Merge pull request #130 from pfmc-assessments/documentation

Update and improve function documentation

R/Biomass.fn.R

@@ -1,36 +1,66 @@
 #' Calculates design based estimates from survey data for West Coast surveys.
+#'
+#' @details
 #' The design based index is calculated based on the area of the strata and
-#' the mean catch by strata.
+#' the mean catch by strata. This function returns a list of design-based
+#' estimates by strata and estimates combined across stratas by year. This
+#' function is designed to work with data frames pulled from the NWFSC
+#' data warehouse using [pull_catch()].
 #' See: Gunderson, D.R. and Sample, T.M. 1980. Distribution and abundance of rockfish off Washington,
 #' Oregon, and California during 1977. Marine Fisheries Review: March - April.
 #'
-#' The variables defining the strata must begin with the name in strat.vars and end with ".1" or ".2" (i.e., Depth_m.1)
-#' the strata are assumed to be continuous variables, thus have a lower and upper value defining them. The lower value does not necessarily have to be the same as the previous upper value.
-#' the stat.df dataframe is difficult to build up with more than one variable becuase it turns into a design where you have to define all areas, thus repeat the variables for one (like a design)
-#'
-#' I calculate the variance given stratified sampling theory
-#' I work in normal space, then calculate the statistics if B is lognormal
-#' This is the Mean Ratio Estimate
-#'
-#' @param dir directory where the output file will be saved
-#' @param dat data-frame of the data that has been by the PullCatch.fn
-#' @param strat.vars A vector of the strata variable names (i.e., c("Depth_m","Latitude_dd"))
-#' @param strat.df a dataframe with the first column the name of the stratum, the second column the area of the stratum, and the remaining columns are the high and low variables defining the strata created by the CreateStrataDF.fn
-#' @param printfolder the folder where files will be saved
-#' @param outputMedian T/F output median or the mean biomass estimate
-#' @param month month for SS
-#' @param fleet fleet number for SS
+#' @template dir
+#' @param dat Data frame of catch data that has been created by the [pull_catch()].
+#' @template strat.vars
+#' @template strat.df
+#' @template printfolder
+#' @param outputMedian Logical input to specify whether to output median or the
+#' mean biomass estimate. Default `TRUE`.
+#' @template month
+#' @template fleet
 #' @template verbose
 #'
+#' @returns List of biomass estimates by year, biomass estimates by year and
+#' strata, and numbers of fish by year.
+#'
 #' @author Allan Hicks and Chantel Wetzel
 #' @importFrom grDevices dev.off png rgb
 #' @importFrom graphics axis legend mtext par plot points segments symbols
 #' @importFrom stats optim qnorm sd var
 #' @importFrom utils write.csv
 #' @export
-
-Biomass.fn <- function(dir = NULL, dat, strat.vars = c("Depth_m", "Latitude_dd"), strat.df, printfolder = "forSS", outputMedian = TRUE,
-                       month = NA, fleet = NA, verbose = TRUE) {
+#'
+#' @examples
+#' \dontrun{
+#' catch <- pull_catch(
+#'   common_name = "petrale sole",
+#'   survey = "NWFSC.Combo"
+#' )
+#'
+#' strata <- CreateStrataDF.fn(
+#'   names = c("shallow_wa", "shallow_or", "shallow_ca", "deep_wa", "deep_or", "deep_ca"),
+#'   depths.shallow = c( 55,   55,   55,  183,  183, 183),
+#'   depths.deep    = c(183,  183,  183,  549,  549, 549),
+#'   lats.south     = c(46.0, 42.0, 32.0, 46.0, 42.0, 32.0),
+#'   lats.north     = c(49.0, 46.0, 42.0, 49.0, 46.0, 42.0))
+#'
+#' biommass <- Biomass.fn(
+#'   dat = catch,
+#'   strat.df = strata
+#' )
+#'
+#' }
+#'
+Biomass.fn <- function(
+  dir = NULL,
+  dat,
+  strat.vars = c("Depth_m", "Latitude_dd"),
+  strat.df,
+  printfolder = "forSS",
+  outputMedian = TRUE,
+  month = "Enter month",
+  fleet = "Enter fleet",
+  verbose = TRUE) {
 
   if (is.null(dat$cpue_kg_km2)) stop("There must be a column called cpue_kg_km2 in the dataframe")
 

R/Format.AKSlope.fn.R

@@ -1,3 +1,6 @@
+#' Rename AFSC slope survey columns from data pulled before 2017
+#'
+#' @details
 #' Rename columns in the AFSC slope survey data file
 #' received prior to the creation of the NWFSC data
 #' warehouse. This function converts the older data files

R/GetN.fn.R

@@ -1,4 +1,4 @@
-#' Calculate effN input sample sizes
+#' Calculate input sample sizes
 #'
 #' @references
 #' Stewart, I.J. and O.S. Hamel. 2014.
@@ -7,19 +7,16 @@
 #' Canadian Journal of Fishery and Aquatic Science, 71(4): 581--588.
 #' [10.1139/cjfas-2013-0289](https://doi.org/10.1139/cjfas-2013-0289).
 #'
-#' @param dir A file path to the main directory where
-#'   `printfolder` will be created. If `NULL`, which is the default,
-#'   then no files will be written to the disk.
-#' @param dat A `data.frame` of composition data.
+#' @template dir
+#' @param dat A data frame of composition data created using [pull_bio()].
 #' @param type A string specifying whether doing "length" or "age" that is
 #'   used to ensure the sample size is of the correct column and create
 #'   the file name of the saved sheet.
 #' @param species A string specifying the species group of interest, which
 #'   will lead to the use of the correct species-specific value for
 #'   the number of unique samples per tow. See the function call for
 #'   allowed values, where the default is `"all"`.
-#' @param printfolder A string that will be used to create the name of the
-#'   folder where files will be saved, i.e., `file.path(dir, printfolder)`.
+#' @template printfolder
 #' @param output A string, where the default is `NULL`, which returns
 #'   only a vector of samples sizes.
 #'   `"summary"`, or any other character string, will return
@@ -28,21 +25,39 @@
 #'
 #' @author Chantel R. Wetzel
 #' @export
+#'
+#' @examples
+#' \dontrun{
+#' bio <- pull_bio(
+#'   common_name = "petrale sole",
+#'   survey = "NWFSC.Combo"
+#' )
+#'
+#' n <- GetN.fn(
+#'   dat = bio,
+#'   type = "length",
+#'   species = "flatfish"
+#' )
+#'
+#' }
+#'
+#'
+GetN.fn <- function(
+  dir = NULL,
+  dat,
+  type = c("length", "age"),
+  species = c(
+    "all",
+    "flatfish",
+    "shelfrock",
+    "sloperock",
+    "thorny",
+    "others"
+  ),
+  printfolder = "forSS",
+  output = NULL,
+  verbose = TRUE) {
 
-GetN.fn <- function(dir = NULL,
-                    dat,
-                    type = c("length", "age"),
-                    species = c(
-                      "all",
-                      "flatfish",
-                      "shelfrock",
-                      "sloperock",
-                      "thorny",
-                      "others"
-                    ),
-                    printfolder = "forSS",
-                    output = NULL,
-                    verbose = TRUE) {
   species <- match.arg(species)
   type <- match.arg(type)
   n.unq <- NA

R/GetSpp.fn.R

@@ -1,5 +1,6 @@
 #' Get Species Information
 #'
+#' @details
 #' Get the scientific name, common name, and strata group for
 #' a vector of species.
 #'
@@ -76,7 +77,7 @@ GetSpp.fn <- function(species, unident = FALSE) {
     c("coast", "stripetail_rockfish"),
     c("coast", "widow_rockfish"),
     c("coast", "yelloweye_rockfish"),
-    c("north_south", "yellowtail_rockfish")   
+    c("north_south", "yellowtail_rockfish")
   ))
   row.names(spplist) <- NULL
 

R/GetSppDefault.fn.R

@@ -1,5 +1,6 @@
 #' Get Vector of Default Species Names for US West Coast
 #'
+#' @details
 #' A standard list of common names for species of interest to the
 #' US West Coast. This list does not reflect ecosystem or financial
 #' importance, and instead it is strictly a list of species for which
@@ -11,7 +12,7 @@
 #' @examples
 #' GetSppDefault.fn()
 GetSppDefault.fn <- function() {
-  sp.list <- c(   
+  sp.list <- c(
     "arrowtooth_flounder",
     "aurora_rockfish",
     "big_skate",

R/GetStrata.fn.R

@@ -1,5 +1,6 @@
 #' Get Default Strata
 #'
+#' @details
 #' Get a data frame of strata for design-based estimates and survey
 #' composition data. Several strata are available for different default areas,
 #' as well as combinations using \code{"_"} in the argument \code{area}.
@@ -24,9 +25,11 @@
 #' to generate the strata returned by this function. Also, see
 #' convert_strata4vast function in the VASTWestCoast package that converts results
 #' from this function to strata that can be used within the VAST package.
+#'
 #' @author Chantel Wetzel and Kelli Faye Johnson
-
-GetStrata.fn <- function(area = "coast") {
+#'
+GetStrata.fn <- function(
+  area = "coast") {
 
   # development instructions ... find the numbers for each comment
   # (1) Add your area here in lower-case text

R/GetSurveyAbb.fn.R

@@ -1,5 +1,6 @@
 #' Get Survey Abbreviation
 #'
+#' @details
 #' Get abbreviations for a vector of survey names. The input vector of
 #' names, which are typically names used to pull the data from the
 #' warehouse, do not always match the name agreed upon within the

R/PlotMap.fn.R

@@ -5,7 +5,7 @@
 #'
 #'
 #' @template dir
-#' @param dat An object created by [PullCatch.fn()].
+#' @param dat An object created by [pull_catch()].
 #' @param main A string that will be prepended to the name of the saved png
 #'   (i.e., "NWFSC" results in a file called "NWFSC_CPUE_Map.png").
 #' @param dopng Deprecated with {nwfscSurvey} 2.1 because providing a non-NULL
@@ -35,11 +35,12 @@
 #' }
 #' @import ggplot2
 
-PlotMap.fn <- function(dir = NULL,
-                       dat,
-                       main = NULL,
-                       dopng = lifecycle::deprecated(),
-                       plot = 1:2) {
+PlotMap.fn <- function(
+  dir = NULL,
+  dat,
+  main = NULL,
+  dopng = lifecycle::deprecated(),
+  plot = 1:2) {
 
 
   if (lifecycle::is_present(dopng)) {
@@ -113,7 +114,7 @@ PlotMap.fn <- function(dir = NULL,
     print(g)
 
     if (!is.null(dir)) {
-       ggsave(filename = plot_names[1], width = 7, height = 10, units = 'in')     
+       ggsave(filename = plot_names[1], width = 7, height = 10, units = 'in')
     }
   }
 
@@ -135,7 +136,7 @@ PlotMap.fn <- function(dir = NULL,
           x = Longitude_dd, y = Latitude_dd,
           color = cpue_kg_km2, size = cpue_kg_km2
         ),
-        pch = 1, 
+        pch = 1,
         col = "lightgrey",
         alpha = 0.15
       ) +
@@ -168,7 +169,7 @@ PlotMap.fn <- function(dir = NULL,
     print(h)
 
     if (!is.null(dir)) {
-       ggsave(filename = plot_names[2], width = 7, height = 10, units = 'in')     
+       ggsave(filename = plot_names[2], width = 7, height = 10, units = 'in')
     }
   }
 }

R/PlotPresenceAbsence.fn.R

@@ -3,8 +3,8 @@
 #' This function was deprecated in {nwfsc} version 2.1. Please use
 #' [plot_proportion()] instead.
 #'
-#' @param data data.frame containing data per haul created by [PullCatch.fn()]
-#'   or biological data created by [PullBio.fn()] where the `dim = "sex"` must
+#' @param data Data frame containing data per haul created by [pull_catch()]
+#'   or biological data created by [pull_bio()] where the `dim = "sex"` must
 #'   be true for the latter.
 #' @param dim Dimension of interest, either "depth", "lat", or "sex".
 #' @template dir
@@ -50,19 +50,21 @@
 #' # Plot with package data
 #' PlotPresenceAbsence.fn(catch_nwfsc_combo)
 #' }
-PlotPresenceAbsence.fn <- function(data,
-                                   dim = c("depth", "lat", "sex"),
-                                   dir = NULL,
-                                   dopng = lifecycle::deprecated(),
-                                   plot_type = c("proportion", "total"),
-                                   depth_min = 50,
-                                   depth_max = NULL,
-                                   depth_bin_width = 25,
-                                   lat_min = 32,
-                                   lat_max = 49,
-                                   lat_bin_width = 1.0,
-                                   add_range_to_main = TRUE,
-                                   xlab = NULL) {
+PlotPresenceAbsence.fn <- function(
+  data,
+  dim = c("depth", "lat", "sex"),
+  dir = NULL,
+  dopng = lifecycle::deprecated(),
+  plot_type = c("proportion", "total"),
+  depth_min = 50,
+  depth_max = NULL,
+  depth_bin_width = 25,
+  lat_min = 32,
+  lat_max = 49,
+  lat_bin_width = 1.0,
+  add_range_to_main = TRUE,
+  xlab = NULL) {
+
   lifecycle::deprecate_soft(
     when = "2.1",
     what = "PlotPresenceAbsence.fn()",

R/PlotSexRatioStrata.fn.R

@@ -1,10 +1,11 @@
 #' Function to plot sex ratio by strata
 #'
-#' @param dir directory location for saving the png
-#' @param dat data object
-#' @param type length/age which data type to use
-#' @param strat.vars the parameters to stratify the data
-#' @param strat.df the created strata matrix with the calculated areas by the createStrataDF.fn function
+#' @template dir
+#' @param dat A data frame of length-composition data returned from
+#'   [pull_bio()].
+#' @param type Specify where to calculate the sex ration by length or age.
+#' @template strat.vars
+#' @template strat.df
 #' @param circleSize circle size
 #' @param dopng Deprecated with {nwfscSurvey} 2.1 because providing a non-NULL
 #'   value to `dir` can serve the same purpose as `dopng = TRUE` without the
@@ -16,7 +17,16 @@
 #' @export
 #' @seealso \code{\link{StrataFactors.fn}}
 
-PlotSexRatioStrata.fn <- function(dir = NULL, dat, type = "length", strat.vars = c("Depth_m", "Latitude_dd"), strat.df = NULL, circleSize = 0.05, dopng = lifecycle::deprecated(), ...) {
+PlotSexRatioStrata.fn <- function(
+  dir = NULL,
+  dat,
+  type = "length",
+  strat.vars = c("Depth_m", "Latitude_dd"),
+  strat.df = NULL,
+  circleSize = 0.05,
+  dopng = lifecycle::deprecated(),
+  ...) {
+
   if (lifecycle::is_present(dopng)) {
     lifecycle::deprecate_warn(
       when = "2.1",

R/PullBio.fn.R

@@ -44,13 +44,13 @@
 #' }
 #'
 PullBio.fn <- function(
-    Name = NULL,
-    SciName = NULL,
-    YearRange = c(1980, 5000),
-    SurveyName = NULL,
-    SaveFile = lifecycle::deprecated(),
-    Dir = NULL,
-    verbose = TRUE) {
+  Name = NULL,
+  SciName = NULL,
+  YearRange = c(1980, 5000),
+  SurveyName = NULL,
+  SaveFile = lifecycle::deprecated(),
+  Dir = NULL,
+  verbose = TRUE) {
 
   lifecycle::deprecate_soft(
     when = "2.3",