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

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

This vignette shows how to use function `map_dep()` to visualize important deployment features on a leaflet map: 

- number of identified species
- number of observations
- RAI (Relative Abundance Index)
- effort (duration of a deployment)

## Setup

Load packages:

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

This load automatically a camera trap data package, `mica`, containing camera trap data about musk rat and coypu. We will use this variable from now on.

## Get taxonomic information

As some features must or could be used in combination with a species name, it's sometimes useful to have an idea first about which species have been detected and the correspondent vernacular names if present:

```{r species_list}
get_species(mica)
```

## Create maps

### Basic usage

#### Number of species

You can visualize the number of species detected by each deployment by using the function `map_dep()` with `feature` argument set to `n_species`:

```{r visualize_n_species_with_clusters_and_default_hover_col}
map_dep(mica,
        feature = "n_species")
```

#### Number of observations

To visualize the number of observations, set `feature` = `n_obs`:

```{r visualize_n_obs_with_clusters_and_default_hover_col}
map_dep(mica,
        feature = "n_obs")
```

You can also specify which species you want to calculate the number of observations:

```{r visualize_n_obs_species}
map_dep(mica,
        feature = "n_obs",
        species = "Anas platyrhynchos")
```

Notice how zero values are also visualized by a specific icon for ease detection. By default a black multiplication symbol `×`.

You can filter by sex:

```{r filter_sex}
map_dep(
  mica,
  "n_obs",
  species = "Anas platyrhynchos",
  sex = c("female", "unknown")
)
```

and life stage:

```{r filter_life_stage}
map_dep(
  mica,
  "n_obs",
  life_stage = c("unknown", "subadult")
)
```

#### Number of individuals

To visualize the number of observed individuals, set `feature` = `n_individuals`:

```{r visualize_n_individuas_with_clusters_and_default_hover_col}
map_dep(mica,
        feature = "n_individuals")
```

As for observations, you can specify a species:

```{r specify_species_individuals}
map_dep(mica,
        feature = "n_individuals",
        species = "Anas platyrhynchos")
```

and filter by sex and/or life stage:


```{r filter_sex_individuals}
map_dep(
  mica,
  "n_individuals",
  species = "Anas platyrhynchos",
  sex = c("female", "unknown")
)
```

#### RAI

To visualize the Relative Abundance Index (RAI) for a species, set `feature` = `rai` and specify a species using its scientific name:

```{r visualize_rai_with_clusters_and_default_hover_col}
map_dep(mica,
        feature = "rai",
        species = "Anas platyrhynchos")
```

**Notice that in this package the RAI is normalized over a deployment activity period of 100 days.**

As for number of observations and number of individuals, you can  filter by sex and/or life stage:

```{r filter_sex_rai}
map_dep(
  mica,
  "rai",
  species = "Anas platyrhynchos",
  sex = c("female", "unknown")
)
```

Common names are allowed as values of `species` as well:

```{r common_name}
map_dep(mica,
        feature = "rai",
        species = "great herons")
```

Values of `species` are also interpreted case insensitive:

```{r arg_species_case_insensitive}
map_dep(mica,
        feature = "rai",
        species = "CastoR FIBer")
```

If `species` is not specified or is wrong, an informative error message listing all valid values is returned:

```{r see_error_message, error = TRUE}
map_dep(mica,
          feature = "rai",
          species = "This is not a species name")
```

#### RAI (individuals)

You can also visualize the RAI based on number of detected individuals instead of the standard RAI which is based on the number of observations. Set `feature = "rai_individuals"`:

```{r show_rai_individuals}
map_dep(mica,
        feature = "rai_individuals",
        species = "Anas platyrhynchos")
```

Everything described in previous section about visualizing RAI holds true for RAI based on individuals as well.

#### Effort

Visualize duration of the deployments, also called _effort_, as number of active hours:

```{r effort_in_hours}
map_dep(mica, 
        feature = "effort",
        effort_unit = "hour")
```

The same using days as time unit

```{r effort_in_days}
map_dep(mica, 
        feature = "effort",
        effort_unit = "day")
```

or months

```{r effort_in_months}
map_dep(mica, 
        feature = "effort",
        effort_unit = "month")
```

### Clustering and hovering

