Type: Package
Title: StreamCat Tools
Version: 0.6.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.2
License: CC0
NeedsCompilation: no
Packaged: 2025-08-27 21:01:13 UTC; mweber
Author: Marc Weber [aut, cre], Ryan Hill [ctb], Travis Hudson [ctb], Allen Brookes [ctb], David Rebhuhn [ctb], Zachary Smith [ctb]
Maintainer: Marc Weber <weber.marc@epa.gov>
Repository: CRAN
Date/Publication: 2025-09-02 20:40:02 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



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)

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


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)

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


params <- lc_get_params(param='variable_info')
params <- lc_get_params(param='metric_names')
params <- lc_get_params(param='areaOfInterest')
params <- lc_get_params(param='state')
params <- lc_get_params(param='county')

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



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')

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



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::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)

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


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')

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


params <- sc_get_params(param='variable_info')
params <- sc_get_params(param='metric_names')
params <- sc_get_params(param='areaOfInterest')
params <- sc_get_params(param='state')
params <- sc_get_params(param='county')

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


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')