---
title: "incR Working Pipeline"
author: "Pablo Capilla-Lasheras"
date: "2020-06-21"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{"incR Working Pipeline"}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

*This vignette was created using `incR` version `r packageVersion("incR")` and 
`r R.Version()$version.string`.*


# Introduction
This document serves as an example for a suggested `incR` working pipeline. I have tested the
accuracy of the method and the results of such validation can be found [here](https://onlinelibrary.wiley.com/doi/full/10.1111/jav.01710). Throughout this vignette, I follow the examples found in the documentation for `incR` and use data distributed with the package.


# `incR` working pipeline

## Data preparation: `incRprep`
The data table contains raw nest temperatures coming from an iButton device (Maxim Integrated Products) and has two 
columns, date/time and temperature values in Celsius degrees. Several files, from the same nest
where combined to create a completed nest temperature file.
```{r include=FALSE}
library("incR")
data("incR_rawdata")  # loading the data
head(incR_rawdata)
```
`incRprep` takes these data and simply adds new columns that are going to be useful for
other components of the pipeline. Please, do not use *date* as the name of the date/time 
column. `incRprep` will create a new column named *date* and will, therefore, produce an
error if such a name is already found in the raw data table. See ?incRprep to find information 
about the new columns added by this function.
```{r eval = TRUE}
incR_rawdata_prep <- incRprep(data = incR_rawdata,
                              date.name = "DATE",
                              date.format= "%d/%m/%Y %H:%M",
                              timezone="GMT",
                              temperature.name="temperature")
head(incR_rawdata_prep, 3)
```

## Combining nest and environmental temperatures: `incRenv`
Following the example with the data generated by `incRprep`, we can apply `incRenv` to
match environmental temperatures. The current version of `incRenv` averages environmental
temperatures per hour.
```{r eval = TRUE}
data(incR_envdata)  # environmental data
head (incR_envdata)

# then use incRenv to merge environmental data
incR_data <- incRenv (data.nest = incR_rawdata_prep,     # data set prepared by incRprep
                      data.env = incR_envdata, 
                      env.temperature.name = "env_temperature", 
                      env.date.name = "DATE", 
                      env.date.format = "%d/%m/%Y %H:%M", 
                      env.timezone = "GMT")

head (incR_data, 3)
```
 
## Automatic incubation scoring: `incRscan`
After using `incRprep` and `incRenv`, the data table is ready for `incRscan`. This function
applies an automatic algorithm that scores incubation. By looking at temperature variation
when the incubating individual is assumed to be incubating, `incRscan` determines presence
or absence of the incubating individual (incubation score) for every data point (i.e. time point) in the data set. For details about the algorithm follow 
[this link](https://onlinelibrary.wiley.com/doi/full/10.1111/jav.01710).


Several parameters in `incRscan` need to be chosen by the user. For such task, it is
highly recommended to have an external source of data validation and calibration, 
for example, video-recordings of the nest or pit-tagged individuals, so that the 
scores calculated by `incRscan` can be assessed. By comparing the performance of `incRscan` 
over several parameters values, one can decide on the best combination of parameters. 
This approach may also serve as a quality-checking step as `incRscan` performance is thought
to drop when data quality decreases. For this example, we use parameter values known to work well
for this data set (see this [LINK](https://onlinelibrary.wiley.com/doi/full/10.1111/jav.01710)
for more information).
```{r}
incubation.analysis <- incRscan (data=incR_data, 
                                   temp.name="temperature",
                                   lower.time=22,
                                   upper.time=3,
                                   sensitivity=0.15,
                                   temp.diff.threshold =5,
                                   maxNightVariation=2,
                                   env.temp="env_temp")
```
`incRscan` needs to have temperature data between `lower.time` and `upper.time` to score
incubation in the following morning, when this is not the case, a printed message 
will be produced - as seen above.


The new object `incubation.analysis` is formed by two data tables (see below), 
representing the original data set with the new `incR_score` column added and a table 
with temperature thresholds used for incubation scoring.
```{r}
names(incubation.analysis)

# incRscan output
head(incubation.analysis$incRscan_data)
head(incubation.analysis$incRscan_threshold)
```
There is no `incR_score` information for May 6 as no `lower.time` - `upper.time` window was 
available. The second table shows us the threshold used for on and off-bout detection. 
The absence of data in `first.maxIncrease` and `first.maxDrop` informs us that the
value set by `maxNightVariation` was not passed. 

The results of incRscan can be quickly visualised with the `incRplot` function. In the plot below, 
on-bout are shown in orange, off-bouts in blue and environmental temperatures appear as a 
green line.
```{r}
my_plot <- incRplot(data = incubation.analysis$incRscan_data,
                     time.var = "dec_time", 
                     day.var = "date", 
                     inc.temperature.var = "temperature", 
                     env.temperature.var = "env_temp",
                     vector.incubation = "incR_score")

# a ggplot plot is created that can be modified by the user
my_plot + ggplot2::labs(x = "Time", y = "Temperature")
```
## Extracting incubation metrics
Once we have produced incubation scores (located in `incR_score`), we can apply other 
incR functions to extract incubation information.


### Incubation constancy
This is defined and calculated as the percentage of daily time spent in the nest.
```{r}
incRatt(data = incubation.analysis[[1]], vector.incubation = "incR_score")
```
### Incubation activity
`incRact` calculates onset and end of activity: firs off-bout in the morning and last on-bout in the evening.
```{r}
incRact(data = incubation.analysis[[1]],
             time_column = "time",
             vector.incubation = "incR_score")
```
Note that if temperature data exists for the entire day, `first_offbout` and `last_onbout`
times correspond to onset and end of activity. Biological interpretation of the times yielded 
by `incRatt` is needed - e.g., in the example above, `last_onbout` for May 8 is not
telling us the end of daily activity but rather the last on-bout in an uncompleted day of
temperature recordings.
### Incubation temperatures
This function offers three options. To calculate temperature average and variance between **1)**
two user-defined time windows, **2)** first off-bout and last on-bout as 
calculated by `incRact` and **3)** calculate twilight times using `crepuscule{maptools}`
and apply twilight times as the temporal window for calculation.

