--- 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).