update/clean package documentation

.Rbuildignore

@@ -1,4 +1,3 @@
-^comland\.Rproj$
 ^\.Rproj\.user$
 ^data-raw$
 ^_pkgdown\.yml$
@@ -7,3 +6,5 @@
 ^\.github$
 ^other$
 ^output$
+comlandr.Rproj
+^.*\.Rproj$

DESCRIPTION

@@ -9,7 +9,7 @@ Authors@R: c(person(given = "Sean",
                    email = "andrew.beet@noaa.gov", 
                    role = c("cre","aut"),
                    comment = c(ORCID = "0000-0001-8270-7090")))
-Description: Pulls and processes commercial fishing data (US and NAFO)
+Description: Pulls and processes commercial fishing data (US and NAFO).
 URL: https://github.com/NOAA-EDAB/comlandr
 BugReports: https://github.com/NOAA-EDAB/comlandr/issues
 License: file LICENSE
@@ -34,8 +34,10 @@ Imports:
     data.table,
     sf,
     DBI,
-    odbc,
     magrittr,
+    dplyr,
+    stringr,
+    tibble,
     ggplot2,
     gtools,
     dbutils,

NAMESPACE

@@ -1,7 +1,5 @@
 # Generated by roxygen2: do not edit by hand
 
-export(adjust_inflation)
-export(disaggregate_skates_hakes)
 export(get_areas)
 export(get_comdisc_data)
 export(get_comdisc_raw_data)

news.md → NEWS.md

@@ -26,3 +26,4 @@ Added supporting `get` functions to pull information from supporting oracle tabl
 # comlandr 0.1.0
 
 Initial release 
+

R/adjust_inflation.R

@@ -1,7 +1,6 @@
 #' Adjust species value for inflation
 #'
 #'Reads in data from Bureau of Labor statistics website and adjusts species value
-#'
 #'What data is fetched?
 #'
 #'
@@ -12,22 +11,21 @@
 #'@return comland data frame adjusted for inflation
 #'
 #'@noRd
