Merge pull request #68 from NOAA-EDAB/andy_documentation

Update some documentation
NOAA-EDAB · Jun 11, 2024 · 05039dd · 05039dd
2 parents f9e29d3 + 36939ad
commit 05039dd
Show file tree

Hide file tree

Showing 43 changed files with 300 additions and 369 deletions.
diff --git a/.gitignore b/.gitignore
@@ -9,3 +9,4 @@ inst/doc
 #folder
 testing
 docs
+other
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -35,5 +35,6 @@ RoxygenNote: 7.3.1
 Suggests: 
     knitr,
     rmarkdown,
-    markdown
+    markdown,
+    kableExtra
 VignetteBuilder: knitr
diff --git a/NAMESPACE b/NAMESPACE
@@ -18,10 +18,6 @@ export(get_survdat_scallop_data)
 export(get_vessel)
 export(plot_data_area)
 export(plot_shapefile)
-export(post_strat)
-export(strat_mean)
-export(strat_prep)
-export(swept_area)
 importFrom(data.table,"%like%")
 importFrom(data.table,"key")
 importFrom(magrittr,"%>%")
diff --git a/NEWS.md b/NEWS.md
@@ -0,0 +1,6 @@
+# survdat 1.0
+
+Benchmark release
+
+
+
diff --git a/R/apply_conversion_factors.r b/R/apply_conversion_factors.r
@@ -17,6 +17,7 @@
 #' This is an internal function.
 #' To pull the values of the conversion factors use \code{\link{get_conversion_factors}}
 #'
+#'@noRd
 
 
 
