---
title: "wdnr.gis-Introduction"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{wdnr_gis-intro}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

<img src='../man/figures/logo.png' width="160" height="180" style="border: none; float: right"/>

\
\

wdnr.gis is a package for pulling data from the Wisconsin Department of
Natural Resources (WDNR) ArcGIS REST API sites, which are located [here](https://dnrmaps.wi.gov/arcgis/rest/services) and [here](https://dnrmaps.wi.gov/arcgis2/rest/services). There are a wide variety 
of services and layers on these sites, and this package helps to make sense of
and use these data.

\
\

```{r setup, eval = TRUE}
library(wdnr.gis)
```

Notice that dependency packages arcpullr and sf are loaded along 
with wdnr.gis. These are essential packages that are used to pull data
from an ArcGIS REST API and convert them to an sf object in R. All other
functions in wdnr.gis are just wrappers around functions within 
arcpullr and sf that are specific to WDNR's ArcGIS REST API.

\
\

# Pulling Specific Feature Layers

There are a handful of functions that are written specifically to query certain
commonly used layers by using either a spatial or a SQL query. The querying is
mostly built in to these functions, but advanced querying functionality is also
available.

```{r, warning = FALSE}
mke_cty_streams <- get_hydro_layer(county = "milwaukee")
```

You can also pass an sf object to these get_*_layer functions. This example just
shows how to query the watershed that a particular point falls in and the
streams within that watershed

```{r, warning = FALSE}
pt <- sf_point(c(-90.8, 43.4))
watershed <- get_watershed_layer(sf_object = pt, huc_level = "HUC_8")
streams <- get_hydro_layer(sf_object = watershed)
```

Current functions that query specific WDNR layers are `get_hydro_layer`, 
`get_watershed_layer`, `get_fmdb_site_layer`, and `get_roads_layer`. Others are 
available upon request. If you have a layer that you use a lot, email us with a 
request for a layer specific function and we can add it in (especially if it 
will be useful to many others as well).

\
\

# Pulling Specific Map and Image Layers

These functions work similarly to the other specific feature layer functions, 
but they query the WDNR's map and image services instead and return a raster.

To get landcover data use the `get_wis_landcover` function. For aerial imagery
use the `get_wis_imagery` function.

```{r}
portage_lc <- get_wis_landcover(county = "portage")
plot_layer(portage_lc)
```

The specific landcover service to be queried can be altered using the `service`
argument. A full list of available services can be found by running 
`list_services(section = "DW_Land_Cover")`.


```{r}
portage_imagery <- get_wis_imagery(county = "portage")
plot_layer(portage_imagery)
```

Similar to `get_wis_landcover` the service to be queried can be altered using
the `service` argument. A full list of available image services can be found by 
running  `list_services(section = "DW_Image")`.

\
\

# Finding Sections, Services, and Layers

ArcGIS REST APIs are hierarchical in nature. There are one or more folders, each
of which contain one or more services. Within services are one or more layers 
and perhaps sub-layers. The layers contain the data of interest, but we've built
in functions to be able to find any of the folders, services, or layers 
using the following functions:
 
```{r, eval = TRUE}
match_sections("trout")
match_services("trout")
match_layers("trout stream")
```

There are also functions to find specific sections, services, and layers when 
the name is known. These are most useful when trying to obtain a URL for a 
specific layer.

```{r, eval = TRUE}
list_services("FM_Trout")
```

These functions are most useful when combined for finding specific layers and 
the associated URLs.

```{r, eval = TRUE}
list_layers(services = match_services("trout.*stream"))
list_urls(layers = match_layers("trout.*stream"))
```

Notice the use of regular expressions in the `list_urls` function.