**1**
```{r eval = TRUE}
incRt(data = incubation.analysis[[1]], 
      temp.name = "temperature", 
      limits = c(5,21),                 # time window
      coor = NULL, 
      activity.times = FALSE, 
      civil.twilight = FALSE, 
      time.zone = NULL)              
```
**2**
```{r eval = TRUE}
incRt(data = incubation.analysis[[1]], 
      temp.name = "temperature", 
      limits = NULL,                 
      coor = NULL, 
      activity.times = TRUE,          # incRact is called to define time window
      civil.twilight = FALSE, 
      time.zone = "GMT",
      time_column= "time",
      vector.incubation="incR_score")              
```
**3**
```{r eval = TRUE}
incRt(data = incubation.analysis[[1]], 
      temp.name = "temperature", 
      limits = NULL,                 
      coor = c(39.5, 40.5),          # choose your coordinates
      activity.times = FALSE, 
      civil.twilight = TRUE, 
      time.zone = "GMT")
```
### Calculation of on and off-bouts
`incRbout` calculates i) the number of on and off-bouts per day along with their 
average duration and ii) the starting time, duration, starting temperature and final temperature
for every on and off-bout detected by `incRscan`.
```{r eval = TRUE}
bouts <- incRbouts(data = incubation.analysis[[1]], 
                   vector.incubation = "incR_score",
                   sampling.rate = incubation.analysis[[1]]$dec_time[56] - incubation.analysis[[1]]$dec_time[55],   # sampling interval
                   dec_time = "dec_time",
                   temp = "temperature")

# the results are in two tables
names(bouts)

# bouts per day
head(bouts$day_bouts)

# bout specific data
head(bouts$total_bouts)
```

*****

Please, if you use the package, cite it as: 


Capilla-Lasheras, P. (2018).incR: a new R package to analyse incubation behaviour.
Journal of Avian Biology 49:e01710. doi: [https://doi.org/10.1111/jav.01710).
