Type: Package
Title: 'StreamCatTools'
Version: 0.8.0
Description: Tools for using the 'StreamCat' and 'LakeCat' API and interacting with the 'StreamCat' and 'LakeCat' database. Convenience functions in the package wrap the API for 'StreamCat' on https://api.epa.gov/StreamCat/streams/metrics.
Depends: R (≥ 4.1.0)
Imports: sf, nhdplusTools, jsonlite, httr2, curl (≥ 6.0.0)
Suggests: dplyr, ggplot2, mapview, testthat, knitr, rmarkdown, devtools, xml2, magrittr, readr, tidyr, stringr, purrr
Encoding: UTF-8
URL: https://usepa.github.io/StreamCatTools/, https://github.com/USEPA/StreamCatTools
BugReports: https://github.com/USEPA/StreamCatTools/issues
VignetteBuilder: knitr,rmarkdown
RoxygenNote: 7.3.3
License: CC0
NeedsCompilation: no
Packaged: 2025-10-08 21:01:36 UTC; mweber
Author: Marc Weber [aut, cre], Ryan Hill [ctb], Travis Hudson [ctb], Allen Brookes [ctb], David Rebhuhn [ctb], Michael Dumelle [ctb], Zachary Smith [ctb]
Maintainer: Marc Weber <weber.marc@epa.gov>
Repository: CRAN
Date/Publication: 2025-10-09 08:40:21 UTC

Lookup Full Metric Name

Description

Function to retrieve a full metric name based on the short name using the LakeCat API.

Usage

lc_fullname(metric = NULL)

Arguments

metric

Short metric name Syntax: metric=value1 Values: metric

Value

A lookup of the full name for a given LakeCat metric

Author(s)

Marc Weber

Examples

fullname <- lc_fullname(metric='clay')

Get Lake COMIDs

Description

Function to return NHDPlusV2 Waterbody COMIDS using either a dataframe with coordinates and a specified CRS or an sf object. The function generates a vector of NHDPlus Waterbody COMID values a user can then pass to lc_get_data function

Usage

lc_get_comid(
  dd = NULL,
  xcoord = NULL,
  ycoord = NULL,
  crsys = NULL,
  buffer = NULL
)

Arguments

dd

Name of data frame object. Can be a simple data frame with coordinate columns in a known CRS or an sf points data frame

xcoord

The x coordinate column if using a raw data frame

ycoord

The y coordinate column if using a raw data frame

crsys

The epsg code if using a raw data frame

buffer

The amount of buffer to use to extend search for a waterbody (simply passed to nhdplusTools::get_waterbodies)

Value

A new sf data frame with a populated 'COMID' column

Author(s)

Marc Weber

Examples

## Not run: 

dd <- data.frame(x = c(-89.198,-114.125,-122.044),
y = c(45.502,47.877,43.730))

comids <- lc_get_comid(dd, xcoord='x',
                       ycoord='y', crsys=4269)

dd <- data.frame(x = c(-89.198,-114.125,-122.044),
y = c(45.502,47.877,43.730)) |> 
   sf::st_as_sf(coords = c('x', 'y'), crs = 4326)
   
comids <- lc_get_comid(dd)
 
## End(Not run)

Get LakeCat data

Description

Function to return LakeCat metrics using the StreamCat API. The function allows a user to get specific metric data aggregated by area of interest, returned by comid(s), hydroregion(s), state(s), or county(ies).

Usage

lc_get_data(
  comid = NULL,
  metric = NULL,
  aoi = NULL,
  showAreaSqKm = NULL,
  showPctFull = NULL,
  state = NULL,
  county = NULL,
  region = NULL,
  conus = NULL,
  countOnly = NULL
)

Arguments

comid

Return metric information for specific COMIDs. Can be a comma-delimited list, a character vector, or any object that can be coerced to a comma-delimited list with paste. One of comid, county, state, or region is required unless conus='true'. Syntax: comid=<comid1>,<comid2>

metric

Name(s) of metrics to query. Must be character string with comma-delimited list of metrics. Not case-sensitive. Syntax: name=<name1>,<name2>

