Package 'nsink'

nsink: A package that implements flow path analysis of nitrogen removal

Description

The N-Sink approach is based off of research outlined in Kellogg et al (2010). This approach builds on peer-reviewed literature in the form of reviews and meta-analyses (i.e., Mayer et al (2007), Alexander et al (2007), and Seitzinger et al (2006)) to estimate nitrogen (N) removal within three types of landscape sinks – wetlands, streams and lakes – along any given flow path within a HUC12 basin. The nsink package implements this approach, using publicly available spatial data to identify flow paths and estimate N removal in landscape sinks. Removal rates depend on retention time, which is influenced by physical characteristics identified using publicly available spatial data – National Hydrography Dataset (NHD), Watershed Boundary Dataset (WBD), National Land Cover Dataset (NLCD), and Soil Survey Geographic Dataset (SSURGO). Static maps of a specified HUC-12 basin are generated – N Removal Efficiency, N Loading Index, N Transport Index, and N Delivery Index. These maps may be used to inform local decision-making by highlighting areas that are more prone to N "leakiness" and areas that contribute to N removal.

References

Kellogg, D. Q., Gold, A. J., Cox, S., Addy, K., & August, P. V. (2010). A geospatial approach for assessing denitrification sinks within lower-order catchments. Ecological Engineering, 36(11), 1596-1606. Link

Mayer, P. M., Reynolds Jr., S. K., McCutchen, M. D., & Canfield, T. J. (2007). Meta-analysis of nitrogen removal in riparian buffers. J. Environ. Qual. 36, 1172-1180. Link

Alexander, R. B., Boyer, E. W., Smith, R.A., Schwarz, G.E. & Moore, R. B. (2007). The role of headwater streams in downstream water quality. J. Am. Water Resou.Assoc. 43, 41-59. Link

Seitzinger, S. P., Harrison, J.A., Hohlke, J.K., Bouwman, A.F., Lowrance, R., Peterson, B., Tobias, C., & Van Drecht, G. (2006). Denitrification across landscapes and waterscapes: a synthesis. Ecol. Appl. 16, 1064-2090. Link

---

Build out required datasets for N-Sink

Description

This function is a wrapper around the other functions and runs all of those required to build out the full dataset needed for a huc and develops the four static N-Sink maps: the nitrogen loading index, nitrogen removal effeciency, nitrogen transport index, and the nitrogen delivery index. The primary purpose of this is to use the nsink package to develop the required datasets for an nsink application to be built outside of R (e.g. ArcGIS). This will take some time to complete as it is downloading 500-600 Mb of data, processing that data and then creating output files.

Usage

nsink_build(
  huc,
  projection,
  output_dir = normalizePath("nsink_output", winslash = "/", mustWork = FALSE),
  data_dir = normalizePath("nsink_data", winslash = "/", mustWork = FALSE),
  force = FALSE,
  samp_dens = 300,
  year = "2016",
  ...
)

Arguments

huc	A character with the 12 digit HUC ID. May be searched with nsink_get_huc_id
projection	Projection to use for all spatial data, specified as either an EPSG code (as numeric) or WKT (as string).
output_dir	Folder to write processed nsink files to. Currently, the processed files will be overwritten if the same output folder is used. To run different HUC12's specify separate output folders.
data_dir	Folder to hold downloaded data. The same data directory can be used to hold data for multiple HUCs. Data will not be downloaded again if it already exists in this folder.
force	Logical value used to force a new download if data already exists on file system.
samp_dens	The samp_dens controls the density of points to use when creating the nitrogen removal heat map. The area of the watershed is sampled with points that are separated by the samp_dens value, in the units of the input data. The larger the value, the fewer the points.
year	Year argument to be passed to FedData's get_nlcd function. Defaults to 2016.
...	Passes to nsink_calc_removal for the off network arguments: off_network_lakes, off_network_streams, and off_network_canalsditches.

Value

A list providing details on the huc used and the output location of the dataset.

Examples

## Not run: 
library(nsink)
aea <- 5072
nsink_build(nsink_get_huc_id("Niantic River")$huc_12, aea,
            output_dir = "nsink_output", data_dir = "nsink_data",
             samp_dens = 600)

