---
title: "Getting Started"
output: 
  html_document:
    theme: flatly
    keep_md: yes
    number_sections: true
    highlighted: default 
    toc: yes
    toc_float:
      collapsed: no
      smooth_scroll: no
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Getting Started With StreamCatTools StreamCatTools}
  %\VignetteEncoding{UTF-8}{inputenc}
  %\VignetteEngine{knitr::rmarkdown}
---

```{r, include = FALSE}
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
```{r, message=FALSE, eval=FALSE}
library(devtools)
install_github('USEPA/StreamCatTools')
```

After installing load the library
```{r, message=FALSE}
library(StreamCatTools)
```

## Background
The `StreamCatTools` package was designed to simplify the use of [StreamCat](https://www.epa.gov/national-aquatic-resource-surveys/streamcat-dataset) data in R, leveraging the new [API for StreamCat](https://api.epa.gov/StreamCat/streams/metrics). 

## StreamCat API
We can  pull data into R from the [StreamCat API](https://usepa.github.io/StreamCatWebServices_Public/#/) 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.
```{r API}
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 via the API
```{r params}
region_params <- sc_get_params(param='aoi')

name_params <- sc_get_params(param='metric_names')

print(paste0('region parameters are: ', paste(region_params,collapse = ', ')))
print(paste0('A selection of available StreamCat metrics include: ',paste(name_params[1:10],collapse = ', ')))
```
We can also see what metrics are available for what areas of interest and what years using the `sc_get_params` function (which returns a tibble of information about StreamCat metrics):
```{r params2}
var_info <- sc_get_params(param='variable_info')
head(var_info)
```

We can look up the display name or names for a metric using the `sc_fullname` function via the API
```{r fullnames}
metric='pcthbwet2011'
fullname <- sc_fullname(metric)
fullname
```

```{r fullnames2}
metric='pctdecid2019,fert'
fullname <- sc_fullname(metric)
fullname
```

We can additionally get a data frame of state FIPS codes, abbreviations and names, and the same information for counties as well using `sc_get_params`:
```{r states}
states <- sc_get_params(param='state')
head(states)
```

```{r counties}
counties <- sc_get_params(param='county')
head(counties)
```

## Filter metric information by criteria
We can also filter metric names and information by the metric year(s), the indicator categories for metrics, the metric data set names, or the Areas of Interest the metrics are available for.
```{r get_metric_names}
metrics <- sc_get_metric_names(category = c('Deposition','Climate'),aoi=c('Cat','Ws'))
head(metrics)
```

## 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.
```{r get_data}
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. 
```{r countydata}
df <- sc_get_data(metric='pctwdwet2006', aoi='ws', county='41003')
knitr::kable(head(df))
```

## Get all metrics for COMIDs or an Area of Interest
We can also get all StreamCat metrics for a set of COMIDs or an area of interest.  **Please do not request metric='all' and aoi='conus' in order not to overload requests to the server.  Requesting metric='all' for a state or multiple states or hydroregions will also take a long time to process**.
```{r all}
df <- sc_get_data(comid='179', aoi='cat', metric='all')
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.
```{r get_nlcd}
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.
```{r get_nlcd2}
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.
```{r comids, eval=FALSE}
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.
```{r hydroregion}
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
```{r conus, eval=FALSE}
# df <- sc_get_data(metric='om', aoi='ws', conus='true')
# knitr::kable(head(df))
```