From 2253be32894edb29771ca4435de46d2b0dcb9d21 Mon Sep 17 00:00:00 2001 From: sean-rohan-NOAA Date: Fri, 24 Nov 2023 15:42:33 -0800 Subject: [PATCH] Minor changes to function documentation --- DESCRIPTION | 2 +- R/make_idw_map.R | 6 ++++-- R/make_idw_stack.R | 4 +++- man/make_idw_map.Rd | 7 +++++-- man/make_idw_stack.Rd | 5 ++++- 5 files changed, 17 insertions(+), 7 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index be1f7e5..d779057 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -4,7 +4,7 @@ Title: Alaska Groundfish and Ecosystem Survey Area Mapping Version: 3.3.0 Authors@R: c(person("Sean", "Rohan", email = "sean.rohan@noaa.gov", role = c("aut", "cre")), person("Jason", "Conner", email = "jason.conner@noaa.gov", role = "ctb"), - person("Liz", "Dawson", email = "liz.dawson@noaa.gov", role = "ctb"), + person("Liz", "Dawson", role = "ctb"), person("Ned", "Laman", email = "ned.laman@noaa.gov", role = "ctb"), person("Emily", "Markowitz", email = "emily.markowitz@noaa.gov", role = "ctb"), person("Zack", "Oyafuso", email = "zack.oyafuso@noaa.gov", role = "ctb")) diff --git a/R/make_idw_map.R b/R/make_idw_map.R index c5e123b..7c360fd 100644 --- a/R/make_idw_map.R +++ b/R/make_idw_map.R @@ -4,14 +4,14 @@ #' #' @param x Data frame which contains at minimum: CPUE, LATITUDE, and LONGITUDE. Can be passed as vectors instead (see below). Default value: \code{NA} #' @param region Character vector indicating which plotting region to use. Options: bs.south, bs.north, bs.all -#' @param grid.cell Numeric vector of length two specifying dimensions of grid cells for extrpolation grid, in units for the output CRS. Default = c(5000,5000) correponds with 5x5 km for EPSG:3338 +#' @param grid.cell Numeric vector of length two specifying dimensions of grid cells for extrpolation grid, in units for the output CRS. Default = c(5000,5000) corresponds with 5x5 km for EPSG:3338 #' @param COMMON_NAME Common name #' @param LATITUDE Latitude (degrees north) #' @param LONGITUDE Longitude (degrees east; Western hemisphere is negative) #' @param CPUE_KGHA Catch per unit effort in kilograms per hectare #' @param extrap.box Optional. Vector specifying the dimensions of the extrapolation grid. Elements of the vector should be named to specify the minimum and maximum x and y values c(xmin, xmax, ymin, ymax). If not provided, the extrapolation area will be set to the extent of the survey.area bounding box with the output CRS. #' @param extrapolation.grid.type Type of object to use for the extrapolation grid, default = "stars". "stars" = returns a 'stars' object; "sf" = sf object with layer masked to survey area extent and converted to collection of sf POLYGON and MULTIPOLYGON geometries; "sf.simple" = same as "sf", but with polygons vertices smoothed using rmapshaper::ms_simplify -#' @param set.breaks Suggested. Vector of break points to use for plotting. Alternatively, a character vector indicating which break method to use. Default = "jenks" +#' @param set.breaks Either a numeric vector of breaks to use for plotting or a character vector indicating which classIntervals() algorithm to use for break selection. See Description for information about break selection. Users are strongly encouraged to specify their own numeric vector of breaks based on the properties of their data. #' @param in.crs Character vector containing the coordinate reference system for projecting the extrapolation grid. #' @param out.crs Character vector containing the coordinate reference system for projecting the extrapolation grid. The default is Alaska Albers Equal Area (EPSG:3338). #' @param key.title Character vector which will appear in the legend above key.title.units. Default = "auto" tries to pull COMMON_NAME from input. @@ -20,6 +20,8 @@ #' @param idw.nmax Maximum number of adjacent stations to use for interpolation. Default = 8 #' @param use.survey.bathymetry Logical indicating if historical survey bathymetry should be used instead of continuous regional bathymetry. Default = TRUE #' @param return.continuous.grid If TRUE, also returns an extrapolation grid on a continuous scale. +#' @details +#' This function include an argument for algorithmic break selection using the `set.breaks` argument. However, algorithmic break selection is provided for convenience purposes and **users are strongly encouraged to select their own breaks based on the properties of their data**. No single algorithm in the package can be expected to perform well in all cases. See ?classInt::classIntervals for a algorithmic break selection method options. #' @return Returns a list containing: #' (1) plot: a ggplot IDW map; #' (2) extrapolation.grid: the extrapolation grid with estimated values on a discrete scale as a 'stars' (when extrapolation.grid.type is "stars") or 'sf' (when extrapolation.grid.type is "sf" or "sf.simple") object; diff --git a/R/make_idw_stack.R b/R/make_idw_stack.R index 10f7847..0aea2f4 100644 --- a/R/make_idw_stack.R +++ b/R/make_idw_stack.R @@ -12,12 +12,14 @@ #' @param grouping.vars Character vector indicating of columns in the input data frame to use for grouping input variable layers. #' @param extrap.box Optional. Vector specifying the dimensions of the extrapolation grid. Elements of the vector should be named to specify the minimum and maximum x and y values c(xmin, xmax, ymin, ymax). If not provided, the extrapolation area will be set to the extent of the survey.area bounding box with the output CRS. #' @param extrapolation.grid.type Type of object to use for the extrapolation grid, default = "stars". "stars" = returns a 'stars' object; "sf" = sf object with layer masked to survey area extent and converted to collection of sf POLYGON and MULTIPOLYGON geometries; "sf.simple" = same as "sf", but with polygons vertices smoothed using rmapshaper::ms_simplify -#' @param set.breaks Suggested. Vector of break points to use for plotting. Alternatively, a character vector indicating which break method to use. Default = "jenks" +#' @param set.breaks Either a numeric vector of breaks to use for plotting or a character vector indicating which classIntervals() algorithm to use for break selection. See Description for information about break selection. Users are strongly encouraged to specify their own numeric vector of breaks based on the properties of their data. #' @param in.crs Character vector containing the coordinate reference system for projecting the extrapolation grid. #' @param out.crs Character vector containing the coordinate reference system for projecting the extrapolation grid. The default is Alaska Albers Equal Area (EPSG:3338). #' @param log.transform Character vector indicating whether CPUE values should be log-transformed for IDW. Default = FALSE. #' @param idw.nmax Maximum number of adjacent stations to use for interpolation. Default = 8 #' @param use.survey.bathymetry Logical indicating if historical survey bathymetry should be used instead of continuous regional bathymetry. Default = TRUE +#' @details +#' This function include an argument for algorithmic break selection using the `set.breaks` argument. However, algorithmic break selection is provided for convenience purposes and **users are strongly encouraged to select their own breaks based on the properties of their data**. No single algorithm in the package can be expected to perform well in all cases. See ?classInt::classIntervals for a algorithmic break selection method options. #' @return Returns a list containing: #' (1) map_layers: Layer of shapefiles returned by akgfmaps::get_base_layers() #' (2) extrapolation.stack: a stack of extrapolated spatial objects with estimated values on a discrete scale as a 'stars' (when extrapolation.grid.type is "stars") or 'sf' (when extrapolation.grid.type is "sf" or "sf.simple") object; diff --git a/man/make_idw_map.Rd b/man/make_idw_map.Rd index 40f1292..2bdb704 100644 --- a/man/make_idw_map.Rd +++ b/man/make_idw_map.Rd @@ -42,9 +42,9 @@ make_idw_map( \item{extrapolation.grid.type}{Type of object to use for the extrapolation grid, default = "stars". "stars" = returns a 'stars' object; "sf" = sf object with layer masked to survey area extent and converted to collection of sf POLYGON and MULTIPOLYGON geometries; "sf.simple" = same as "sf", but with polygons vertices smoothed using rmapshaper::ms_simplify} -\item{set.breaks}{Suggested. Vector of break points to use for plotting. Alternatively, a character vector indicating which break method to use. Default = "jenks"} +\item{set.breaks}{Either a numeric vector of breaks to use for plotting or a character vector indicating which classIntervals() algorithm to use for break selection. See Description for information about break selection. Users are strongly encouraged to specify their own numeric vector of breaks based on the properties of their data.} -\item{grid.cell}{Numeric vector of length two specifying dimensions of grid cells for extrpolation grid, in units for the output CRS. Default = c(5000,5000) correponds with 5x5 km for EPSG:3338} +\item{grid.cell}{Numeric vector of length two specifying dimensions of grid cells for extrpolation grid, in units for the output CRS. Default = c(5000,5000) corresponds with 5x5 km for EPSG:3338} \item{in.crs}{Character vector containing the coordinate reference system for projecting the extrapolation grid.} @@ -75,6 +75,9 @@ Returns a list containing: \description{ This function can be used to make inverse-distance-weighted plots for the eastern Bering Sea and northern Bering Sea } +\details{ +This function include an argument for algorithmic break selection using the `set.breaks` argument. However, algorithmic break selection is provided for convenience purposes and **users are strongly encouraged to select their own breaks based on the properties of their data**. No single algorithm in the package can be expected to perform well in all cases. See ?classInt::classIntervals for a algorithmic break selection method options. +} \author{ Sean Rohan \email{sean.rohan@noaa.gov} } diff --git a/man/make_idw_stack.Rd b/man/make_idw_stack.Rd index eb1b1e4..2a47488 100644 --- a/man/make_idw_stack.Rd +++ b/man/make_idw_stack.Rd @@ -40,7 +40,7 @@ make_idw_stack( \item{extrapolation.grid.type}{Type of object to use for the extrapolation grid, default = "stars". "stars" = returns a 'stars' object; "sf" = sf object with layer masked to survey area extent and converted to collection of sf POLYGON and MULTIPOLYGON geometries; "sf.simple" = same as "sf", but with polygons vertices smoothed using rmapshaper::ms_simplify} -\item{set.breaks}{Suggested. Vector of break points to use for plotting. Alternatively, a character vector indicating which break method to use. Default = "jenks"} +\item{set.breaks}{Either a numeric vector of breaks to use for plotting or a character vector indicating which classIntervals() algorithm to use for break selection. See Description for information about break selection. Users are strongly encouraged to specify their own numeric vector of breaks based on the properties of their data.} \item{grouping.vars}{Character vector indicating of columns in the input data frame to use for grouping input variable layers.} @@ -67,6 +67,9 @@ Returns a list containing: \description{ This function can be used to make inverse-distance-weighted plots for the eastern Bering Sea and northern Bering Sea } +\details{ +This function include an argument for algorithmic break selection using the `set.breaks` argument. However, algorithmic break selection is provided for convenience purposes and **users are strongly encouraged to select their own breaks based on the properties of their data**. No single algorithm in the package can be expected to perform well in all cases. See ?classInt::classIntervals for a algorithmic break selection method options. +} \author{ Sean Rohan \email{sean.rohan@noaa.gov} }