-#'@export
 
 
 
 
 adjust_inflation <- function(comland, refYear, refMonth){
-  
+
   call <- c(comland$call, dbutils::capture_function_call())
-  
+
   #Pulling data
   message("Adjusting for inflation ...")
-  
+
   #pull out comland data
   sql <- comland$sql
   comland <- comland$comland
-  
+
   #This isn't working right now - using downloaded file
   # temp <- tempfile()
   # download.file("http://download.bls.gov/pub/time.series/wp/wp.data.3.ProcessedFoods", temp)
@@ -39,7 +37,7 @@ adjust_inflation <- function(comland, refYear, refMonth){
   # deflate[, MONTH := as.numeric(substr(period, 2, 3))]
   # data.table::setnames(deflate, c('year', 'value'), c('YEAR', 'PPI'))
   # deflate <- deflate[, list(YEAR, MONTH, PPI)]
-  
+
   #Set yearly deflator to 0 instead of 13 to match unknown month designation
   deflate <- comlandr::deflate
   deflate[MONTH == 13, MONTH := 0]
@@ -50,8 +48,8 @@ adjust_inflation <- function(comland, refYear, refMonth){
 
   #Remove extra column
   comland[, PPI := NULL]
-  
-  return(list(comland      = comland[], 
+
+  return(list(comland      = comland[],
               sql          = sql,
               pullDate     = date(),
               functionCall = call))

R/aggregate_area.R

@@ -5,12 +5,10 @@
 #' proportions to more than two user defined areas from one stat area
 #'
 #'@param comland Data set generated by \code{get_comland_data}
-#'@param userAreas Data frame. Definitions to aggregate statistical areas to user defined
-#'                 areas
-#'@param areaDescription Character. Name of column in userAreas that defines the new
-#'                       area.
+#'@param userAreas Data frame. Definitions to aggregate statistical areas to user defined areas
+#'@param areaDescription Character. Name of column in userAreas that defines the new area.
 #'@param propDescription Character. Name of column in userAreas that defines the
-#'                       proportions of landings assigned to new area.
+#'proportions of landings assigned to new area.
 #'
 #'@noRd
 

R/calc_DK.R

@@ -11,8 +11,6 @@
 #' \item{areaDescription}{The name of the region (found in \code{areaPolygon})
 #'  that a record in \code{surveyData} is assigned to}
 #'
-#' @importFrom magrittr "%>%"
-#'
 #' @family comdisc
 #'
 #' Internal function

R/calc_discards.R

@@ -11,10 +11,6 @@
 #'
 #'@family comdisc
 #'
-#' @examples
-#' \dontrun{
-#' }
-#'
 #'
 #' Internal function
 #' @noRd

R/disaggregate_skates_hakes.R

@@ -3,15 +3,14 @@
 #'Determine proportion of little/winter skates and silver hake in landings data 7/13
 #'SML
 #'
+#'@inheritParams get_comland_data
 #'@param comland Data frame. Master data frame containing species landings
-#'@param skate.hake.us Data frame. Landings of skates and hakes in USA
 #'
 #'@return updated comland
 #'
 #'@importFrom data.table ":=" "key"
 #'
 #' @noRd
-#' @export
 
 disaggregate_skates_hakes <- function(comland, channel, filterByYear, filterByArea) {
 

R/get_areas.R

@@ -3,8 +3,7 @@
 #'Extract a list of statistical areas, region, NAFO codes, etc from the NEFSC "Area" supporting 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[dbutils]{connect_to_database}})
+#' @inheritParams get_comland_data
 #' @param areas a specific area code or set of codes. Either numeric or character vector. Defaults to "all" areas
 #' Numeric codes are converted to VARCHAR2(3 BYTE) when creating the sql statement. Character codes are short character strings to reference the AREANM field.
 #'

R/get_comdisc_data.R

@@ -5,7 +5,7 @@
 #'
 #'@inheritParams get_comland_data
 #'@param comland Data frame. Result of \code{get_comland_data}
-#'@param extendsTS Boolean. Should the DK (Discard to kept) ratio be extended and applied
+#'@param extendTS Boolean. Should the DK (Discard to kept) ratio be extended and applied
 #'to landings beyond observer coverage time period (Discards started in 1989). Default = T
 #'
 #'
@@ -25,10 +25,6 @@
 #'\item{SPPLIVLB}{live weight (landed = "n") or landed weight (landed="y") in lbs}
 #'\item{SPPVALUE}{The value of landed catch to the nearest dollar (U.S.), paid to fisherman by dealer, for a given species.}
 #'
-#'@section File Creation:
-#'
-#'A file containing the data.table above will also be saved to the users machine in the directory provided
-#'
 #'
 #'@importFrom data.table ":="
 #'@importFrom magrittr "%>%"
@@ -54,7 +50,7 @@ get_comdisc_data <- function(channel, comland,
   #Aggregate areas
   if(aggArea){
     userAreas <- comland$userAreas
-    comdisc.raw <- comlandr::aggregate_area(comdisc.raw, userAreas, areaDescription,
+    comdisc.raw <- aggregate_area(comdisc.raw, userAreas, areaDescription,
                                             propDescription, useForeign = F,
                                             applyPropValue = F)
   }
@@ -66,7 +62,7 @@ get_comdisc_data <- function(channel, comland,
   }
 
   #Calculate the discard to kept ratio
-  dk <- comlandr::calc_DK(comdisc.raw, areaDescription, fleetDescription)
+  dk <- calc_DK(comdisc.raw, areaDescription, fleetDescription)
 
   #Extend dk ratios beyond observer data
   if(extendTS){
@@ -94,7 +90,7 @@ get_comdisc_data <- function(channel, comland,
   }
 
   #Apply the discard to kept ratio
-  comdisc <- comlandr::calc_discards(comland, dk, areaDescription, fleetDescription)
+  comdisc <- calc_discards(comland, dk, areaDescription, fleetDescription)
 
   message("Some data may be CONFIDENTIAL ... DO NOT disseminate without proper Non-disclosure agreement.")
 

R/get_comdisc_raw_data.R

@@ -18,10 +18,6 @@
 #'\item{SPPLIVLB}{live weight (landed = "n") or landed weight (landed="y") in lbs}
 #'\item{SPPVALUE}{The value of landed catch to the nearest dollar (U.S.), paid to fisherman by dealer, for a given species.}
 #'
-#'@section File Creation:
-#'
-#'A file containing the data.table above will also be saved to the users machine in the directory provided
-#'
 #'@export
 
 get_comdisc_raw_data <- function(channel, filterByYear){
@@ -36,7 +32,7 @@ get_comdisc_raw_data <- function(channel, filterByYear){
   if(is.na(filterByYear[1])){
     years <- ">= 1989"
   }else{
-    years <- paste0("in (", comlandr:::sqltext(filterByYear), ")")
+    years <- paste0("in (", sqltext(filterByYear), ")")
   }
 
   ob.qry <- paste0("select year, month, area, negear, nespp4, hailwt, catdisp, drflag,

R/get_comland_data.R

@@ -1,51 +1,51 @@
-#' Extracts commercial data from Database
+#' Extracts and processes commercial data from Database
 #'
-#' Connects to cfdbs and pulls fields from WOLANDS, WODETS, CFDETS
+#' Connects to Population dynamics Database STOCKEFF to pull US landings data.
+#' Data is also pulled from NAFO (foreign landings) and the State of Maine (Herring).
+#' These sources of data are then aggregated, species value is adjusted to a user defined reference year,
+#' skate and hake landings (often reported as an unclassified category) are split based on bottom trawl survey,
+#' and missing values are imputed. For more information regarding these methods
+#' see \code{vignette("Overview", package = "comlandr")}
 #'
-#'@param channel an Object inherited from \code{ROracle}. This object is used to connect
+#'@param channel an Object inherited from \code{\link[ROracle]{Oracle}}. This object is used to connect
 #' to communicate with the database engine. (see \code{\link[dbutils]{connect_to_database}})
-#'@param filterByYear numeric vector
-#'@param filterByArea numeric vector
-#'@param useLanded boolean
-#'@param removeParts boolean
-#'@param useHerringMaine boolean
-#'@param useForeign boolean
-#'@param refYear numeric
-#'@param refMonth numeric
-#'@param disaggSkatesHakes boolean
-#'@param aggArea boolean
-#'@param userAreas data frame
-#'@param areaDescription character string
-#'@param propDescription character string
-#'@param applyPropLand boolean
-#'@param applyPropValue boolean
-#'@param aggGear boolean
-#'@param userGears data frame
-#'@param fleetDescription character string
-#'@param unkVar character vector
-#'@param knStrata character vector
+#'@param filterByYear numeric vector. Years to retrieve data for (Default = NA, pull all years)
+#'@param filterByArea numeric vector. Statistical Areas to retrieve data for (Default = NA, pull all areas)
+#'@param useLanded boolean. Default = T
+#'@param removeParts boolean. Remove species parts (Heads, wings, etc), Default = T
+#'@param useHerringMaine boolean. Pull data from Maine Herring database or use herring data in commercial landings database (Default = T)
+#'@param useForeign boolean. Pull foreign data from NAFO. Default = T
+#'@param refYear numeric. Reference year to use when adjusting species value
+#'@param refMonth numeric. Reference month to use when adjusting species value
+#'@param disagSkatesHakes boolean. Partition skates and hake unclassified landings into species (Default = T)
+#'@param aggArea boolean. Aggregate Statistical Areas into larger spatial units (Default = F)
+#'@param userAreas data frame. Spatial units in which Statistical areas should be aggregated (eg. \code{\link{mskeyAreas}})
+#'@param areaDescription character string. Field name in \code{userAreas} denoting spatial unit. (Default = "EPU")
+#'@param propDescription character string. Field name in \code{userAreas} denoting the scaling factor. (Default = "MeanProp")
+#'@param applyPropLand boolean. Apply the proportions in userAreas to the landings (Default = F)
+#'@param applyPropValue boolean. Apply the proportions in userAreas to the value (Default = F)
+#'@param aggGear boolean. Aggregate NEGEAR codes to larger "fleets" (Default = F)
+#'@param userGears data frame. Fleet designations in which NEGEAR codes should be grouped (eg.  \code{\link{mskeyGears}})
+#'@param fleetDescription character string. Field name in \code{userGears} denoting Fleet. (Default = "Fleet")
+#'@param unkVar character vector. Variables in the data, with have missing values, that you wish to assign a value to
+#'@param knStrata character vector. Variables in the data that you wish to use to use to assign values to \code{unkVar}
 #'
 #'@return Data frame (data.table) (n x 12)
 #'Each row of the data.table represents a species record for a given tow/trip
 #'
 #'\item{YEAR}{Year of trip/tow}
 #'\item{MONTH}{Month of trip/tow}
-#'\item{NEGEAR}{Fishing gear used on trip/tow}
+#'\item{NEGEAR/Fleet}{Fishing gear used on trip/tow or aggregated to Fleet}
 #'\item{TONCL2}{Tonnage class of the fishing vessel (2 digit value)}
 #'\item{NESPP3}{Species code (3 charachters)}
 #'\item{MARKET_CODE}{market code (2 characters)}
 #'\item{MESHCAT}{Code to describe the mesh size for a trawl vessel}
 #'\item{AREA/EPU}{Statistical area/ Ecological Production Unit in which species was reportly caught}
 #'\item{UTILCD}{Utilization code}
 #'\item{US}{Landing from the USA vessels or foreign vessels}
-#'\item{SPPLIVLB}{live weight (landed = "n") or landed weight (landed="y") in lbs}
+#'\item{SPPLIVMT}{Weight in metric tons.}
 #'\item{SPPVALUE}{The value of landed catch to the nearest dollar (U.S.), paid to fisherman by dealer, for a given species.}
 #'
-#'@section File Creation:
-#'
-#'A file containing the data.table above will also be saved to the users machine in the directory provided
-#'
-#'
 #'@importFrom data.table ":="
 #'@importFrom magrittr "%>%"
 #'
@@ -105,10 +105,10 @@ get_comland_data <- function(channel, filterByYear = NA,
 
 
   #Apply correction for inflation
-  if(!is.na(refYear)) comland <- comlandr::adjust_inflation(comland, refYear, refMonth)
+  if(!is.na(refYear)) comland <- adjust_inflation(comland, refYear, refMonth)
 
   #Disaggregate skates and hakes
-  if(disagSkatesHakes) comland <- comlandr::disaggregate_skates_hakes(comland,
+  if(disagSkatesHakes) comland <- disaggregate_skates_hakes(comland,
                                                                       channel,
                                                             filterByYear, filterByArea)
 

R/get_comland_raw_data.R

@@ -1,6 +1,7 @@
 #' Extracts commercial data from Database
 #'
-#' Connects to cfdbs and pulls fields from WOLANDS, WODETS, CFDETS
+#' Connects to Population dynamics Database STOCKEFF. This database contains the information
+#' from from WOLANDS, WODETS, CFDETS and CAMS.
 #'
 #'@inheritParams get_comland_data
 #'
@@ -10,18 +11,14 @@
 #'\item{YEAR}{Year of trip/tow}
 #'\item{MONTH}{Month of trip/tow}
 #'\item{NEGEAR}{Fishing gear used on trip/tow}
-#'\item{TONCL1}{Tonnage class of the fishing vessel}
+#'\item{TONCL2}{Two digit Tonnage class code of the fishing vessel}
 #'\item{NESPP3}{Species code (3 charachters)}
 #'\item{NESPP4}{Species code and market code (4 characters)}
 #'\item{AREA}{Statistical area in which species was reportly caught}
 #'\item{UTILCD}{Utilization code}
-#'\item{SPPLIVLB}{live weight (landed = "n") or landed weight (landed="y") in lbs}
+#'\item{SPPLIVMT}{live weight (landed = "n") or landed weight (landed="y") in lbs}
 #'\item{SPPVALUE}{The value of landed catch to the nearest dollar (U.S.), paid to fisherman by dealer, for a given species.}
 #'
-#'@section File Creation:
-#'
-#'A file containing the data.table above will also be saved to the users machine in the directory provided
-#'
 #'@export
 
 get_comland_raw_data <- function(channel, filterByYear = NA, filterByArea = NA,

R/get_foreign_data.R

@@ -1,6 +1,6 @@
 #' Downloads all NAFO data
 #'
-#'Downloads, imports, aggregates NAFO data
+#' Downloads, imports, aggregates NAFO data from 21B data base
 #'
 #' @param filterByYear Numeric vector. Years for which data is required
 #' @param filterByArea Character vector. NAFO Areas for which data is required
@@ -22,6 +22,9 @@
 #'
 #'@importFrom data.table ":=" "key" "setcolorder" "as.data.table"
 #'
+#'@seealso
+#' NAFO 21B website: \url{https://www.nafo.int/Data/Catch-Statistics-STATLANT-21B}
+#'
 #' @export
 
 get_foreign_data <- function(filterByYear=NA,filterByArea=NA,removeUSA = T, aggregateCountry = T){

R/get_gears.R

@@ -3,8 +3,7 @@
 #'Extract a list of gear types in the NEFSC "GEAR" supporting table
 #'
 #'
-#' @param channel DBI Object. Inherited from \link[DBI]{DBIConnection-class}. This object is used to connect
-#' to communicate with the database engine. (see \code{\link[dbutils]{connect_to_database}})
+#' @inheritParams get_comland_data
 #' @param gears specific gear code or set of codes. Either numeric or character vector. Defaults to "all" gears.
 #' Numeric codes are converted to VARCHAR2(2 BYTE) when creating the sql statement. Character codes are short character strings referencing GEARNM field.
 #'