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

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

This vignette shows how to get a _species record table_ as returned by camtrapR's function [recordTable](https://jniedballa.github.io/camtrapR/reference/recordTable.html) starting from a camera trap data package.

## Setup

Load packages:

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

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

## Species record table

The camtrapR's function `recordTable()` generates:

> a record table from camera trap images or videos

At a certain extent the aggregation of `media` (e.g. images) into `observations` is already done in a camera trap data package.

If we consider that all observations are independent, then, it will be sufficient to run the following:

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

The function returns the same columns as the camtrapR's function `recordTable()` except for column `n`. The following mapping is applied:

column name output | description
--- | ---
`Station` | the station name as provided by argument `stationCol` (default: `locationName`). It has to be a column of `deployments`
`Species` |  `scientific_name` column in `observations`
`n` | `count` column in `observations` (number of individuals)
`DateTimeOriginal` | the `timestamp` column in `observations`
`Date` | the date from `timestamp`
`Time` | the time part from `timestamp`
`delta.time.secs` | the elapsed time in seconds between two (independent) observations
`delta.time.mins` | the elapsed time in minutes between two (independent) observations
`delta.time.hours` | the elapsed time in hours between two (independent) observations
`delta.time.days` | the elapsed time in days between two (independent) observations
`Directory` | a list with file paths as stored in column `file_path` of `media`
`FileName` | a list with file paths as stored in column `file_path` of `media`

The following remarks are both valid for camtrapR's function  `recordTable()` and the function  `get_record_table()` of this package:
1. observations are grouped by station and species
2. observations of unidentified animals are removed
2. the elapsed time of the first observation (record) of a species at a certain station is set to 0 by default

### Temporal independence

As described in [Chapter 3](https://jniedballa.github.io/camtrapR/articles/camtrapr3.html) of camtrapR documentation, we could filter observations using an adjustable criterion for temporal independence between subsequent records of the same species in an attempt to remove non-independent records. As for `recordTable()`, this is achieved via argument `minDeltaTime`, defined as the minimum time difference (in minutes) between two records of the same species at the same station which are to be considered independent. As shown above, the default is 0, causing the function to return all records.

Again, as for `recordTable()`, we provide an argument, `deltaTimeComparedTo`, to further control how independence between records is assessed. Setting it to `“lastRecord”` returns only records taken `minDeltaTime` minutes after the last record, i.e. `minDeltaTime` minutes after `timestamp` of the last recorded media file. Example with  `minDeltaTime = 60` (1 hour):

```{r example_lastRecord}
mica_dependent <- mica
mica_dependent$data$observations[4,"timestamp"] <- lubridate::as_datetime("2020-07-29 05:55:00")
get_record_table(mica_dependent, 
                 minDeltaTime = 10, 
                 deltaTimeComparedTo = "lastRecord")
```

Setting `deltaTimeComparedTo` to `“lastIndependentRecord”` returns only records taken `minDeltaTime` minutes after the last independent record, i.e. `minDeltaTime` minutes after `timestamp` of the last observation. Example with  `minDeltaTime = 60` (1 hour):

```{r example_lastIndependentRecord}
get_record_table(mica_dependent, 
                 minDeltaTime = 10, 
                 deltaTimeComparedTo = "lastIndependentRecord")
```

### Exclude some species

Similar to `recordTable()`, the function `get_record_table()` allows you also to
exclude some species. Both vernacular names and scientific names are allowed (case insensitive):

```{r example_exclude}
get_record_table(mica, exclude = c("grey heron", "Anas platyrhynchos", "mens"))
```

### Station names

The column containing the station names can also be defined by the user if the default value, `"locationName"`, is not the correct one. It has to be a valid column of  `deployments`. Here below, `locationID` is used:

```{r example_stationCol}
get_record_table(mica, stationCol = "locationID")
```

### Remove duplicates

It can happen that "duplicates" occur, e.g. when two distinct observations of the same species are made based on the same sequence of images, e.g. same species but different `lifeStage` or `sex`. You can decide what to do with these duplicates by using the argument `removeDuplicateRecords`: by default it is equal to `TRUE`. The duplicates are therefore removed.  To not remove them, set `removeDuplicateRecords` equal to `FALSE`.

Let's create an easy example with a duplicate based on `mica` datapackage:

```{r dummy_data_with_duplicates}
mica_dup <- mica
# create a duplicate at 2020-07-29 05:46:48, location: B_DL_val 5_beek kleine vijver
mica_dup$data$observations[4,"sequenceID"] <- mica_dup$data$observations$sequenceID[3]
mica_dup$data$observations[4, "deploymentID"] <- mica_dup$data$observations$deploymentID[3]
mica_dup$data$observations[4, "timestamp"] <- mica_dup$data$observations$timestamp[3]
```

Record table without duplicates:

```{r no_duplicates}
get_record_table(mica_dup)
```

Record table with duplicates:

```{r duplicates_allowed}
get_record_table(mica_dup, removeDuplicateRecords = FALSE)
```

### Use filter predicates

As for visualization and all other functions, you can select a subset of deployments by using filter predicates. E.g. to get the record table of observations for the deployments with latitude equal or higher than 51.18:

```{r example_filter_predicates_map}
get_record_table(mica, pred_gt("latitude", 51.18))
```

### Other arguments needed?

Are there other arguments of camtrapR's function `recordTable()` you think should be relevant to add to `get_camera_record()`, please let us know by posting an [issue](https://github.com/inbo/camtraptor/issues)!