Skip to contents

Getting Started

Source: vignettes/Introduction.Rmd
Introduction.Rmd

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

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
#>   fertws fertcat comid
#> 1  1.438   1.438   179

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 = ', ')))
#> [1] "region parameters are: cat, catrp100, other, ws, wsrp100"
print(paste0('A selection of available StreamCat metrics include: ',paste(name_params[1:10],collapse = ', ')))
#> [1] "A selection of available StreamCat metrics include: agkffact, al2o3, BankfullDepth, BankfullWidth, bfi, canaldens, cao, cbnf, CHEM_V2_1, clay"

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
#> [1] "Herbaceous Wetland Percentage 2011"
metric='pctdecid2019,fert'
fullname <- sc_fullname(metric)
fullname
#> [1] "Deciduous Forest Percentage 2019"                   
#> [2] "Synthetic Nitrogen Fertilizer Application Mean Rate"

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)
comid damdenscat damdensws tridensws tridenscat pcturbmd2006cat pcturbmd2006ws
179 0 0.0000 0 0 0.00 0.00
1337 0 0.0000 0 0 0.07 0.07
1337420 0 0.0329 0 0 0.00 0.01

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))
comid pctwdwet2006ws
23762961 1.11
23762985 0.84
23762915 1.14
23762959 1.14
23762967 1.10
23762761 1.72

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)
comid pcturbhi2001cat pctgrs2001cat pctwdwet2001cat pctcrop2001cat pctow2001cat pcthbwet2001cat pctbl2001cat pctice2001cat pctmxfst2001cat pcturblo2001cat pcturbmd2001cat pcthay2001cat pctconif2001cat pctshrb2001cat pcturbop2001cat pctdecid2001cat
179 0 0.23 36.89 1.52 0.0 1.95 0.00 0 48.76 0.00 0 1.22 4.89 0.73 0.00 3.82
1337 0 1.60 20.75 0.00 0.1 0.56 0.28 0 51.55 0.24 0 2.83 5.65 0.66 3.98 11.79
1337420 0 0.87 0.95 0.00 0.0 1.64 0.00 0 3.77 0.40 0 0.11 4.06 3.38 1.77 83.06

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))
comid pctbl2019ws pctconif2019ws pctcrop2019ws pctdecid2019ws pctgrs2019ws pcthay2019ws pcthbwet2019ws pctice2019ws pctmxfst2019ws pctow2019ws pctshrb2019ws pcturbhi2019ws pcturblo2019ws pcturbmd2019ws pcturbop2019ws pctwdwet2019ws pctice2006ws pctmxfst2006ws pctcrop2006ws pcthay2006ws pcturbop2006ws pctbl2006ws pctconif2006ws pctwdwet2006ws pctgrs2006ws pcturbhi2006ws pcturbmd2006ws pctshrb2006ws pcthbwet2006ws pctdecid2006ws pcturblo2006ws pctow2006ws
23762961 0.01 36.68 4.65 1.03 1.51 33.28 3.44 0 7.32 0.08 3.99 0.10 1.69 0.30 3.46 2.46 0 5.85 3.00 35.58 3.44 0.01 26.93 1.11 5.74 0.09 0.23 10.78 4.79 0.66 1.67 0.11
23762985 0.00 51.52 1.58 1.03 2.21 20.06 0.84 0 9.14 0.04 6.06 0.05 1.46 0.24 4.60 1.18 0 7.16 1.05 21.16 4.62 0.01 37.51 0.84 8.44 0.04 0.19 15.78 1.22 0.51 1.44 0.04
23762915 0.01 55.83 0.01 1.58 2.74 6.60 0.40 0 18.61 0.05 7.45 0.01 0.60 0.14 4.65 1.33 0 19.10 0.01 6.87 4.63 0.01 49.77 1.14 4.71 0.01 0.12 11.15 0.58 1.27 0.58 0.05
23762959 0.01 36.29 4.66 1.02 1.50 33.72 3.51 0 7.24 0.09 3.95 0.10 1.68 0.30 3.43 2.51 0 5.79 3.02 36.01 3.41 0.01 26.64 1.14 5.68 0.09 0.23 10.66 4.88 0.66 1.66 0.12
23762967 0.01 38.81 3.54 1.04 1.60 31.71 3.49 0 7.53 0.09 4.30 0.09 1.65 0.29 3.40 2.47 0 5.98 2.42 33.49 3.39 0.01 28.48 1.10 6.20 0.08 0.23 11.36 4.86 0.64 1.64 0.13
23762761 0.00 57.44 0.40 1.90 3.08 2.45 0.27 0 20.77 0.01 6.65 0.00 0.31 0.07 4.89 1.76 0 19.15 0.05 2.84 4.91 0.00 38.13 1.72 7.95 0.00 0.04 23.53 0.31 1.06 0.29 0.01

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))
comid pctwdwet2006ws
22988611 0.99
24114311 0.29
24114309 0.27
24116239 0.42
22988639 0.00
22988711 0.02

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