@@ -30,10 +31,9 @@ apply_conversion_factors <- function(channel,survdat.raw,use.SAD = F) {
   survdat[, ABUNDANCE := as.double(ABUNDANCE)]
 
   #Grab all conversion factors off the network
-  convert.qry <- "select *
-    from svdbs.survan_conversion_factors"
-
-  convert <- data.table::as.data.table(DBI::dbGetQuery(channel, convert.qry))
+  conversionFactors <- get_conversion_factors(channel)
+  convert.qry <- conversionFactors$sql
+  convert <- data.table::as.data.table(conversionFactors$data)
 
   #DCF < 1985 Door Conversion
   dcf.spp <- convert[DCF_WT > 0, SVSPP]

diff --git a/R/calc_stratified_mean.R b/R/calc_stratified_mean.R
@@ -2,8 +2,20 @@
 #'
 #' Calculates the stratified mean. Details of method found here ...
 #'
-#' @inheritParams strat_prep
-#' @inheritParams strat_mean
+#' @param surveyData Data table. NEFSC survey data generated by \code{get_survdat_data.R}
+#' @param areaPolygon sf object or character string. Default = "NEFSC strata". The default option uses the survey strata shapefile bundled with the package.
+#' To use any other shapefile for stratification, the shapefile must be read in as an \link[sf]{sf} object and the \code{areaDescription} argument must be specified.
+#' @param areaDescription Character String. Column name from \code{areaPolygon}
+#'                       that contains the strata designations.
+#' @param filterByArea Numeric vector. Set of areas to subset from the
+#'  \code{areaDescription} of the \code{areaPolygon}.
+#' @param filterBySeason Character string. Which seasons of the \code{surveyData}
+#'  should be included.  Choices include "SPRING", "FALL", or "all".
+#' @param groupDescription Character string. Column of \code{prepData} which
+#'  contains the groups (e.g. "SVSPP") on which the means are based.
+#' @param filterByGroup Character or numeric vector. Set of groups to subset from
+#'  \code{groupDescription}.  The default "all" will calculate means for all groups.
+#' @param mergesexFlag Boolean. Logical value to merge sexed species such as dogfish.
 #' @param tidy Boolean. Return output in long format (Default = F).
 #' @param returnPrepData Boolean. Return both \code{stratmeanData} and \code{prepData}
 #'   as a list object. The default (F) returns only the \code{stratmeanData} as a
@@ -58,15 +70,15 @@ calc_stratified_mean <- function(surveyData, areaPolygon = 'NEFSC strata',
 
   #Run stratification prep
   message("Prepping data ...")
-  prepData <- survdat::strat_prep(surveyData, areaPolygon, areaDescription,
+  prepData <- survdat:::strat_prep(surveyData, areaPolygon, areaDescription,
                                   filterByArea, filterBySeason)
 
   #Calculate stratified mean
   message("Calculating Stratified Mean  ...")
   #Check if calculating mean base on all station or by season
   if(filterBySeason[1] == "all"){seasonFlag <- F}else{seasonFlag <- T}
 
-  stratmeanData <- survdat::strat_mean(prepData, groupDescription, filterByGroup,
+  stratmeanData <- survdat:::strat_mean(prepData, groupDescription, filterByGroup,
                                        mergesexFlag, seasonFlag = seasonFlag,
                                        areaDescription, poststratFlag)
 

diff --git a/R/calc_swept_area.R b/R/calc_swept_area.R
@@ -44,7 +44,7 @@ calc_swept_area <- function(surveyData, areaPolygon = 'NEFSC strata',
 
     #Calculate total biomass/abundance estimates
     message("Calculating Swept Area Estimate  ...")
-    sweptareaData <- survdat::swept_area(prepData = stratmeanData$prepData,
+    sweptareaData <- survdat:::swept_area(prepData = stratmeanData$prepData,
                                          stratmeanData = stratmeanData$stratmeanData,
                                          q = q, areaDescription = areaDescription,
                                          groupDescription = groupDescription)

diff --git a/R/get_conversion_factors.R b/R/get_conversion_factors.R
@@ -33,7 +33,7 @@
 get_conversion_factors <- function(channel){
 
   # creates the sql based on user input
-  sqlStatement <-   convert.qry <- "select * from SURVAN_CONVERSION_FACTORS"
+  sqlStatement <-   convert.qry <- "select * from SVDBS.SURVAN_CONVERSION_FACTORS"
 
   query <- DBI::dbGetQuery(channel,sqlStatement)
 

diff --git a/R/get_length_weight.R b/R/get_length_weight.R
@@ -1,6 +1,7 @@
-#'Generate a table of length weight coefficients
+#' Extract species specific LENGTH-WEIGHT COEFFICIENTS from SVDBS
 #'
-#'Pulls the length-weight coefficients calculated from NOAA Tech Memo NMFS-NE-171.
+#'Pulls the length-weight coefficients from SVDBS LENGTH_WEIGHT_COEFFICIENTS table
+#' These coefficients are described in NOAA Tech Memo NMFS-NE-171.
 #'
 #'
 #' @inheritParams get_survdat_data
@@ -11,7 +12,7 @@
 #'\item{SVLWEXP}{The exponent of the length-weight equation, b.}
 #'\item{SVLWCOEFF}{The natural log of the coefficient of the length-weight equation, ln a.}
 #'
-#'@family survdat
+#'@family helper
 #'
 #'@export
 

diff --git a/R/get_survdat_data.R b/R/get_survdat_data.R
@@ -1,23 +1,28 @@
-#' Extracts Survey data  from Database
+#' Extracts Survey data from Database
 #'
-#'Connects to svdbs and pulls data from MSTR_CRUISE, UNION_FSCS_SVCAT, UNION_FSCS_SVLEN, UNION_FSCS_SVSTA, UNION_FSCS_SVBIO
+#' Connects to svdbs and pulls data from MSTR_CRUISE, UNION_FSCS_SVCAT,
+#' UNION_FSCS_SVLEN, UNION_FSCS_SVSTA, UNION_FSCS_SVBIO
 #'
-#' @param channel an Object inherited from \link[DBI]{DBIConnection-class}. This object is used to communicate with the database engine. (see \code{\link[dbutils]{connect_to_database}})
+#' @param channel an Object inherited from \link[DBI]{DBIConnection-class}.
+#'      This object is used to communicate with the database engine.
+#'       (see \code{\link[dbutils]{connect_to_database}})
 #' @param filterByYear Numeric vector. Subset of years from which to pull data.
 #'                     If not specified then all years are pulled. (Default = NA)
 #' @param all.season Boolean. Spring and Fall only (F) otherwise T. (Default = F)
 #' @param shg.check Boolean. use only SHG <=136 or TOGA <= 1324 (>2008). (Default = T)
 #' @param conversion.factor Boolean. Whether to apply conversion factors to the data pull, (Default = T)
 #' @param use.SAD Boolean. Use Survey Analysis Database (SAD) for assessed species. (Default = F)
-#' @param getBio Boolean. Include biology data for each fish weight, sex,, stomach weight, stomach volume, age, maturity
+#' @param getBio Boolean. Include biology data for each fish weight, sex,
+#' stomach weight, stomach volume, age, maturity
 #' @param getLengths Boolean. Include length data which includes the length in
 #'                   cm and the number at length. (Default = T)
 #' @param getWeightLength Boolean. Include the weight at length by applying length
 #'                        weight coefficients from SVDBS. (Default = F)
 #'
-#' @return A list containing a Data frame (data.table) (n x 21), a list of SQL queries used to pull the data,
-#' the date of the pull, and the call expression
-#' Each row of the data.table represents the number at length of a species on a specific tow along with physical attributes of the tow.
+#' @return A list containing a Data frame (data.table) (n x 21),
+#' a list of SQL queries used to pull the data, the date of the pull,
+#' and the call expression. Each row of the data.table represents the number
+#' at length of a species on a specific tow along with physical attributes of the tow.
 #'
 #' The data frame (Descriptions taken from NEFSC Data dictionary)
 #'
@@ -65,15 +70,14 @@
 #'
 #' The date:
 #'
-#'  \item{pullDate}{The date the data was pulled from the database}
+#' \item{pullDate}{The date the data was pulled from the database}
 #'
 #' The expression:
 #'
-#' \item{functionCall}{The call used to create the data pul}
+#' \item{functionCall}{The call used to create the data pull}
 #'
 #' @importFrom data.table "%like%"
-#'
-#'@family survdat
+#' @family survdat
 #'
 #'@examples
 #'\dontrun{
@@ -89,11 +93,14 @@
 #'
 #'@export
 
+
 get_survdat_data <- function(channel, filterByYear = NA, all.season = F,
                              shg.check = T, conversion.factor = T, use.SAD = F,
                              getBio = F, getLengths = T, getWeightLength = F) {
 
   call <- capture_function_call()
+  version <- packageVersion("survdat")
+
 
   # Cruise List --------------------------------------------------------------
   #Generate cruise list
@@ -288,6 +295,6 @@ get_survdat_data <- function(channel, filterByYear = NA, all.season = F,
 
 
 
-  return(list(survdat=survdat,sql=sql,pullDate=date(),functionCall = call))
+  return(list(survdat=survdat,sql=sql,pullDate=date(),functionCall = call,version=version))
 
 }
diff --git a/R/get_survdat_scallop_data.R b/R/get_survdat_scallop_data.R
@@ -6,8 +6,6 @@
 #' @param filterByYear Numeric vector. Subset of years from which to pull data.
 #'                     If not specified then all years are pulled. (Default = NA)
 #' @param shg.check Boolean. use only SHG <=136 or TOGA <= 1324 (>2008). (Default = T)
-#' @param conversion.factor Boolean. Whether to apply conversion factors to the data pull, (Default = T)
-#' @param getBio Boolean. Include biology data for each fish weight, sex,, stomach weight, stomach volume, age, maturity
 #' @param getLengths Boolean. Include length data which includes the length in
 #'                   cm and the number at length. (Default = T)
 #' @param getWeightLength Boolean. Include the weight at length by applying length
@@ -88,8 +86,12 @@
 #'
 #'@export
 
-get_survdat_scallop_data <- function(channel, filterByYear = NA, shg.check = T,
-                             getLengths = T, getWeightLength = F, scallopOnly = T){
+get_survdat_scallop_data <- function(channel,
+                                     filterByYear = NA,
+                                     shg.check = T,
+                                     getLengths = T,
+                                     getWeightLength = F,
+                                     scallopOnly = T){
 
   call <- capture_function_call()
 

diff --git a/R/post_strat.R b/R/post_strat.R
@@ -17,7 +17,7 @@
 #'
 #'@family survdat
 #'
-#' @export
+#' @noRd
 
 
 post_strat <- function (surveyData, areaPolygon, areaDescription, na.keep = F) {

diff --git a/R/strat_mean.R b/R/strat_mean.R
@@ -23,14 +23,14 @@
 #'
 #' @importFrom data.table "key"
 #'
-#'@family survdat
+#'@family surdat
 #'
 #'@examples
 #'\dontrun{
 #' # Called internally
 #'}
 #'
-#' @export
+#' @noRd
 
 
 strat_mean <- function (prepData, groupDescription = "SVSPP", filterByGroup = "all",
@@ -44,7 +44,7 @@ strat_mean <- function (prepData, groupDescription = "SVSPP", filterByGroup = "a
     stratmeanData <- unique(stratmeanData, by = key(stratmeanData))
     stratmeanData[, c('LENGTH', 'NUMLEN') := NULL]
   }
-  
+
   data.table::setnames(stratmeanData, c(groupDescription, areaDescription),
                        c('group', 'strat'))
 
@@ -145,9 +145,9 @@ strat_mean <- function (prepData, groupDescription = "SVSPP", filterByGroup = "a
     stratmeanData[, glen := NULL]
     data.table::setkey(stratmeanData, YEAR, SVSPP, CATCHSEX)
   }
-  
+
   if(seasonFlag == F) stratmeanData[, SEASON := 'ALL']
-  
+
   data.table::setnames(stratmeanData, 'group', groupDescription)
 
   return(stratmeanData[])

diff --git a/R/strat_prep.R b/R/strat_prep.R
@@ -26,7 +26,7 @@
 #' # Called internally
 #' }
 #'
-#' @export
+#' @noRd
 
 
 strat_prep <- function (surveyData, areaPolygon = "NEFSC strata",
@@ -53,7 +53,7 @@ strat_prep <- function (surveyData, areaPolygon = "NEFSC strata",
   # post stratify if necessary
   if(poststratFlag){
     message("Post stratifying ...")
-    surveyData <- survdat::post_strat(surveyData, areaPolygon, areaDescription)
+    surveyData <- survdat:::post_strat(surveyData, areaPolygon, areaDescription)
   } else {
     #Add extra column to original data to mimic what happens when post-stratifying
     surveyData <- surveyData[, areaDescription := STRATUM]

diff --git a/R/swept_area.R b/R/swept_area.R
@@ -29,7 +29,7 @@
 #'# Called internally
 #'}
 #'
-#'@export
+#'@noRd
 
 
 swept_area <- function (prepData, stratmeanData, q = NULL, a = 0.0384,

diff --git a/man/apply_conversion_factors.Rd b/man/apply_conversion_factors.Rd
diff --git a/man/calc_stratified_mean.Rd b/man/calc_stratified_mean.Rd
diff --git a/man/calc_swept_area.Rd b/man/calc_swept_area.Rd
diff --git a/man/get_area.Rd b/man/get_area.Rd
diff --git a/man/get_conversion_factors.Rd b/man/get_conversion_factors.Rd
diff --git a/man/get_cruise_purpose.Rd b/man/get_cruise_purpose.Rd