## End(Not run)

---

Calculates N-Sink nitrogen removal percent

Description

Starting with base data layers of NHDPlus, SSURGO, impervious surface, flow velocity, and time of travel, this function calculates percentage of Nitrogen removal. Nitrogen removal methods and calculations are from Kellogg et al. (2010). This function assumes data has been downloaded with nsink_get_data and has been prepared with nsink_prep_data.

Usage

nsink_calc_removal(
  input_data,
  off_network_lakes = NULL,
  off_network_streams = NULL,
  off_network_canalsditches = NULL,
  off_network_out = FALSE
)

Arguments

input_data	A list of input datasets created with nsink_prep_data.
off_network_lakes	Optional argument to set removal for waterbodies that are not part of the NHDPlus hydrologic network. Default value is to use the 75th percentile of removal from other lakes in the HUC. If another value is desired provide a single numeric ranging from 0 to 1.
off_network_streams	Optional argument to set removal for streams that are not part of the NHDPlus hydrologic network. Default value is to use the median removal from first order streams in the HUC. If another value is desired provide a single numeric ranging from 0 to 1.
off_network_canalsditches	Optional argument to set removal for canals and ditches that are not part of the NHDPlus hydrologic network. Default value is to use the 25th percentile of removal from third order streams in the HUC. If another value is desired provide a single numeric ranging from 0 to 1.
off_network_out	Optional argument to have the off network features returned on the output list.

Value

A list with three items, 1) a raster stack with one layer with the nitrogen removal, a second layer with the type of removal (e.g. hydric soils, lakes, streams), 2) a polygon representing removal from land, and 3) a polygon representing removal from the stream network, including stream removal, and lake removal. Optionally, the off network waterbodies may be returned if off_network_out == TRUE.

References

Kellogg, D. Q., Gold, A. J., Cox, S., Addy, K., & August, P. V. (2010). A geospatial approach for assessing denitrification sinks within lower-order catchments. Ecological Engineering, 36(11), 1596-1606. Link

Examples

## Not run: 
library(nsink)
niantic_huc <- nsink_get_huc_id("Niantic River")$huc_12
niantic_data <- nsink_get_data(niantic_huc, data_dir = "nsink_data")
aea <- 5072
niantic_nsink_data <- nsink_prep_data(niantic_huc, projection = aea ,
                                      data_dir = "nsink_data")
removal <- nsink_calc_removal(niantic_nsink_data)

## End(Not run)

---

Generate and clean a flowpath for N-Sink

Description

This function takes an XY location as a starting point and generates a flowpath for use in the N-Sink nitrogen removal analysis. The flowpath is a combination of a flow direction derived flowpath on land plus NHDPlus derived stream-reach flowpath.

Usage

nsink_generate_flowpath(starting_location, input_data)

Arguments

starting_location	An sf point location as a starting point for the flowpath. Projection must match projection in input_data.
input_data	A list of input data with (at least) "fdr", "streams", "tot", and "raster_template". These may be generated with nsink_prep_data.

Value

An sf LINESTRING object of the flowpath that starts at the starting_location and ends at the ouflow of the HUC.

Examples

## Not run: 
library(nsink)
niantic_huc <- nsink_get_huc_id("Niantic River")$huc_12
niantic_data <- nsink_get_data(niantic_huc, data_dir = "nsink_data")
aea <- 5072
niantic_nsink_data <- nsink_prep_data(niantic_huc, projection = aea,
                                      data_dir = "nsink_niantic_data")
pt <- c(1948121, 2295822)
start_loc <- st_sf(st_sfc(st_point(c(pt)), crs = aea))
fp <- nsink_generate_flowpath(start_loc, niantic_nsink_data)

## End(Not run)

---

Generate N-Sink Static Maps for a given HUC

Description

Generate N-Sink Static Maps for a given HUC

Usage

nsink_generate_static_maps(
  input_data,
  removal,
  samp_dens,
  ncpu = future::availableCores() - 1,
  seed = 23
)

Arguments

