summarize.Rmd

---
title: "Summarize data"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Summarize data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

This vignette demonstrates how this package can be used to summarize camera trap data.

```{r setup, message=FALSE, results='hide'}
library(camtrapviz)
library(dplyr)
```

## Import and prepare data

```{r}
data(recordTableSample, package = "camtrapR")
data(camtraps, package = "camtrapR")
```

```{r}
recordTableSample$DateTimeOriginal <- as.POSIXct(recordTableSample$DateTimeOriginal)
recordTableSample$Date <- as.Date(recordTableSample$Date)
recordTableSample$Time <- chron::times(recordTableSample$Time)

camtraps$Setup_date <- as.Date(camtraps$Setup_date, format = "%d/%m/%Y")
camtraps$Retrieval_date <- as.Date(camtraps$Retrieval_date, format = "%d/%m/%Y")
```

## Camera information

We can summarize the camera sampling with the function `summarize_cameras`. The start and end dates are taken from the data and the sampling length is computed using the `cameraOperation` matrix from the `camtrapR` package.

If we provide only the observation dataframe, sampling will be computed from first and last picture.

```{r}
camsum <- summarize_cameras(recordTableSample,
                            cam_col = "Station",
                            date_col = "Date",
                            time_col = "Time")
knitr::kable(camsum)
```

The summary table has the following columns:

-   The first column is named as the cameras ID column (here `Station`) and contains cameras ID.
-   `pictures` is the number of pictures caught on each camera.
-   `sampling_length` is the length of the sampling period in days (computed with the `cameraOperation` function from the `camtrapR` package).
-   `setup` contains the start of the sampling for each camera.
-   `retrieval` contains the end of the sampling for each camera.
-   `setup_origin` containing the method used to determine the start of the sampling (possible values are `picture` or `setup`).
-   `retrieval_origin` containing the method used to determine the end of the sampling (`picture` or `setup`).

If we add the species column with the `spp_col` argument, a column `species` is added to the summary (it contains the number of species caught on each camera).

```{r}
camsum <- summarize_cameras(recordTableSample,
                            cam_col = "Station",
                            date_col = "Date",
                            time_col = "Time",
                            spp_col = "Species")
knitr::kable(camsum)
```

If we provide the cameras dataframe, whenever possible the sampling information will be obtained from setup and retrieval columns.

```{r}
camsum <- summarize_cameras(recordTableSample,
                            cam_col = "Station",
                            date_col = "Date",
                            time_col = "Time",
                            spp_col = "Species",
                            dfcam = camtraps, 
                            cam_col_dfcam = "Station", 
                            setup_col = "Setup_date",
                            retrieval_col = "Retrieval_date")
knitr::kable(camsum)
```

If some information is missing from the camera dataframe, then the information from the observations will be used.

```{r}
cam_missing <- camtraps
cam_missing$Retrieval_date[cam_missing$Station == "StationA"] <- NA

knitr::kable(cam_missing |> 
               select(Station, Setup_date, Retrieval_date))
```

```{r}
camsum <- summarize_cameras(recordTableSample,
                            cam_col = "Station",
                            date_col = "Date",
                            time_col = "Time",
                            spp_col = "Species",
                            dfcam = cam_missing, 
                            cam_col_dfcam = "Station", 
                            setup_col = "Setup_date",
                            retrieval_col = "Retrieval_date")
knitr::kable(camsum)
```

## Species information

We can also summarize the species sightings with the function `summarize_species`.

```{r}
sppsum <- summarize_species(recordTableSample,
                            spp_col = "Species", 
                            cam_col = "Station")
knitr::kable(sppsum)
```

The summary table has the following columns:

-   the first column is named as the species column (here `Species`) and contains species name
-   `sightings` is the number of sightings of the species (corresponding to row count in the data)
-   `individuals` takes into account the information from the counting column (if provided). Else, it is the same as `sightings`.
-   `n_cameras` gives the number of cameras the species was observed on.
-   `prop_cam` gives the proportion of cameras the species was observed on.

We can also include the count information:

```{r}
with_count <- recordTableSample |> 
  mutate(count = 3)
sppsum <- summarize_species(with_count,
                            spp_col = "Species", 
                            cam_col = "Station", 
                            count_col = "count")
knitr::kable(sppsum)
```

If any of the count data is `NA`, it is possible to provide a value to replace it:

```{r}
with_count_NA <- with_count |> 
  mutate(count = ifelse(Species == "PBE", NA, count))

sppsum <- summarize_species(with_count_NA,
                            spp_col = "Species", 
                            cam_col = "Station", 
                            count_col = "count",
                            NA_count_placeholder = 1)

knitr::kable(sppsum)
```

If `obstype_col` is included, the final table will have one more column describing type and the values will be summarized by `species_col` and `obstype_col`.

```{r}
with_obstype <- recordTableSample |> 
  mutate(type = "animal")
with_obstype <- rbind(with_obstype,
                      c(rep(NA, 11), "human"))
with_obstype <- rbind(with_obstype,
                      c(rep(NA, 11), "fire"))

sppsum <- summarize_species(with_obstype,
                            spp_col = "Species", 
                            cam_col = "Station", 
                            obstype_col = "type")
knitr::kable(sppsum)
```

## Summarize per species and cameras

It is also possible to summarize the information per species and camera using the argument `by_cam` in the `summarize_species` function:

```{r}
bycam <- summarize_species(recordTableSample,
                           spp_col = "Species", 
                           cam_col = "Station",
                           by_cam = TRUE)
knitr::kable(bycam)
```

Then, we obtain a table with one row per species and camera. The four first columns are the same as without the `by_cam` option, but the following rows differ:

-   `sightings_prop` is the proportion of sightings of a given species at a given camera

-   `individuals_prop` is the proportion of individuals of a given species at a given camera

When providing additional information on cameras sampling (typically obtained with `summarize_cameras`), the relative abundance index can also be computed.

```{r}
camsum <- summarize_cameras(recordTableSample,
                            cam_col = "Station",
                            date_col = "Date",
                            time_col = "Time")
```

```{r}
bycam_RAI <- summarize_species(recordTableSample,
                           spp_col = "Species", 
                           cam_col = "Station",
                           dfcam = camsum,
                           by_cam = TRUE)
knitr::kable(bycam_RAI)
```

When `dfcam` is provided, there are three additional columns:

-   `sightings_RAI`: relative abundance index for species' sightings at each camera. It is computed as the number of sightings over the sampling duration (it represents the number of sightings per time unit).

-   `individuals_RAI`: the same as `sightings_RAI`, but computed as the number of individuals over the sampling duration.

-   `sampling_length` containing the sampling duration for each camera