---
title: "Working with LakeCat data"
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{Working with LakeCat data}
  %\VignetteEncoding{UTF-8}{inputenc}
  %\VignetteEngine{knitr::rmarkdown}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>", 
  warning = FALSE, 
  message = FALSE
)
```

## Accessing and working with [LakeCat](https://www.epa.gov/national-aquatic-resource-surveys/lakecat-dataset)
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).  We now have functionality in the [StreamCat API](https://api.epa.gov/StreamCat/streams/metrics) for accessing and working with LakeCat data and have added functions in `StreamCatTools` to access LakeCata data in R using the API.

We can actually pull data into R from LakeCat by simply passing a URL to extract from json. We have to hard-wire parameters and are limited in the number of records returned through a `GET` request.
```{r, message=FALSE, eval=FALSE}
res <- jsonlite::fromJSON("https://api.epa.gov/StreamCat/lakes/metrics?name=pcturbmd2006&areaOfInterest=cat&comid=22538788")
res$items
```

## List LakeCat API parameters

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

```{r name_params}
library(StreamCatTools)
region_params <- lc_get_params(param='aoi')

name_params <- lc_get_params(param='metric_names')

print(paste0('region parameters are: ', paste(region_params,collapse = ', ')))
print(paste0('A selection of available LakrCat 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 <- lc_get_params(param='variable_info')
head(var_info)
```

Look up the display name or names for a metric using the `lc_fullname` function via the API
```{r fullnames}
metric='pcthbwet2016'
fullname <- lc_fullname(metric)
fullname
```

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

## 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 <- lc_get_metric_names(category = c('Anthropogenic','Natural'), aoi=c('Cat','Ws'))
head(metrics)
```

## Get Waterbody COMIDs
In this example we use the `lc_get_comid` function to find COMIDs for a set of example lake locations we load into R.`lc_get_comid` is just a simple wrapper for `get_waterbodies` in the [nhdplusTools](https://doi-usgs.github.io/nhdplusTools/) R package. We can then use the COMIDs we derive for our lake locations to get LakeCat metrics for these lakes as we show in after this.
```{r comids, warning=FALSE, message=FALSE}
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 data for COMIDs

In this example we access several variables, for several areas of interest, and for several COMIDs using the `lc_get_data` function. We'll show using both the COMIDS we derived with `lc_get_comid` function in previous chunk as well as with known COMIDS for NHDPlus waterbodies. Loads data into a tibble we can view.

```{r get_data}
df <- lc_get_data(metric='pcturbmd2006,damdens', aoi='cat,ws', comid=comids)
knitr::kable(df)
```

```{r get_data2}
df <- lc_get_data(metric='pcturbmd2006,damdens', aoi='cat,ws', comid='23783629,23794487,23812618')
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 <- lc_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 2019, just at the catchment level for several COMIDs using the `lc_nlcd` function. Loads data into a tibble we can view.

```{r get_nlcd}
df <- lc_get_nlcd(comid='23783629,23794487,23812618', year='2019', aoi='ws')
knitr::kable(df)
```

## Get lake and lake watersheds as `sf` objects

`StreamCatTools` includes a function `lc_get_watershed` that will return the watershed of any lake by COMID from an AWS S3 bucket of partitioned geoparquet files for all LakeCat lake watersheds (both on-network and off-network lakes).  The watershed requested is returned as an `sf` object and uses `duckDB` as well as optional parallelization for faster data returns and specification of a specific HUC2 if known to reduce search time. **NOTE** `lc_get_watershed` currently only returns one watershed per request. This can be used in conjunction with `nhdplusTools` function `get_waterbodies` to map lake features for which `LakeCat` metrics are requested as shown below.

```{r get_lake}
lake <- nhdplusTools::get_waterbodies(id = 19334077)
```

```{r get_watershed}
tictoc::tic()
ws <- lc_get_watershed(comid = 19334077)
tictoc::toc()
```

### Adding a HUC2 query parameter and using multi-threading speeds the process significantly
```{r get_lake_and_watershed_faster}
tictoc::tic()
ws <- lc_get_watershed(comid = 19334077, huc2 = "01",huc2_filter = "01", 
                      threads = 2,retries = 5)
tictoc::toc()
```

### View lake with watershed
```{r view_lake_watershed}
m1 <- mapview::mapview(ws, 
                       col.regions = "blue", 
                       alpha.regions = 0.1,  
                       color = "blue",
                       alpha = 0.8,
                       lwd = 2,
                       layer.name = "Watershed")


m2 <- mapview::mapview(lake, 
                       col.regions = "blue", 
                       alpha.regions = 0.5,
                       color = "blue",
                       alpha = 0.8,
                       layer.name = "Lake")


mapview::m1 + m2
```