input_data	A list of input datasets created with nsink_prep_data.
removal	The removal raster stack or removal list, generated by nsink_calc_removal
samp_dens	A value, in the units of the input data, divided by total area of the input HUC. It is used to determine the number of points, determined through a regular sample, to calculate removal. For instance, a value of 90 would roughly equate to a point per every 90 meters.
ncpu	Number of CPUs to use for calculating flowpath removal for larger (i.e. greater than 50) number of flowpaths. Default is the number of cores available minus one.
seed	Random seed to ensure reproducibility of sample point creation for transport maps. Default set to 23.

Value

This function returns a list of rasters: nitrogen removal efficiency, nitrogen loading index, nitrogen transport index, and the nitrogen delivery index.

Examples

## Not run: 
library(nsink)
niantic_huc <- nsink_get_huc_id("Niantic River")$huc_12
niantic_data <- nsink_get_data(niantic_huc, data_dir = "nsink_data")
aea <- 5072
niantic_nsink_data <- nsink_prep_data(niantic_huc, projection = aea,
                                      data_dir = "nsink_data")
removal <- nsink_calc_removal(niantic_nsink_data)
static_maps <- nsink_generate_static_maps(niantic_nsink_data, removal,samp_dens = 900)

## End(Not run)

---

Gets N-Sink data for a given HUC

Description

The required datasets for the N-sink analysis are available from multiple, online resources. This function takes a HUC as input and downloads local copies of those datasets. It will place these in a local directory and inside that directory a new folder for each NHD Plus raster processing unit will be created. If you use the same folder for the data directory, it will act as a cache (imperfect, though) and only download any new datasets that have not already been downloaded.

Usage

nsink_get_data(
  huc,
  data_dir = normalizePath("nsink_data", winslash = "/", mustWork = FALSE),
  force = FALSE,
  year = "2016"
)

Arguments

huc	A character string of a HUC identifier. Currently can run only a single HUC at a time. This package was developed using 12-digit HUCS, but has been (lightly) tested with larger HUCs and appears to work, but is not certain for all cases.
data_dir	A directory to store N-Sink data downloads. Defaults to "nsink_data" inside of the current working directory. Created if it doesn't exist. May be used for multiple HUCs and only data that doesn't currently exist will be downloaded.
force	Logical to determine if files should be downloaded again if they already exist locally.
year	An argument to be passed to FedData's get_nlcd function. Default is 2016.

Value

Returns a list with the huc used and the directory where the data is stored.

Examples

## Not run: 
library(nsink)
niantic_huc <- nsink_get_huc_id("Niantic River")$huc_12
nsink_get_data(huc = niantic_huc, data_dir = "nsink_data", force = TRUE)

## End(Not run)

---

Look up HUC 12 ID from a HUC name

Description

This function takes a HUC Name and returns matching HUC 12 IDs. The default behavior is to select all possible matching IDs without matching the case of the string. If an exact match is required, use the exact argument.

Usage

nsink_get_huc_id(huc_name, exact = FALSE)

Arguments

huc_name	Character string of a HUC Name or partial HUC name
exact	Logical indicating whether or not to do an exact match

Value

A data frame with HUC_12 and HU_12_NAME that match the huc_name

Examples

nsink_get_huc_id(huc_name = "Niantic River")

---

Load an existing N-Sink analysis folder

Description

Load an existing N-Sink analysis folder

Usage

nsink_load(input_folder, base_name = "nsink_", projection = NULL, ...)

Arguments

input_folder	Folder that contains nsink files produced by nsink_build
base_name	A base name used to assign objects to the global environment.
projection	An optional CRS specified as a either an EPSG code (as numeric) or WKT (as string). Useful if projection is returned as unknown.
...	Passes to nsink_calc_removal for the off network arguments: off_network_lakes, off_network_streams, and off_network_canalsditches.

Value

Creates several lists in the global environment that would normally be created when running an N-Sink analysis. These include: a nsink_prep_data object, a nsink_calc_removal object, and a nsink_generate_static_maps object

Examples

## Not run: 
library(nsink)

