README.Rmd

---
output: github_document
---

<!-- badges: start -->
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-green.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![CRAN status](https://www.r-pkg.org/badges/version/distanceto)](https://cran.r-project.org/package=distanceto)
[![R-CMD-check](https://github.com/robitalec/distance-to/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/robitalec/distance-to/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
  
# distance-to

## Overview

The `distanceto` package is designed to quickly sample distances from points
features to other vector layers. Normally the approach for calculating distance 
to (something) involves generating distance surfaces using raster based approaches 
eg. `raster::distance` or `gdal_proximity` and subsequently point sampling these 
surfaces. Since raster based approaches are a costly method that frequently leads
to memory issues or long and slow run times with high resolution data or large 
study sites, we have opted to compute these distances using vector based 
approaches. As a helper, there's a decidedly low-res raster based approach for 
visually inspecting your region's distance surface. But the workhorse is 
`distance_to`. See the [Example](#example). 


## Install
```{r, eval = FALSE}
install.packages('distanceto', repos = 'https://robitalec.r-universe.dev')
```


## Example
```{r}
library(distanceto)
library(sf)

# Load nc data
nc <- st_read(system.file("shape/nc.shp", package="sf"))

# Set number of sampling points
npts <- 1e3

# Sample points in nc
ncpts <- st_sample(nc, npts)

# Select first 5 of nc
ncsub <- nc[1:5,]

# Measure distance from ncpts to first 5 of nc
dists <- distance_to(ncpts, ncsub, measure = 'geodesic')

head(dists, 30)

# Add to ncpts
ncpts$dist <- dists
```



## Other approaches

* `nngeo::st_nn`
* `gdal_proximity`
* `raster::distance`
* GUI GIS applications