aoi

Specify the area of interest described by a metric. By default, all available areas of interest for a given metric are returned. Case-sensitive. Syntax: areaOfInterest=<value1>,<value2> Values: catchment|watershed|

showAreaSqKm

Return the area in square kilometers of a given area of interest. The default value is false. Values: true|false

showPctFull

Return the pctfull for each dataset. The default value is false. Values: true|false

state

Return metric information for COMIDs within a specific state. Use a state's abbreviation to query for a given state. One of comid, county, state, or region is required unless conus='true'. If specified and valid, comid and county are ignored. Case-sensitive. Syntax: state=<state1>,<state2>

county

Return metric information for COMIDs within a specific county. Users must use the FIPS code, not county name, as a way to disambiguate counties. One of comid, county, state, or region is required unless conus='true'. If specified and valid, comid is ignored. Syntax: county=<county1>,<county1>

region

Return metric information for COMIDs within a specified hydroregion. Hydroregions are specified using full name i.e. 'Region01', 'Region03N', 'Region10L' One of comid, county, state, or region is required unless conus='true'. If specified and valid, comid, county, and state are ignored. Case-sensitive. Syntax: region=<regionid1>,<regionid2>

conus

Return all COMIDs in the conterminous United States. Character string (Not case-sensitive) or logical. The default value is false. If true, comid, county, state, and region are ignored. Values: true|false

countOnly

Return a CSV containing only the row count (ROWCOUNT) and the column count (COLUMNCOUNT) that the server expects to return in a request. The default value is false. Values: true|false

Value

A tibble of desired StreamCat metrics. If data are missing for all rows of a given metric, then the column for that metric will not exist. If data are missing for only some rows, then they will be specified with NA.

Author(s)

Marc Weber

Examples

## Not run: 
df <- lc_get_data(comid='23794487', aoi='cat', metric='fert')

df <- lc_get_data(metric='pcturbmd2006', aoi='ws',
comid='24083377')

df <- lc_get_data(metric='pctgrs2006', aoi='ws', region='Region01')

df <- lc_get_data(metric='pctwdwet2006', aoi='ws', county='41003')

df <- lc_get_data(metric='pcturbmd2006', aoi='ws',
comid='24083377', showAreaSqKm=FALSE, showPctFull=TRUE)

df <- lc_get_data(metric='pcturbmd2006,damdens',
aoi='cat,ws', comid='23783629,23794487,23812618')

df <- lc_get_data(metric='pcturbmd2006,damdens',
aoi='cat,ws', comid=c('23783629','23794487','23812618'))

df <- lc_get_data(metric='pcturbmd2006,damdens',
aoi='cat,ws', comid='23783629,23794487,23812618',
countOnly=TRUE)


 
## End(Not run)

Get LakeCat Metric Names

Description

Function to filter LakeCat metrics metrics by category, area of interest, dataset or year. Use 'lc_get_params(categories)' or 'lc_get_params(datasets)' to see all the valid category or dataset options

Usage

lc_get_metric_names(category = NULL, aoi = NULL, year = NULL, dataset = NULL)

Arguments

category

Filter LakeCat metrics based on the metric category

aoi

Filter LakeCat metrics based on the area of interest

year

Filter LakeCat metrics based on a particular year or years

dataset

Filter LakeCat metrics based on the dataset name

Value

A dataframe of merics and description that match filter criteria

Author(s)

Marc Weber

Examples