aea <- 5072
nsink_build(nsink_get_huc_id("Niantic River")$huc_12, aea,
            output_folder = "nsink_output", samp_dens = 300)
nsink_load(input_folder = "nsink_output",
           base_name = "nsink_")

## End(Not run)

---

N-Sink plot function for the a list of nsink static maps

Description

This function creates a simple plot with pre-selected color palettes from a list of static maps created by nsink_generate_static_maps. This is meant as a quick means to visualize the various static maps.

Usage

nsink_plot(static_maps, map = c("removal", "transport", "delivery"))

Arguments

static_maps	A list of raster objects that can be created via nsink_generate_static_maps. The list should have removal_effic, delivery_idx, and transport_idx.
map	A character of either, "removal", "transport", or "delivery."

Examples

## Not run: 
library(nsink)
niantic_huc <- nsink_get_huc_id("Niantic River")$huc_12
niantic_data <- nsink_get_data(niantic_huc, data_dir = "nsink_data")
aea <- 5072
niantic_nsink_data <- nsink_prep_data(niantic_huc, projection = aea,
                                      data_dir = "nsink_data")
removal <- nsink_calc_removal(niantic_nsink_data)
static_maps <- nsink_generate_static_maps(niantic_nsink_data, removal,
samp_dens = 900)
nsink_plot(static_maps, "transport")

## End(Not run)

---

Prepares N-Sink data for a given HUC

Description

In addition to having local access to the required dataset, those datasets need to have some preparation. This function standardizes projections and extents and clips all datasets to the boundary of the specified HUC. Additionally, any tabular datasets (e.g. flow, time of travel, etc.) are included in the output as well.

Usage

nsink_prep_data(
  huc,
  projection,
  data_dir = normalizePath("nsink_data/", winslash = "/", mustWork = FALSE),
  year = "2016"
)

Arguments

huc	A character string of the HUC12 ID. Use nsink_get_huc_id to look up ID by name.
projection	CRS to use, passed as ethier EPSG code (as numeric) or WKT (as character). This must be a projected CRS and not geographic as many of the measurements required for the nsink analysis require reliable length and area measurments.
data_dir	Base directory that contains N-Sink data folders. Data may be downloaded with the nsink_get_data function.
year	The year of the nlcd and impervious data that was retrieved with FedData's, get_nlcd function.

Value

returns a list of sf, raster, or tabular objects for each of the required datasets plus the huc.

Examples

## Not run: 
library(nsink)
aea <- 5072
niantic_huc <- nsink_get_huc_id("Niantic River")$huc_12
niantic_nsink_data <- nsink_prep_data(huc = niantic_huc, projection = aea,
data_dir = "nsink_data")
# Example using EPSG code for projection
epsg <- 3748L
niantic_nsink_data <- nsink_prep_data(huc = niantic_huc, projection = epsg,
                data_dir = "nsink_data")

## End(Not run)

---

Summarize nitrogen removal along a flowpath

Description

Nitrogen removal varies along a flowpath as it may include different land cover and waterbody types that have different nitrogen reduction capabilities. This function requires a flowpath generated by nsink_generate_flowpath as input and returns an estimate of total flow path removal as well as removal by type.

Usage

nsink_summarize_flowpath(flowpath, removal)

Arguments

flowpath	A flowpath to summarize nitrogen removal
removal	The removal raster stack or removal list, generated by nsink_calc_removal

Value

A data frame is returned with a summary of nitrogen removal. The

Examples

## Not run: 
library(nsink)
niantic_huc <- nsink_get_huc_id("Niantic River")$huc_12
niantic_data <- nsink_get_data(niantic_huc, data_dir = "nsink_data")
aea <- 5072
niantic_nsink_data <- nsink_prep_data(niantic_huc, projection = aea,
                                      data_dir = "nsink_data")
removal <- nsink_calc_removal(niantic_nsink_data)
pt <- c(1948121, 2295822)
start_loc <- st_sf(st_sfc(st_point(c(pt)), crs = aea))
fp <- nsink_generate_flowpath(start_loc, niantic_nsink_data)
flow_summary <- nsink_summarize_flowpath(fp, removal)
flow_summary

## End(Not run)

---