Merge pull request #74 from NOAA-EDAB/dev

Cleaned up documentation + added function

DESCRIPTION

@@ -6,11 +6,11 @@ Date: 2015-03-03
 Authors@R: c(person(given = "Sean",
                     family = "Lucey",
                     email = "[email protected]",
-                    role = c("aut", "cre")),
+                    role = c("aut")),
             person(given = "Andy", 
                    family = "Beet", 
                    email = "[email protected]",
-                   role = c("aut"),
+                   role = c("aut","cre"),
                    comment = c(ORCID = "0000-0001-8270-7090")))
 License: file LICENSE
 Encoding: UTF-8
@@ -36,5 +36,9 @@ Suggests:
     knitr,
     rmarkdown,
     markdown,
-    kableExtra
+    kableExtra,
+    DT
 VignetteBuilder: knitr
+Depends: 
+    R (>= 2.10)
+LazyData: true

R/check_argument_validation.R

@@ -0,0 +1,27 @@
+#' Argument Flag check
+#'
+#' check to make sure arguments passed do not contradict each other
+#' @inheritParams get_survdat_data
+#'
+#' @noRd
+
+# We can either create error messages (like below) or fix argument specs
+check_argument_validation <- function(getLengths,getBio,getWeightLength) {
+
+  if (getWeightLength) {
+    if(!getLengths) {
+      # Weight at Length Data -----------------------------------------------------
+      stop("Can not calculate weight at length without lengths...
+           Set getLengths = TRUE.")
+    }
+  }
+
+  if (getBio) {
+    if(!getLengths) {
+      stop("Can not obtain individual fish biological data without lengths ...
+           Set getLengths = TRUE")
+    }
+  }
+
+
+}

R/data_sampleBio.r

@@ -0,0 +1,11 @@
+#' Sample data pull with spcies specific biological data
+#'
+#' get_survdat_data(channel, getLengths = T, getWeightLength = F, conversion.factor = F, getBio = T)
+#'
+#' @format A data frame with n rows and m variables
+#'
+#' @family sampleData
+#'
+#'
+#'
+"sampleBio"

R/data_sampleLengthWeight.r

@@ -0,0 +1,11 @@
+#' Sample data pull with species lengths and predicted weights
+#'
+#' get_survdat_data(channel, getLengths=F, getWeightLength = T, conversion.factor=F)
+#'
+#' @format A data frame with n rows and m variables
+#'
+#' @family sampleData
+#'
+#'
+#'
+"sampleLengthWeight"

R/data_sampleLengths.r

@@ -0,0 +1,11 @@
+#' Sample data pull with species lengths
+#'
+#' get_survdat_data(channel, getLengths=T, conversion.factor=F)
+#'
+#' @format A data frame with n rows and m variables
+#'
+#' @family sampleData
+#'
+#'
+#'
+"sampleLengths"

R/data_sampleRaw.r

@@ -0,0 +1,11 @@
+#' Sample raw data pull
+#'
+#' get_survdat_data(channel, getLengths=F,conversion.factor=F)
+#'
+#' @format A data frame with n rows and m variables
+#'
+#' @family sampleData
+#'
+#'
+#'
+"sampleRaw"

R/data_sampleRawWithConversion.r

@@ -0,0 +1,11 @@
+#' Sample raw data pull with conversion factors applied
+#'
+#' get_survdat_data(channel, getLengths = F, conversion.factor = T)
+#'
+#' @format A data frame with n rows and m variables
+#'
+#' @family sampleData
+#'
+#'
+#'
+"sampleRawWithConversion"

R/get_length_weight.R

@@ -1,6 +1,6 @@
 #' Extract species specific LENGTH-WEIGHT COEFFICIENTS from SVDBS
 #'
-#'Pulls the length-weight coefficients from SVDBS LENGTH_WEIGHT_COEFFICIENTS table
+#'Pulls the length-weight coefficients from SVDBS.LENGTH_WEIGHT_COEFFICIENTS table
 #' These coefficients are described in NOAA Tech Memo NMFS-NE-171.
 #'
 #'

R/get_length_weight_data.R

@@ -38,15 +38,15 @@
 #'
 #'@section Reference:
 #'
-#' Note: species codes (svspp) are stored in the database as VARCHAR2(3 BYTE)
+#' Note: species codes (SVSPP) are stored in the database as VARCHAR2(3 BYTE)
 #'
 #' @seealso \code{\link[dbutils]{connect_to_database}}
 #'
 #' @examples
 #' \dontrun{
 #' # extracts length-weight data for cod (73) for all years and sexes
 #' channel <- connect_to_database(server="servername",uid="username")
-#' codPull <- get_length_weight_data(channel,species=73)
+#' codPull <- get_length_weight_data(channel,year = "all", species=73)
 #'}
 #'
 #' @export
@@ -86,7 +86,6 @@ get_length_weight_data <- function(channel, year=1994, species="all", sex="all")
     whereStr <- paste(whereStr,item,"and")
   }
 
-  print(whereStr)
   # eventually user will be able to pass these variables
   sqlStatement <- "select m.cruise6, m.stratum, m.tow, m.station, m.svspp, m.sex, m.indid, m.length, m.indwt, m.maturity, m.stom_wgt, m.stom_volume, s.season
                     from svdbs.union_fscs_svbio m LEFT JOIN svdbs.svdbs_cruises s

R/get_sex.R

@@ -1,6 +1,6 @@
 #' Extract SEX information from SVDBS
 #'
-#'Extract a list of sex codes and descriptions from the SVDBS SEX_CODES table
+#'Extract a list of sex codes and descriptions from the SVDBS.SEX_CODES table
 #'
 #'
 #' @param channel an Object inherited from \link[DBI]{DBIConnection-class}. This object is used to connect

R/get_sex_fscs.R

@@ -1,6 +1,6 @@
 #' Extract SEX information from SVDBS
 #'
-#'Extract a list of sex codes and descriptions from the SVDBS FSCS_SEX_CODES table
+#'Extract a list of sex codes and descriptions from the SVDBS.FSCS_SEX_CODES table
 #'
 #'
 #' @param channel an Object inherited from \link[DBI]{DBIConnection-class}. This object is used to connect

R/get_species.R

@@ -5,7 +5,7 @@
 #'
 #' @param channel an Object inherited from \link[DBI]{DBIConnection-class}. This object is used to connect
 #' to communicate with the database engine. (see \code{\link{connect_to_database}})
-#' @param species Numeric or character vector. a specific species code or set of codes. Defaults to "all" species.
+#' @param species Numeric or character vector. A specific species code or set of codes. Default = "all".
 #' Numeric codes are converted to VARCHAR2(3 BYTE) when creating the sql statement. Character codes are short character strings.
 #'
 #' @return A list is returned:
@@ -16,7 +16,6 @@
 #'
 #'   \item{colNames}{a vector of the table's column names}
 #'
-#'The default sql statement "\code{select * from svdbs.svspecies_list}" is used
 #'
 #'@section Reference:
 #'Use the data dictionary for field name explanations

R/get_strata.R

@@ -1,11 +1,10 @@
 #' Extract STRATA information from SVDBS
 #'
-#'Extract STRATA information from the SVDBS SVMSTRATA table
-#'
+#'Extract STRATA information from the SVDBS.SVMSTRATA table
 #'
 #' @param channel an Object inherited from \link[DBI]{DBIConnection-class}. This object is used to connect
 #' to communicate with the database engine. (see \code{\link{connect_to_database}})
-#' @param strata Numeric or character vector. Set of strata codes. Defaults to "all" strata.
+#' @param strata Numeric or character vector. Set of strata codes. Default = "all".
 #' Numeric codes are converted to VARCHAR2(5 BYTE) when creating the sql statement. Alternatively enter name of stratum
 #'
 #' @return A list is returned:
@@ -16,7 +15,6 @@
 #'
 #'   \item{colNames}{a vector of the table's column names}
 #'
-#'The default sql statement "\code{select * from svdbs.svspecies_list}" is used
 #'
 #'@section Reference:
 #'Use the data dictionary for field name explanations

R/get_survdat_data.R

@@ -45,9 +45,17 @@
 #' \item{BOTSALIN}{Bottom salinity in Practical Salinity Units (PSU).}
 #' \item{ABUNDANCE}{Expanded number of individuals of a species caught at a given station.(EXPCATCHNUM)}
 #' \item{BIOMASS}{Expanded catch weight of a species caught at a given station. (EXPCATCHWT)}
+#'
+#' Additional Columns if getLengths = T (UNION_FSCS_SVLEN)
+#'
 #' \item{LENGTH}{Measured length of species in centimeters (cm). Measure method differs by species.}
 #' \item{NUMLEN}{Expanded number of specimens at a given length.(EXPNUMLEN)}
 #'
+#' Additional Columns if getWeightLength = T
+#'
+#' \item{PREDWT}{Predicted weight given length based on length-weight coefficients.}
+#' \item{WGTLEN}{Predicted total weight given number of fish observed at given length}
+#'
 #' Additional columns if bio = T (UNION_FSCS_SVBIO)
 #'
 #' \item{INDID}{A unique identifier for each fish sampled.}
@@ -76,6 +84,10 @@
 #'
 #' \item{functionCall}{The call used to create the data pull}
 #'
+#' The version:
+#'
+#' \item{version}{The version of survdat used to pull the data}
+#'
 #' @importFrom data.table "%like%"
 #' @family survdat
 #'
@@ -101,6 +113,9 @@ get_survdat_data <- function(channel, filterByYear = NA, all.season = F,
   call <- capture_function_call()
   version <- packageVersion("survdat")
 
+  check_argument_validation(getBio = getBio,
+                            getLengths = getLengths,
+                            getWeightLength = getWeightLength)
 
   # Cruise List --------------------------------------------------------------
   #Generate cruise list
@@ -211,11 +226,7 @@ get_survdat_data <- function(channel, filterByYear = NA, all.season = F,
 
   }
 
-  # Weight at Length Data -----------------------------------------------------
-  if(getWeightLength & getLengths == F){
-    stop("Can not calculate weight at length without lengths...
-         Set getLengths to TRUE.")
-  }
+
   if(getWeightLength){
     message("Getting Weight at Length Data ...")
     #Grab survey length/weight coefficients using survdat function

README.md

@@ -1,29 +1,43 @@
 # survdat <img src="man/figures/logo.png" align="right" width="120" /> 
 
-### Everything you need to pull and process the NEFSC survey data
+## Pull and process the NEFSC survey data
 
 <!-- badges: start -->
 [![gh-pages](https://github.com/NOAA-EDAB/survdat/workflows/gh-pages/badge.svg)](https://github.com/NOAA-EDAB/survdat/actions)
 [![R-CMD-check](https://github.com/NOAA-EDAB/survdat/actions/workflows/check-standard.yaml/badge.svg)](https://github.com/NOAA-EDAB/survdat/actions/workflows/check-standard.yaml) [![gitleaks](https://github.com/NOAA-EDAB/survdat/workflows/gitleaks/badge.svg)](https://github.com/NOAA-EDAB/survdat/actions)
 <!-- badges: end -->
-
 ---
 
-
 ## Usage
 
 To use this package you will need:
 
 1.  To be behind the NEFSC firewall
 2.  Permissions to access the required server : a username and password.
 3.  Oracle's instant Client installed
+4.  Oracle's ROracle R package
+
+### Who this is for?
+
+* Anyone looking for raw tow level survey data in the format that you would obtain from Ecosystem Survey Branch (ESB) - still in development
+
+* Anyone looking for Ecosystem/multispecies products derived from the tow level data. See [vignettes](articles/articles/pullingData.html) for explanation of methods
+
+### Who this isn't for!
 
+Anyone looking for survey data that is directly input into stock assessments. You will need to either:
 
+* Contact the appropriate stock assessment scientist 
+* Visit the [Northeast Region Stock Assessment Support Materials](https://www.fisheries.noaa.gov/resource/data/northeast-region-stock-assessment-support-materials)
+* Visit [StockSMART web portal](https://apps-st.fisheries.noaa.gov/stocksmart?app=homepage) or [stocksmart](https://noaa-edab.github.io/stocksmart/) R package housing the data from the portal
 
-### Installation
 
-`remotes::install_github("NOAA-EDAB/survdat",build_vignettes = TRUE)`
+## Installation
 
+``` r 
+# Install directly from GitHub
+remotes::install_github("NOAA-EDAB/survdat",build_vignettes = TRUE)`
+```
 ## Developers (in alphabetical order)
 
 | [andybeet](https://github.com/andybeet)                                                         | [slucey](https://github.com/slucey)                                                                                                    |

data-raw/create_sample_data.R

@@ -0,0 +1,71 @@
+#' Create sample data fro vignettes
+#'
+#'
+#'
+
+channel <- dbutils::connect_to_database("server","user")
+# pull raw data
+raw <- survdat::get_survdat_data(channel,
+                          getLengths = F,
+                          conversion.factor = F)
+
+# pull lengths
+len <- survdat::get_survdat_data(channel,
+                          getLengths = T,
+                          conversion.factor = F)
+# pull lengths with predicted weights
+lenwgt <- survdat::get_survdat_data(channel,
+                          getLengths = T,
+                          getWeightLength = T,
+                          conversion.factor = F)
+# Pull bio data
+bio <- survdat::get_survdat_data(channel,
+                          getLengths = T,
+                          getWeightLength = F,
+                          conversion.factor = F,
+                          getBio = T)
+
+# Pull raw data with conversion factors
+rawfact <- survdat::get_survdat_data(channel,
+                                 getLengths = F,
+                                 conversion.factor = T)
+
+overwrite <- F
+set.seed(143)
+rowsToSample <- sample(1:nrow(raw$survdat),20)
+
+# Generate sample data
+# raw
+sampleRaw <- raw$survdat |>
+  dplyr::slice(rowsToSample) |>
+  dplyr::as_tibble()
+
+usethis::use_data(sampleRaw,overwrite = overwrite)
+
+#lengths
+sampleLengths <- len$survdat |>
+  dplyr::slice(rowsToSample) |>
+  dplyr::as_tibble()
+
+usethis::use_data(sampleLengths,overwrite = overwrite)
+
+# lengthweight
+sampleLengthWeight <- lenwgt$survdat |>
+  dplyr::slice(rowsToSample) |>
+  dplyr::as_tibble()
+
+usethis::use_data(sampleLengthWeight,overwrite = overwrite)
+
+# BiologicalData
+sampleBio <- bio$survdat |>
+  dplyr::slice(rowsToSample) |>
+  dplyr::as_tibble()
+
+usethis::use_data(sampleBio,overwrite = overwrite)
+
+# raw with conversion factor
+sampleRawWithConversion <- rawfact$survdat |>
+  dplyr::slice(rowsToSample) |>
+  dplyr::as_tibble()
+
+usethis::use_data(sampleRawWithConversion,overwrite = overwrite)