---
title: "Camera operation matrix"
author: "Damiano Oldoni"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Camera operation matrix}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

This vignette shows how to get a *camera trap station operability matrix*, shortly called *camera operation matrix* as returned by camtrapR's function [cameraOperation](https://jniedballa.github.io/camtrapR/reference/cameraOperation.html).

## Setup

Load packages:

```{r load_pkgs}
library(camtraptor)
library(lubridate)
library(dplyr)
```

By loading package `camtraptor`, a camera trap data package called `mica` is made available. This data package contains camera trap data of musk rats and coypus. We will use this variable from now on.

## Camera operation matrix

You can create a camera operation matrix by passing a camera trap data package:

```{r basic_usage}
get_cam_op(mica)
```

The function will read the `deployments` slot of the data package to create the matrix.

The matrix rows are the location names, by default the values of field `locationName` of `deployments`. Column names are dates. The matrix values are: 0 if station is not active, an integer (1 or more) if one or more deployments linked to the same station are fully active during the whole day and a decimal value for partially active stations.

In the example above there was a one-to-one relation between deployments and locations: the daily effort is between 0 and 1.

In the example below we show what happens if all four deployments are set to the same location (`B_DL_val 5_beek kleine vijver`) and they are active during the same days:

```{r four_deploys_same_start_end_for_one_location}
mica1 <- mica
mica1$data$deployments$locationName <- mica1$data$deployments$locationName[1]
mica1$data$deployments$start <- mica1$data$deployments$start[1]
mica1$data$deployments$end <- mica1$data$deployments$end[1]
multiple_deploys_matrix <- get_cam_op(mica1)
multiple_deploys_matrix
```

In the example below we simulate a location (`B_DM_val 4_'t WAD`) linked to two deployments active in two different periods:

```{r two_deploys_two_periods}
mica2 <- mica
mica2$data$deployments$locationName[4] <- mica2$data$deployments$locationName[3]
mica2$data$deployments$start[4] <- mica2$data$deployments$end[3] + ddays(5)
mica2$data$deployments$end[4] <- mica2$data$deployments$start[4] + ddays(5)
mica2$data$deployments %>% dplyr::select(locationName, start, end)
```

This results in the following camera operation matrix:

```{r camOp_two_deploys_two_periods}
two_deploys_two_periods_matrix <- get_cam_op(mica2)
days_to_show <- seq(as.Date(mica2$data$deployments$start[3]),
                    as.Date(mica2$data$deployments$end[4]),
                    by = "days")
two_deploys_two_periods_matrix[3,as.character(days_to_show)]
```

### Station names

You can specify the column containing the station names instead of using the default `locationName`. In the example below we use the column `locationID`. A small preview of the matrix is shown:

```{r cam_op_with_locationID}
cam_op_with_locationID <- get_cam_op(mica, station_col = "locationID")
cam_op_with_locationID[1:4, 1:2]
```

You can also decide to use prefix `"Station"` in the station names as done by camtrapR's `cameraOperation()` by setting `use_prefix = TRUE`. A small preview of the entire matrix is shown:

```{r use_prefix}
cam_op_with_prefix <- get_cam_op(mica, use_prefix = TRUE)
cam_op_with_prefix[1:4,1:2]
```

### Session and camera IDs

You can specify the column containing the camera IDs to be added to the station names following the camtrapR's convention: `Station__CAM_CameraID`. Only the row names are shown:

```{r add_camera_IDs}
mica_cameras <- mica
mica_cameras$data$deployments$cameraID <- c(1, 2, 3, 4)
cam_op_with_camera_ids <- get_cam_op(mica_cameras, camera_col = "cameraID")
row.names(cam_op_with_camera_ids)
```

You cans also add the session IDs using `session_col` argument, following the camtrapR's convention: `Station__SESS_sessionID`:

```{r add_session_IDs}
mica_sessions <- mica
mica_sessions$data$deployments$session <- c(1, 2, 3, 4)
cam_op_with_session_ids <- get_cam_op(mica_sessions, session_col = "session")
row.names(cam_op_with_session_ids)
```

To use both camera and session IDs, the camtrapR's convention `Station__SESS_SessionID__CAM_CameraID` is followed:

```{r add_session_camera_IDs}
mica_sessions$data$deployments$cameraID <- c(1, 2, 3, 4)
cam_op_with_session_and_camera_ids <- get_cam_op(
  mica_sessions, 
  camera_col = "cameraID",
  session_col = "session"
)
row.names(cam_op_with_session_and_camera_ids)
```