README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "40%",
  eval = TRUE
)

library(AOI)
library(sf)
```

# AOI <img src="man/figures/logo.png" width=130 height = 150 align="right" />

<!-- badges: start -->
[![DOI](https://zenodo.org/badge/158620263.svg)](https://zenodo.org/badge/latestdoi/158620263)
[![R CMD Check](https://github.com/mikejohnson51/AOI/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/mikejohnson51/AOI/actions/workflows/R-CMD-check.yaml)
[![Dependencies](https://img.shields.io/badge/dependencies-6/33-orange?style=flat)](#)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://choosealicense.com/licenses/mit/)
[![codecov](https://codecov.io/github/mikejohnson51/AOI/branch/master/graph/badge.svg?token=C8B30HSTMU)](https://codecov.io/github/mikejohnson51/AOI)
<!-- badges: end -->

AOI helps  create reproducible, programmatic boundaries for analysis and mapping workflows. The package targets five main use cases:

## 1. Term based geocoding

AOI uses `tidygeocoder` as a backend for term-based geooding and Wikipedia APIs. If you have more ridgid addresses `tidygeocoder` is great!

### Foward (from name to location)

#### Places
```{r}
geocode(c('Colorado State University', "University of Colorado", 'NOAA'))
```

#### Addresses
```{r}
# Address with POINT representation
geocode('500 Linden St, Fort Collins, CO 80524', pt = TRUE) 
```

####  Events

```{r}
# Single events
geocode(event = 'D-day')

# Multi-location events with BBOX
(harvey = geocode(event = 'Hurricane Harvey', bb = TRUE))

mapview::mapview(harvey)
```

### Reverse (from location to term)

```{r}
geocode_rev(c(37, -119))
```

### 2. Consistent queries for domestic (USA) and international boundaries: 

#### State / Multi-state

```{r}
aoi_get(state = c("CO", "UT"))
```

#### USA Counties

```{r}
aoi_get(state = "TX", county = "Harris")
```

#### World Countries

```{r}
aoi_get(country = "Ukraine")
```

#### USA and World Regions 

```{r}
World_asia = aoi_get(country = "Asia")
aoi_describe(World_asia)


USA_south = aoi_get(state = "south")
aoi_describe(USA_south)
```

### 3. Creating flexible AOIs from locations and bounding dimensions. 

#### Place Name and diminsions

```{r}
# 100 square mile region around Longs Peaks
aoi_ext("Long Peaks", wh = 10)
```

#### Location and Diminsions

```{r}
# 200 square mile region around 37,-119
aoi_ext(xy = c(x = 119, y = 37), wh =  c(20, 10))
```

#### Event and Diminsions

```{r}
# 10,000 square meter region around Normandy Landings
aoi_ext(geo = "white house", wh = 10000, bbox = TRUE) |> 
  st_as_sf() |>
  aoi_map(returnMap = T)
```

### 4. View and Draw

**NOTE**: The following functions require leaflet, shiny and leaflelt.extras. Since these are Suggested Dependencies you will need to install them yourself in warnings appear.

Sometimes it is useful to view the created AOIs. `aoi_map` offers a quickly formatted `leaflet` map (not all that dissimilar from `mapview` so this may retire).

```{r}
AOI = geocode(geo = c("Paris", "Amsterdam", "Prague", "England"), pt = TRUE) 
aoi_map(AOI, returnMap = TRUE)

```

Alternatively sometimes users need very specific AOIs that are not POINTs,  bounding boxes, or fiat boundaries. For this AOI provides `aoi_draw()` which allows users to interactively draw an Area of Interest (AOI) using a shiny app.
Once an object is drawn and the "Save AOI" button pressed, a new `sf` object called 'aoi' will appear in your environment.

```{r, eval = FALSE, out.width="100%"}
aoi_draw()
```

```{r, echo = FALSE, out.width="75%", fig.cap="Using the aoi_draw() interface"}
knitr::include_graphics('man/figures/shiny-app.png')
```

### 5. Programmatic way to interface with other R packages that require user defined AOIs or bounding boxes

The need for AOI's is rampant in the r-spatial community. AOI plays nicely with the following non-exhaustive list helping users be to the meat of their utilities without getting hung up on boundary definition.


| package  | 
|---|
| ggmap  |     
| nhdplusTools  |   
| elevatr  |   
| terrainr  | 
| climateR  |   
| dataRetrivial  |   
| soilDB  |    
| nwmTools  |   
| FedData  |   
| hereR  |   


Please add more!

### Installation:

```{r, eval = FALSE }
remotes::install_github("mikejohnson51/AOI")
```


### Support:

AOI has been supported with funds from the [UCAR COMET program][15] (2018-2019) and the [NSF Convergence Accelerator Project][16] (2020).


[1]:	https://travis-ci.org/mikejohnson51/AOI
[2]:	https://coveralls.io/r/mikejohnson51/AOI?branch=master
[3]:	https://zenodo.org/badge/latestdoi/139353238
[4]:    https://github.com/mikejohnson51/AOI/actions
[5]:    https://www.repostatus.org/#active
[12]:	https://mikejohnson51.github.io
[15]:	http://www.comet.ucar.edu
[16]:	https://nsf.gov/awardsearch/showAward?AWD_ID=1937099&HistoricalAwards=false


[image-1]:	https://travis-ci.org/mikejohnson51/AOI.svg?branch=master
[image-2]:	https://img.shields.io/coveralls/github/mikejohnson51/AOI.svg
[image-3]:	https://zenodo.org/badge/139353238.svg
[image-4]:  https://github.com/mikejohnson51/AOI/workflows/R-CMD-check/badge.svg
[image-5]:  https://www.repostatus.org/badges/latest/active.svg