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 = "100%"
)

library(terra)
```

# fetchr <img src="man/figures/fetchr_logo_transparent.png" align="right" width="25%" />

<!-- badges: start -->
[![Dependencies](https://img.shields.io/badge/dependencies-8/07-orange?style=flat)](#)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://choosealicense.com/licenses/mit/)
<!-- badges: end -->

<div align="left">

  <p align="left">
    <a href="https://en.wikipedia.org/wiki/Wind_fetch"><strong>« Fetch »</strong></a>
    <br />
  </p>
</div>

<hr>

The goal of `fetchr` is to provide a fast and efficient raster based method for calculating fetch lengths across thousands of water grid cells. 
Calculating fetch lengths, the distance that wind can blow in a constant direction over a body of water without interruption, can be a slow and memory intensive process when done on thousands of points of interest in multiple directions. `fetchr` attempts to fix this problem and allows for thousands of fetch calculations to be performed in a fraction of the time that other methods take. 

<hr>

## Installation

You can install the development version of **`fetchr`** from [GitHub](https://github.com/anguswg-ucsb/fetchr) with:

``` r
# install.packages("devtools")
devtools::install_github("anguswg-ucsb/fetchr")
```

## Coastline raster

If we start with a raster representing the Southern California coast near Santa Barbara, CA.

```{r example}
library(fetchr)

# land raster
land_rast <- terra::rast(fetchr::land)

terra::plot(land_rast, col = "#2e8b57")
```

<br>

## Make a binary land water rasters
We can take this land raster, indicate which cells are water cells, and create a binary land water raster (land = 0, water = 1).
```{r binary_lw}
# binary land water raster 
landwater <- fetchr::get_landwater(
  r           = land_rast,                 # land raster
  water_value = NA,                        # cells with a value of NA are classified as water, all other cells are land
  res         = terra::res(land_rast)[1]   # return raster with the same cell resolution as input raster
  )

terra::plot(landwater, col = c("#2e8b57", "#add8e6"))
```

This raster now meets all the specification for using `get_fetch()`:

  - Binary cell values (land cells = 0 and water cells = 1)
  - Projected Coordinate Reference System
  - Regular grid cell size (same x and y cell resolution)

<br>

## Calculate fetch length
Internally, `get_fetch()` will coerce polygon/multipolygon geometries and rasters into the required binary landwater raster. It is recommended to provide either an `sf`/`terra` polygon or a `raster`/`terra` raster with a single value for land cells and NA values for water cells. To calculate fetch distances, we can simply provide an `sf`/`terra` polygon or `raster`/`terra` raster to `get_fetch()`
```{r fetch_calc}
system.time(
  
  fetch <- fetchr::get_fetch(
    r           = land_rast,     # binary land water raster
    max_dist    = 200000,        # maximum distance to calculate fetch in meters (200km)
    in_parallel = TRUE,          # run calculations in parallel
    verbose     = TRUE
    )
  
)

plot(fetch)
```

In this example here, my machine calculated fetch distances for > 24,000 water cells in about ~3 seconds, or ~0.00014 seconds per point. That is a  ~99.99% reduction in computation time compared to various other polygon based methods out there!

<br>

## Multidirectional fetch calculations
The `get_fetch_directions()` function allows you to get get individual fetch distances in 8 directions: 
```{r multi_fetch_calc}
multi_fetch <- fetchr::get_fetch_directions(
  r           = land_rast,     # binary land water raster
  max_dist    = 200000,        # maximum distance to calculate fetch in meters (200km)
  in_parallel = TRUE,          # run calculations in parallel
  verbose     = TRUE
  )

plot(multi_fetch)
```