README.Rmd

---
title: "readme"
author: "Luke Winslow"
date: "January 29, 2018"
output: md_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

# hydrolinks R Package
Hydrologic Network Linking Data and Tools for R

[![Build Status](https://travis-ci.org/lawinslow/hydrolinks.svg?branch=master)](https://travis-ci.org/lawinslow/hydrolinks) | [![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/hydrolinks)](https://cran.r-project.org/package=hydrolinks)

## Bug reports and feedback

First things first, if you are having an issue, please consider reporting bugs and submitting feedback via the [Github Issues page](https://github.com/lawinslow/hydrolinks/issues).


## Package Description

This package provides tools for linking latitude and longitude (geopoint) data with 
hydrologic networks, such as the [U.S. Geologic Survey's National Hydrologic Dataset (NHD)](http://nhd.usgs.gov)
or the global [hydroLakes](http://www.hydrosheds.org/pages/hydrolakes) dataset. The function automates 
the access and download of these large, cumbersome datasets and provides a number of techniques for 
geographic data to the hydro networks. 

The key functionality `hydrolinks` provides
centers on three areas. 

1. Linking geopoint data (lat/lon) to mapped lakes, streams and rivers. This provides an unambigous 
ID-based link to mapped aquatic features. 

2. Providing on-demand access to mapped aquatic features based on ID. 

3. Enable traversal of the hydrologic network with full support for both lakes and streams. 


hydrolinks is available on CRAN. Please install from there. 
```{r eval=FALSE, echo=FALSE}
install.packages('hydrolinks')
```

## Example Usage

### Link to a waterbody feature

Lets say we have an observation `lakeobs1` that was taken at some point. We want to see
if there is a lake at that point, and get the information, including ID, of that lake. 

```{r eval=TRUE, echo=TRUE, warning=FALSE, include=FALSE}
library(hydrolinks)
linked_wb = link_to_waterbodies(39.086637, -120.052634, 'lakeobs1', dataset='nhdh')
```

Lo and behold, this point is over top of Lake Tahoe. We can get further information
about this lake from the mapping layer we used to link. National Hydrography Dataset
Highres (NHDH) has some other useful information included. 

```{r eval=TRUE, echo=FALSE}
print(linked_wb)
```

Now, lets generate map of the linked lake (Lake Tahoe). Using hydrolinks, we don't need
to dig through shapefiles. We can just use the ID we got from linking. 

```{r eval=TRUE, echo=TRUE, message=FALSE, warning=FALSE, results='hide'}
library(sf)
lake_poly = get_shape_by_id(linked_wb$PERMANENT_, dataset = 'nhdh', feature_type = 'waterbody')
#Simple quick viz of polygon
plot(st_geometry(lake_poly), main='Lake Tahoe', col='Dodgerblue')

```

The polygon returned is fully functional, so it could be used for 
quantiative analysis of the lake shape or location. We use the `sf` package
throughout for spatial data handling.

## Network functionality

The latest and greatest feature allows for the traversal of the hydrologic network. 
Buildling on what we did above, we can quickly grab very useful information from 
the hydrologic network. 

For example, lets grab and plot all inflows into Lake Tahoe. We will start from
the lake and traverse up the hydrologic network. We will specify a max traversal
distance of 50km to prevent the traversal from exploding (can happen with unlimited
bounds going up the network, e.g., Mississippi). 

```{r eval=TRUE, echo=TRUE, message=FALSE, warning=FALSE, results='hide'}

upstream = traverse_flowlines(50, linked_wb$PERMANENT_, direction = 'in')
upstream_shp = get_shape_by_id(upstream$PERMANENT_, dataset = 'nhdh', feature_type = 'flowline')
plot(st_geometry(upstream_shp), col='palegreen')
plot(st_geometry(lake_poly), main='Lake Tahoe', col='Dodgerblue', add=TRUE)

```

Boom! We have Tahoe and all its input tributaries. 
Again, the shape data returned are the same as from the underlying hydrologic 
network datasets, so they can be used in spatial and other analyses.