Skip to content

Commit

Permalink
Merge pull request #75 from NOAA-EDAB/andy_package_doc
Browse files Browse the repository at this point in the history
update/clean package documentation
  • Loading branch information
sgaichas authored Sep 25, 2024
2 parents 54fe90b + b5e292e commit 7890eec
Show file tree
Hide file tree
Showing 59 changed files with 262 additions and 2,811 deletions.
3 changes: 2 additions & 1 deletion .Rbuildignore
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
^comland\.Rproj$
^\.Rproj\.user$
^data-raw$
^_pkgdown\.yml$
Expand All @@ -7,3 +6,5 @@
^\.github$
^other$
^output$
comlandr.Rproj
^.*\.Rproj$
6 changes: 4 additions & 2 deletions DESCRIPTION
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Authors@R: c(person(given = "Sean",
email = "[email protected]",
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
Expand All @@ -34,8 +34,10 @@ Imports:
data.table,
sf,
DBI,
odbc,
magrittr,
dplyr,
stringr,
tibble,
ggplot2,
gtools,
dbutils,
Expand Down
2 changes: 0 additions & 2 deletions NAMESPACE
Original file line number Diff line number Diff line change
@@ -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)
Expand Down
1 change: 1 addition & 0 deletions news.md → NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,4 @@ Added supporting `get` functions to pull information from supporting oracle tabl
# comlandr 0.1.0

Initial release

16 changes: 7 additions & 9 deletions R/adjust_inflation.R
Original file line number Diff line number Diff line change
@@ -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?
#'
#'
Expand All @@ -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)
Expand All @@ -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]
Expand All @@ -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))
Expand Down
8 changes: 3 additions & 5 deletions R/aggregate_area.R
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 0 additions & 2 deletions R/calc_DK.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 0 additions & 4 deletions R/calc_discards.R
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,6 @@
#'
#'@family comdisc
#'
#' @examples
#' \dontrun{
#' }
#'
#'
#' Internal function
#' @noRd
Expand Down
3 changes: 1 addition & 2 deletions R/disaggregate_skates_hakes.R
Original file line number Diff line number Diff line change
Expand Up @@ -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) {

Expand Down
3 changes: 1 addition & 2 deletions R/get_areas.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.
#'
Expand Down
12 changes: 4 additions & 8 deletions R/get_comdisc_data.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
#'
#'
Expand All @@ -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 "%>%"
Expand All @@ -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)
}
Expand All @@ -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){
Expand Down Expand Up @@ -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.")

Expand Down
6 changes: 1 addition & 5 deletions R/get_comdisc_raw_data.R
Original file line number Diff line number Diff line change
Expand Up @@ -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){
Expand All @@ -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,
Expand Down
64 changes: 32 additions & 32 deletions R/get_comland_data.R
Original file line number Diff line number Diff line change
@@ -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 "%>%"
#'
Expand Down Expand Up @@ -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)

Expand Down
11 changes: 4 additions & 7 deletions R/get_comland_raw_data.R
Original file line number Diff line number Diff line change
@@ -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
#'
Expand All @@ -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,
Expand Down
5 changes: 4 additions & 1 deletion R/get_foreign_data.R
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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){
Expand Down
3 changes: 1 addition & 2 deletions R/get_gears.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.
#'
Expand Down
Loading

0 comments on commit 7890eec

Please sign in to comment.