You can specify which information you want to show while hovering with the mouse over the deployment. You can choose among all columns from deployments (see allowed fields in [camera trap data package standard documentation](https://tdwg.github.io/camtrap-dp/data/#deployments)) and `n` (number of species, number of observations or RAI).

Here below the lat/lon, the camera height and the tags are shown while hovering:

```{r visualize_with_clusters_spec_hover_col}
map_dep(mica,
        hover_columns = c("latitude",
                          "longitude",
                          "cameraHeight",
                          "tags"),
        feature = "n_obs"
)
```

Deactivating both cluster mode and hovering is also possible:

```{r visualize_without_clusters}
map_dep(mica,
        feature = "n_species", 
        cluster = FALSE,
        hover_columns = NULL)
```

### Visualize deployments without detected animals 

It can happen that some deployments didn't detected any recognizable animal
(`scientificName` = `NA`) or didn't observe anything at all (deployments with no
observations). While visualizing the number of species, these two situations are
shown by default as red and black multiplication symbols `×` respectively.
A message about deployment with zero observations is also returned to the R console:

```{r show_deployments_without_observations_or_without_known_species}
# create data package with one deployment with 0 obs and one delpoyment with
# observations of unknown species
unknown_species_vs_no_obs <- mica
unknown_species_vs_no_obs$data$observations <- 
  unknown_species_vs_no_obs$data$observations %>% 
  # a deployment has detected only unknown species
  filter(is.na(.data$scientificName) | 
           .data$scientificName != "Homo sapiens") %>%
  # a deployment has no observations
  filter(deploymentID != "62c200a9-0e03-4495-bcd8-032944f6f5a1")
# create new map
map_dep(unknown_species_vs_no_obs,
        feature = "n_species")
```

### Use a color palette

The default color palette is a [viridis color palette](https://cran.microsoft.com/snapshot/2017-08-01/web/packages/viridis/vignettes/intro-to-viridis.html) called `"inferno"`. You can specify another viridis color palette, e.g. `"viridis"` or `"magma"`, or a [RColorBrewer](https://renenyffenegger.ch/notes/development/languages/R/packages/RColorBrewer/index) palette, e.g. `"BuPu"` or `"Oranges"`. Below we use the `viridis` color palette:

```{r use_viridis}
map_dep(
  mica,
  "n_obs",
  palette = "viridis"
)
```

We can use a palette from `RColorBrewer`, e.g. the `"BuPu"` palette:

```{r use_BuPu}
map_dep(
  mica,
  "n_obs",
  palette = "BuPu"
)
```

Another easy way to specify a palette is to create it by passing a vector of colors as names or hex colors, e.g. `c("black", "blue", "#A3675F")`:

```{r use_black_blue_white}
map_dep(
  mica,
  "n_obs",
  palette = c("black", "blue", "#A3675F")
)
```

### Use a specific icon and color for zero values

You can pass to `zero_value_icon_url` argument the URL to an icon and to `zero_values_icon_size` the size in pixels of such icon. There are several icon libraries you can choose from. A library with many free icons is [icons8](https://icons8.com/). Here, an example with the icon of Fry from Futurama animation series and icon size 50:

```{r fry_futurama}
map_dep(
  mica,
  "n_obs",
  life_stage = "subadult",
  zero_values_icon_url = "https://img.icons8.com/color/48/000000/futurama-fry.png",
  zero_values_icon_size = 50
)
```

Typically the colour is part of the URL. Here below two examples where we change the color of the default icon to green (2ECC71):

```{r specify_zero_colors_value_example_1}
map_dep(
  mica,
  "n_obs",
  life_stage = "subadult",
  zero_values_icon_url = 
    "https://img.icons8.com/ios-glyphs/30/2ECC71/multiply.png"
)
```

or the INBO fuchsia (#C04384):

```{r specify_zero_colors_value_example_2}
map_dep(
  mica,
  "n_obs",
  life_stage = "subadult",
  zero_values_icon_url = 
    "https://img.icons8.com/ios-glyphs/30/C04384/multiply.png"
)
```

Modifying the default value (`"black"`) can be useful as the color of deployments with zero values can be sometimes too similar to one of the colors used in the palette.

### Modify circle size

You can also modify the upper and lower limit of the circle sizes by specifying `radius_range` (default:   `c(10,50`):

```{r change_size_circles}
map_dep(mica,
        feature = "n_obs",
        radius_range = c(20, 150))
```

### Use absolute scale

By default the upper limit of color palette and radius are defined based on the actual feature values. However, sometimes can be useful to set up an absolute upper limit. This can be done by setting argument `relative_scale` to  `FALSE` and specifying the upper limit in  `max_scale`.

Upper limit lower than number of observations:

```{r low_upper_limit}
map_dep(mica,
        feature = "n_obs",
        relative_scale = FALSE,
        max_scale = 2)
```

Upper limit higher than number of observations:

```{r high_upper_limit}
map_dep(mica,
        feature = "n_obs",
        relative_scale = FALSE,
        max_scale = 50)
```

### Use filter predicates

You maybe would like to visualize deployment information for a subset of deployments. To do this, you can use filter predicates. E.g. visualize number of observations for the deployments with longitude equal or higher than 5.6:

```{r example_filter_predicates_map}
map_dep(mica,
        pred_gt("longitude", 5.6),
        feature = "n_obs")
```

More about filter predicates in [filter predicates](https://inbo.github.io/camtraptor/articles/filter-predicates.html) article.