## Not run: 
metrics <- lc_get_metric_names(category='Natural')
metrics <- lc_get_metric_names(category = c('Anthropogenic','Natural'),
aoi=c('Cat','Ws')
## End(Not run)

Get LakeCat Parameters

Description

Function to return available LakeCat parameters using the StreamCat API.

Usage

lc_get_params(param = NULL)

Arguments

param

List of available parameters in the API for the following options: name, areaofInterest, region, state, county. State and county return a data frame that includes FIPS codes, names and state abbreviations Syntax: param=<value1>,<value2> Values: name|area

Value

A list of all the current LakeCat values for a given parameter

Author(s)

Marc Weber

Examples

## Not run: 
params <- lc_get_params(param='variable_info')
params <- lc_get_params(param='metric_names')
params <- sc_get_params(param='categories')
params <- lc_get_params(param='aoi')
params <- lc_get_params(param='state')
params <- lc_get_params(param='county')
params <- sc_get_params(param='datasets')

## End(Not run)

Get NLCD Data

Description

Function to specifically retrieve all NLCD metrics for a given year using the StreamCat API.

Usage

lc_nlcd(
  year = "2019",
  aoi = NULL,
  comid = NULL,
  showAreaSqKm = NULL,
  showPctFull = NULL,
  countOnly = NULL
)

Arguments

year

Years(s) of NLCD metrics to query. Only valid NLCD years are accepted (i.e. 2001, 2004, 2006, 2008, 2011, 2013, 2016, 2019) Syntax: year=<year1>,<year2>

aoi

Specify the area of interest described by a metric. By default, all available areas of interest for a given metric are returned. Syntax: areaOfInterest=<value1>,<value2> Values: catchment|watershed|riparian_catchment|riparian_watershed|other

comid

Return metric information for specific COMIDs Syntax: comid=<comid1>,<comid2>

showAreaSqKm

Return the area in square kilometers of a given area of interest. The default value is false. Values: true|false

showPctFull

Return the pctfull for each dataset. The default value is false. Values: true|false

countOnly

Return a CSV containing only the row count (ROWCOUNT) and the column count (COLUMNCOUNT) that the server expects to return in a request. The default value is false. Values: true|false

Value

A tibble of desired StreamCat metrics

Author(s)

Marc Weber

Examples

## Not run: 

df <- lc_nlcd(comid='23783629', year='2019', aoi='ws')

df <- lc_nlcd(year='2016', aoi='cat',
comid='23783629,23794487,23812618', showAreaSqKm=FALSE, showPctFull=TRUE)

df <- lc_nlcd(year='2016', aoi='cat',
comid='23783629,23794487,23812618', countOnly=TRUE)

df <- lc_nlcd(year='2016, 2019', aoi='cat,ws',
comid='23783629,23794487,23812618')

## End(Not run)

Lookup Full Metric Name

Description

Function to retrieve a full metric name based on the short name using the StreamCat API.

Usage

sc_fullname(metric = NULL)

Arguments

metric

Short metric name Syntax: metric=value1 Values: metric

Value

A lookup of the full name for a given StreamCat metric

Author(s)

Marc Weber

Examples

fullname <- sc_fullname(metric='clay')

Get COMIDs

Description

Function to return NHDPlusV2 COMIDS using either a dataframe with coordinates and a specified CRS or an sf object. The function generates a vector of COMID values a user can then pass to sc_get_data function

Usage

sc_get_comid(dd = NULL, xcoord = NULL, ycoord = NULL, crsys = NULL)

Arguments

dd

Name of data frame object. Can be a simple data frame with coordinate columns in a known CRS or an sf points data frame

xcoord

The x coordinate column if using a raw data frame

ycoord

The y coordinate column if using a raw data frame

crsys

The epsg code if using a raw data frame

Value

A new sf data frame with a populated 'COMID' column

Author(s)

Marc Weber

Examples

## Not run: 

dd <- data.frame(x = c(-122.649,-100.348,-75.186,-106.675),
y = c(45.085, 35.405,42.403,38.721))

comids <- sc_get_comid(dd, xcoord='x',
                       ycoord='y', crsys=4269)

dd <- sf::st_point_on_surface(sf::read_sf(system.file("shape/nc.shp", package="sf")))

comids <- sc_get_comid(dd)
                                  
comids <- sc_get_comid(dd, xcoord='x', 
ycoord='y', crsys=4269)

dd <- sf::read_sf(system.file("shape/nc.shp", package="sf"))
comids <- sc_get_comid(dd)

 
## End(Not run)

Get StreamCat data

Description

Function to return StreamCat catchment and watershed metrics using the StreamCat API. The function allows a user to get specific metric data aggregated by area of interest, returned by comid(s), hydroregion(s), state(s), or county(ies).

Usage

sc_get_data(
  comid = NULL,
  metric = NULL,
  aoi = NULL,
  showAreaSqKm = NULL,
  showPctFull = NULL,
  state = NULL,
  county = NULL,
  region = NULL,
  conus = NULL,
  countOnly = NULL
)

Arguments

comid

Return metric information for specific COMIDs. Can be a comma-delimited list, a character vector, or any object that can be coerced to a comma-delimited list with paste. One of comid, county, state, or region is required unless conus='true'. Syntax: comid=<comid1>,<comid2>

metric

Name(s) of metrics to query. Must be character string with comma-delimited list of metrics, or, if metric='all' then all metrics will be queried. Not case-sensitive. Syntax: name=<name1>,<name2>

aoi

Name(s) of areas of interest to query. If a metric does not have data for a given AOI, no data is returned for that AOI. Certain metrics that have no AOI specified for StreamCat need the AOI to be specified as 'other'. These metrics include: BankfullDepth, BankfullWidth, ThalwagDepth (sic), CHEM_V2_1, CONN, HABT, HYD, ICI, IWI, TEMP, WettedWidth, prg_bmmi, and all the mast, msst, mwst metrics. Case-sensitive.

Syntax: areaOfInterest=<value1>,<value2> Values: cat|ws|catrp100|wsrp100|other

showAreaSqKm

Return the area in square kilometers of a given area of interest. The default value is false. Values: true|false

showPctFull

Return the pctfull for each dataset. The default value is false. Values: true|false

state

Return metric information for COMIDs within a specific state. Use a state's abbreviation to query for a given state. One of comid, county, state, or region is required unless conus='true'. If specified and valid, comid and county are ignored. Case-sensitive. Syntax: state=<state1>,<state2>

county

Return metric information for COMIDs within a specific county. Users must use the FIPS code, not county name, as a way to disambiguate counties. One of comid, county, state, or region is required unless conus='true'. If specified and valid, comid is ignored. Syntax: county=<county1>,<county1>

region

Return metric information for COMIDs within a specified hydroregion. Hydroregions are specified using full name i.e. 'Region01', 'Region03N', 'Region10L' One of comid, county, state, or region is required unless conus='true'. If specified and valid, comid, county, and state are ignored. Case-sensitive. Syntax: region=<regionid1>,<regionid2>

conus

Return all COMIDs in the conterminous United States. Character string (Not case-sensitive) or logical. The default value is false. If true, comid, county, state, and region are ignored. Values: true|false

countOnly

Return a CSV containing only the row count (ROWCOUNT) and the column count (COLUMNCOUNT) that the server expects to return in a request. The default value is false. Values: true|false

Value

A data frame of StreamCat metrics. If data are missing for all rows of a given metric, then the column for that metric will not exist. If data are missing for only some rows, then they will be specified with NA.

Author(s)

Marc Weber

Examples

## Not run: 
df <- sc_get_data(comid='179', aoi='cat', metric='fert')

df <- sc_get_data(metric='pctgrs2006', aoi='ws', region='Region01')

df <- sc_get_data(metric='pctwdwet2006', aoi='ws', county='41003')

df <- sc_get_data(metric='pcturbmd2006', aoi='wsrp100',
comid='1337420')

df <- sc_get_data(metric='pcturbmd2006,damdens',
aoi='cat,ws', comid='179,1337,1337420')

df <- sc_get_data(metric='pcturbmd2006,damdens',
aoi='cat,ws', comid='179,1337,1337420',
showAreaSqKm='true', showPctFull='true')

df <- sc_get_data(metric='pcturbmd2006,damdens',
aoi='cat,ws', comid='179,1337,1337420', countOnly='true')

df <- sc_get_data(metric='thalwagdepth', comid='179,1337,1337420', aoi='other')

df <- sc_get_data(metric='thalwagdepth', comid=c('179','1337','1337420'), aoi='other')

df <- sc_get_data(comid='179', aoi='ws', metric='all')
 
## End(Not run)

Get StreamCat Metric Names

Description

Function to filter StreamCat metrics metrics by category, area of interest, dataset or year. Use 'sc_get_params(categories)' or 'sc_get_params(datasets)' to see all the valid category or dataset options

Usage

sc_get_metric_names(category = NULL, aoi = NULL, year = NULL, dataset = NULL)

Arguments

category

Filter StreamCat metrics based on the metric category

aoi

Filter StreamCat metrics based on the area of interest

year

Filter StreamCat metrics based on a particular year or years

dataset

Filter StreamCat metrics based on the dataset name

Value

A dataframe of merics and description that match filter criteria

Author(s)

Marc Weber

Examples

## Not run: 
metrics <- sc_get_metric_names(category='Wildfire')
metrics <- sc_get_metric_names(category = c('Deposition','Climate'),
aoi=c('Cat','Ws')
metrics <- sc_get_metric_names(aoi='Other',
dataset=c('Canal Density','Predicted Channel Widths Depths'))


## End(Not run)

Get StreamCat Parameters

Description

Function to return available StreamCat parameters using the StreamCat API.

Usage

sc_get_params(param = NULL)

Arguments

param

List of available parameters in the API for the following options: name, areaofInterest, region, state, county. State and county return a data frame that includes FIPS codes, names and state abbreviations Syntax: param=<value1>,<value2> Values: name|area

Value

A list of all the current StreamCat values for a given parameter

Author(s)

Marc Weber

Examples

## Not run: 
params <- sc_get_params(param='variable_info')
params <- sc_get_params(param='metric_names')
params <- sc_get_params(param='categories')
params <- sc_get_params(param='aoi')
params <- sc_get_params(param='state')
params <- sc_get_params(param='county')
params <- sc_get_params(param='datasets')
## End(Not run)

Get NLCD Data

Description

Function to retrieve all NLCD metrics for a given year using the StreamCat API.

Usage

sc_nlcd(
  year = "2019",
  comid = NULL,
  aoi = NULL,
  showAreaSqKm = NULL,
  showPctFull = NULL,
  state = NULL,
  county = NULL,
  region = NULL,
  conus = NULL,
  countOnly = NULL
)

Arguments

year

Years(s) of NLCD metrics to query. Only valid NLCD years are accepted (i.e. 2001, 2004, 2006, 2008, 2011, 2013, 2016, 2019) Syntax: year=<year1>,<year2>

comid

Return metric information for specific COMIDs Syntax: comid=<comid1>,<comid2>

aoi

Specify the area of interest described by a metric. By default, all available areas of interest for a given metric are returned. Syntax: areaOfInterest=<value1>,<value2> Values: catchment|watershed|riparian_catchment|riparian_watershed|other

showAreaSqKm

Return the area in square kilometers of a given area of interest. The default value is false. Values: true|false

showPctFull

Return the pctfull for each dataset. The default value is false. Values: true|false

state

Return metric information for COMIDs within a specific state. Use a state's abbreviation to query for a given state. Syntax: state=<state1>,<state2>

county

Return metric information for COMIDs within a specific county. Users must use the FIPS code, not county name, as a way to disambiguate counties. Syntax: county=<county1>,<county1>

region

Return metric information for COMIDs within a specified hydroregion. Syntax: region=<regionid1>,<regionid2>

conus

Return all COMIDs in the conterminous United States. The default value is false. Values: true|false

countOnly

Return a CSV containing only the row count (ROWCOUNT) and the column count (COLUMNCOUNT) that the server expects to return in a request. The default value is false. Values: true|false

Value

A tibble of desired StreamCat metrics

Author(s)

Marc Weber

Examples

## Not run: 
df <- sc_nlcd(year='2001', aoi='cat',comid='179,1337,1337420')

df <- sc_nlcd(year='2001', aoi='ws', region='Region01')

df <- sc_nlcd(year='2001', aoi='ws', region='Region01',
countOnly=TRUE)

df <- sc_nlcd(year='2001', aoi='ws', region='Region01',
showAreaSqKm=FALSE, showPctFull=TRUE)

df <- sc_nlcd(year='2001, 2006', aoi='cat,ws',
comid='179,1337,1337420')

## End(Not run)