incR Working Pipeline"

In incR: Analysis of Incubation Data

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

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.

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.

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.

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 for more information).

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.

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.

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.

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.

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

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

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

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.

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

incR documentation built on April 19, 2023, 1:07 a.m.