README.Rmd

---
output: github_document
---

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

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  dpi = 150
)
```
# isoband <img width="120px" alt="isoband logo" align="right" src="man/figures/isoband-logo.png">

[![CRAN status](https://www.r-pkg.org/badges/version/isoband)](https://cran.r-project.org/package=isoband)
[![Build Status](https://travis-ci.org/wilkelab/isoband.svg?branch=master)](https://travis-ci.org/wilkelab/isoband)
[![Coverage Status](https://img.shields.io/codecov/c/github/wilkelab/isoband/master.svg)](https://codecov.io/github/wilkelab/isoband?branch=master)


Generate contour lines (isolines) and contour polygons (isobands) from regularly spaced grids containing elevation data.
  
## Installation

Install the latest official release from CRAN via:
``` r
install.packages("isoband")
```

Install the current development from github via:
``` r
remotes::install_github("wilkelab/isoband")
```

## Examples

The two main workhorses of the package are the functions `isolines()` and `isobands()`, respectively. They return a list of isolines/isobands for each isolevel specified. Each isoline/isoband consists of vectors of x and y coordinates, as well as a vector of ids specifying which sets of coordinates should be connected. This format can be handed directly to `grid.polyline()`/`grid.path()` for drawing. However, we can also convert the output to spatial features and draw with ggplot2 (see below).

```{r basic-example}
library(isoband)

m <- matrix(c(0, 0, 0, 0, 0,
              0, 1, 2, 1, 0,
              0, 1, 2, 0, 0,
              0, 1, 0, 1, 0,
              0, 0, 0, 0, 0), 5, 5, byrow = TRUE)

isolines(1:ncol(m), 1:nrow(m), m, 0.5)

isobands(1:ncol(m), 1:nrow(m), m, 0.5, 1.5)
```

The function `plot_iso()` is a convenience function for debugging and testing.
```{r basic-example-plot, fig.asp = 1, out.width = "50%"}
plot_iso(m, 0.5, 1.5)
```

The isolining and isobanding algorithms have no problem with larger datasets. Let’s calculate isolines and isobands for the volcano dataset, convert to sf, and plot with ggplot2.

```{r volcano, fig.asp = 1, out.width = "50%"}
library(ggplot2)
library(sf)

m <- volcano
b <- isobands((1:ncol(m))/(ncol(m)+1), (nrow(m):1)/(nrow(m)+1), m, 10*(9:19), 10*(10:20))
l <- isolines((1:ncol(m))/(ncol(m)+1), (nrow(m):1)/(nrow(m)+1), m, 10*(10:19))

bands <- iso_to_sfg(b)
data_bands <- st_sf(
  level = 1:length(bands),
  geometry = st_sfc(bands)
)
lines <- iso_to_sfg(l)
data_lines <- st_sf(
  level = 2:(length(lines)+1),
  geometry = st_sfc(lines)
)

ggplot() +
  geom_sf(data = data_bands, aes(fill = level), color = NA, alpha = 0.7) +
  geom_sf(data = data_lines, color = "black") +
  scale_fill_viridis_c(guide = "none") +
  coord_sf(expand = FALSE)
```