In USEPA/StreamCatTools: Tools to work with the StreamCat API within R and access the full suite of StreamCat and LakeCat metrics

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>", 
  warning = FALSE, 
  message = FALSE
)

Installing and loading StreamCatTools

To install, currently you need to install from GitHub using devtools

library(devtools)
install_github('USEPA/StreamCatTools')

After installing load the library

library(StreamCatTools)

Background

The StreamCatTools package was designed to simplify the use of StreamCat data in R, leveraging the new API for StreamCat.

StreamCat API

We can pull data into R from the StreamCat API by simply passing a URL to extract from json. We have to hard-wire parameters though and are limited in the number of records returned through a GET request.

res <- jsonlite::fromJSON("https://api.epa.gov/StreamCat/streams/metrics?name=fert&areaOfInterest=cat&comid=179")
res$items

List API parameters

List StreamCat parameters: Get a list of available StreamCat values for certain parameters using the sc_get_params function (right now just metric names and areas of interest for this function) via the API

region_params <- sc_get_params(param='areaOfInterest')

name_params <- sc_get_params(param='name')

print(paste0('region parameters are: ', paste(region_params,collapse = ', ')))
print(paste0('A selection of available StreamCat metrics include: ',paste(name_params[1:10],collapse = ', ')))

Look up the display name or names for a metric using the sc_fullname function via the API

metric='pcthbwet2011'
fullname <- sc_fullname(metric)
fullname

metric='pctdecid2019,fert'
fullname <- sc_fullname(metric)
fullname

Get data for COMIDs

In this example we access several variables, for several areas of interest, and for several COMIDs using the sc_get_data function. Loads data into a tibble we can view.

df <- sc_get_data(metric='pcturbmd2006,damdens,tridens', aoi='rp100cat,cat,ws', comid='179,1337,1337420')
knitr::kable(df)

Get data for county

In this example we access a couple variables at the watershed scale for the area of interest of a county (Benton County in this case) using the sc_get_data function.

df <- sc_get_data(metric='pctwdwet2006', aoi='ws', county='41003')
knitr::kable(head(df))

Get NLCD data

In this example we access National Land Cover Dataset (NLCD) data for 2001, just at the catchment level for several COMIDs using the sc_nlcd function. Loads data into a tibble we can view.

df <- sc_nlcd(year='2001', aoi='cat',
              comid='179,1337,1337420')
knitr::kable(df)

We can also pass a couple years for a different area of interest for another region like a county.

df <- sc_nlcd(year='2006, 2019', aoi='ws',
              county='41003')
knitr::kable(head(df))

Get COMIDs

In this example we use the sc_get_comid function to find COMIDs for USGS stream gages we load into R. We use a .csv file with coordinate columns and a known coordinate reference system.

gages = readr::read_csv(system.file("extdata","Gages_flowdata.csv", package = "StreamCatTools"),show_col_types = FALSE)
# we'll just grab a few variables to keep things simple
gages <- gages[,c('SOURCE_FEA','STATION_NM','LON_SITE','LAT_SITE')]
gages_coms <- sc_get_comid(gages, xcoord='LON_SITE',                   ycoord='LAT_SITE', crsys=4269)

# Add the COMID we found back to gages data frame
gages$COMID <- strsplit(gages_coms, ",")[[1]]
df <- sc_get_data(metric='huden2010', aoi='ws', comid=gages_coms)
df$COMID <- as.character(df$comid)
gages <- dplyr::left_join(gages, df, by='COMID')
knitr::kable(head(gages))

Get data for a hydroregion

In this example we access a couple watershed-only metrics for a particular NHDPlus hydroregion using the sc_get_data function.

df <- sc_get_data(metric='pctwdwet2006', aoi='ws', region='Region17')
knitr::kable(head(df))

Get data for CONUS

In this example we access a metric for conus using the sc_get_data function - this is shown for demonstration but not run as it takes a bit of time

# df <- sc_get_data(metric='om', aoi='ws', conus='true')
# knitr::kable(head(df))

USEPA/StreamCatTools documentation built on Feb. 23, 2025, 12:53 a.m.