intro-camtrapmonitoring.Rmd

---
title: "Introduction to camtrapmonitoring"
author: "Alec L. Robitaille"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to camtrapmonitoring}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7
)
```


<!-- ggplot2 figs with geom_sf -->

The {camtrapmonitoring} package provides functions for planning and evaluating camera
trap surveys. The recommended approach is to first sample a set of candidate 
camera trap locations larger than the intended number of locations. Next, 
these candidate locations are evaluated using spatial layers to measure their
deployment feasibility (such as distance to road) and to quantify their bias 
and coverage of project-specific characteristics (such as distribution across 
specific land cover classes). 

{camtrapmonitoring} is designed to work with modern spatial R packages: {sf} and {terra}.

```{r}
library(camtrapmonitoring)
library(sf)
library(terra)
```



## Sampling candidate camera trap locations

The `sample_ct` function returns candidate camera trap locations using 
`sf::st_sample` across the user's region of interest. Options include 
"regular", "random" or "hexagonal" sampling across the entire region of interest
or stratified by a column in the provided features. 

The example data "clearwater_lake_density" is a simulated species density 
grid near Clearwater Lake, Manitoba. It is a simple feature collection of 
polygons with a column named "density" (High, Medium, Low). 

We will randomly sample candidate camera trap locations, stratified by the 
simulated species density. 

```{r}
data("clearwater_lake_density")

plot(clearwater_lake_density, key.width = lcm(5))

pts <- sample_ct(
	region = clearwater_lake_density, 
	n = 25, 
	type = 'random', 
	strata = 'density'
)

plot(pts)
```



## Evaluating candidate camera trap locations

To evaluate candidate camera trap locations, determine each spatial layer 
required and the criteria associated with it. For example:

Deployment feasibility

- elevation
	- point sample
	- buffered point sample
- roads
	- distance to
	
Characteristics of candidate locations

- land cover
	- point sample
- hydrology
	- distance to
- wetlands
	- distance to



### Deployment feasibility

First, we will evaluate the deployment feasibility layers. Note the example
elevation data is an external TIF file that can be loaded with the
{terra} package. 

The `eval_*` family of functions return a vector of values for each candidate
camera trap location. These vectors can be added to the simple features objects
using the base R `df$name <- value` syntax (shown here) or with `dplyr::mutate`. 
`eval_*` functions take 'features' (candidate camera trap locations) and a 
'target' covariate to evaluate each candidate location with. For `eval_pt`
and `eval_buffer`, 'target' covariates are expected to be raster layers while 
`eval_dist` expects a 'target' vector object. 

```{r}
# Load data
clearwater_lake_elevation_path <- system.file('extdata', 'clearwater_lake_elevation.tif', package = 'camtrapmonitoring')
clearwater_lake_elevation <- rast(clearwater_lake_elevation_path)

data("clearwater_lake_roads")



# Evaluate elevation using point sample
pts$elev_pt <- eval_pt(features = pts, target = clearwater_lake_elevation)

# Evaluate elevation using buffered point sample
pts$elev_buffer_1e3 <- eval_buffer(
	features = pts, 
	target = clearwater_lake_elevation,
	buffer_size = 1e3
)

# Evaluate distance to roads
pts$road_dist <- eval_dist(features = pts, target = clearwater_lake_roads)



# Plot results
plot(pts)
```



### Characteristics of candidate locations

Next, we will evaluate the characteristics of candidate locations.  Note the 
example land cover data is an external TIF file that can be loaded with the
{terra} package. 

```{r}
# Load data
clearwater_lake_land_cover_path <- system.file('extdata', 'clearwater_lake_land_cover.tif', package = 'camtrapmonitoring')
clearwater_lake_land_cover <- rast(clearwater_lake_land_cover_path)

data("clearwater_lake_hydro")
data("clearwater_lake_wetlands")



# Evaluate land cover using point sample
pts$lc_pt <- eval_pt(features = pts, target = clearwater_lake_land_cover)

# Evaluate distance to hydrology
pts$hydro_dist <- eval_dist(features = pts, target = clearwater_lake_hydro)

# Evaluate distance to wetland
pts$wetland_dist <- eval_dist(features = pts, target = clearwater_lake_wetlands)



# Plot results
plot(pts)
```


## Selection from candidate camera trap locations

To select camera trap locations, define the criteria for selecting and sorting 
candidate locations. 

Criteria for selection:

- Maximum distance from roads: 3000 m
- Maximum elevation: 300 m
- Select only forest land cover classes: 1, 2, 5, 6

Criteria for sorting:

- Nearer to wetlands
- Farther from major lakes

```{r}
# Selection criteria
max_road_dist_m <- 3000
max_elev_m <- 300
ls_lc_classes <- c(1, 2, 5, 6)

# Select out of candidate points
select_pts <- pts[pts$road_dist < max_road_dist_m &
										pts$elev_pt < max_elev_m &
										pts$lc_pt %in% ls_lc_classes,]

plot(select_pts)
```

```{r}
# Sorting criteria
ordered <- order(select_pts$wetland_dist, -select_pts$hydro_dist)

order_select_pts <- select_pts[ordered,]
print(order_select_pts)
```


## Establishing camera trap grids

The function `grid_ct` allows the user to establish sampling grids around
focal locations selected above. The `grid_design` function is provided to 
the user to help explore grid layout options, using either the 'case' argument
or the 'n' argument.

```{r}
plot(grid_design(distance = 100, case = 'queen'))

plot(grid_design(distance = 100, case = 'bishop'))

plot(grid_design(distance = 100, case = 'rook'))

plot(grid_design(distance = 100, case = 'triplet'))

plot(grid_design(distance = 250, n = 13))
```

After the grid design is selected, the `grid_ct` function can be used with the
selected camera trap locations. 

```{r}
ct_grids <- grid_ct(
	features = order_select_pts,
	distance = 500,
	case = 'queen'
)

plot(ct_grids['id_grid_ct'][1])
```


## Example data sources

Example data used in the {camtrapmonitoring} package come from open data sources we 
gratefully acknowledge in the help page for each data set. Also see the "data-raw"
directory in the package source for full data preprocessing steps. 

- `?clearwater_lake_density`
- `?clearwater_lake_elevation`
- `?clearwater_lake_hydro`
- `?clearwater_lake_land_cover`
- `?clearwater_lake_roads`