incR Working Pipeline

Pablo Capilla-Lasheras

2020-06-21

This vignette was created using incR version 2.1.0 and R version 4.2.2 (2022-10-31 ucrt).

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.

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)
##               DATE temperature index     time hour minute second       date
## 1 06/05/2015 21:42      32.018     1 21:42:00   21     42      0 2015-05-06
## 2 06/05/2015 21:44      32.018     2 21:44:00   21     44      0 2015-05-06
## 3 06/05/2015 21:47      32.143     3 21:47:00   21     47      0 2015-05-06
##   dec_time temp1
## 1 21.70000    NA
## 2 21.73333 0.000
## 3 21.78333 0.125

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)
##               DATE env_temperature
## 1 06/05/2015 00:02           6.415
## 2 06/05/2015 00:03           6.244
## 3 06/05/2015 00:08           6.244
## 4 06/05/2015 00:08           6.415
## 5 06/05/2015 00:13           6.477
## 6 06/05/2015 00:14           6.244
# 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)
##         date hour             DATE temperature index     time minute second
## 1 2015-05-06   21 06/05/2015 21:42      32.018     1 21:42:00     42      0
## 2 2015-05-06   21 06/05/2015 21:44      32.018     2 21:44:00     44      0
## 3 2015-05-06   21 06/05/2015 21:47      32.143     3 21:47:00     47      0
##   dec_time temp1 env_temp
## 1 21.70000    NA 8.759136
## 2 21.73333 0.000 8.759136
## 3 21.78333 0.125 8.759136

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")
## [1] "No night reference period for  2015-05-06  - day skipped"

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)
## [1] "incRscan_data"      "incRscan_threshold"
# incRscan output
head(incubation.analysis$incRscan_data)
##          date hour             DATE temperature index     time minute second
## 1        <NA>   NA             <NA>          NA    NA     <NA>     NA     NA
## 57 2015-05-07    0 07/05/2015 00:02      31.456    57 00:02:00      2      0
## 58 2015-05-07    0 07/05/2015 00:04      31.581    58 00:04:00      4      0
## 59 2015-05-07    0 07/05/2015 00:07      31.706    59 00:07:00      7      0
## 60 2015-05-07    0 07/05/2015 00:09      31.893    60 00:09:00      9      0
## 61 2015-05-07    0 07/05/2015 00:12      31.830    61 00:12:00     12      0
##      dec_time  temp1 env_temp incR_score
## 1          NA     NA       NA         NA
## 57 0.03333333 -0.062   6.7945          1
## 58 0.06666667  0.125   6.7945          1
## 59 0.11666667  0.125   6.7945          1
## 60 0.15000000  0.187   6.7945          1
## 61 0.20000000 -0.063   6.7945          1
head(incubation.analysis$incRscan_threshold)
##         date first.maxIncrease final.maxIncrease first.maxDrop final.maxDrop
## 1 2015-05-06              <NA>              <NA>          <NA>          <NA>
## 2 2015-05-07              <NA>             0.312          <NA>        -0.562
## 3 2015-05-08              <NA>             0.749          <NA>        -0.499
##   night_day_varRatio
## 1               <NA>
## 2              0.034
## 3               0.08

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")
## Warning: Removed 1 row containing missing values (`geom_line()`).
## Warning: Removed 1 rows containing missing values (`geom_point()`).
## Warning: Removed 1 row containing missing values (`geom_line()`).

## 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")
##         date percentage_in
## 1 2015-05-07      78.64583
## 2 2015-05-08      68.63354

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")
##         date first_offbout last_onbout
## 1 2015-05-07      05:47:00    20:49:00
## 2 2015-05-08      05:52:00    13:14:00

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)              
##         date day.mean   day.var night.mean night.var
## 1 2015-05-07 31.06143  30.03051   33.61665 0.4397057
## 2 2015-05-08 22.50848 168.61488         NA        NA

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")              
##         date day.mean   day.var night.mean night.var
## 1 2015-05-07 30.97323  31.89103   33.69237 0.4758604
## 2 2015-05-08 20.73246 168.97885         NA        NA

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")
##         date day.mean   day.var night.mean night.var
## 1 2015-05-07 30.60936  29.91397   33.35018  1.264417
## 2 2015-05-08 25.76023 148.19003         NA        NA

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)
## [1] "total_bouts" "day_bouts"
# bouts per day
head(bouts$day_bouts)
##         date number.on.bouts number.off.bouts mean.time.on.bout
## 1 2015-05-07              33               32         0.6863636
## 2 2015-05-08               8                7         1.3812500
##   mean.time.off.bout
## 1          0.1921875
## 2          0.7214286
# bout specific data
head(bouts$total_bouts)
##         date    type start_time duration start_temp final_temp
## 1 2015-05-07  onbout      0.033     6.90     31.456     32.018
## 2 2015-05-07 offbout      5.783     1.55     30.457     10.374
## 3 2015-05-07  onbout      7.067     0.80     12.128     32.455
## 4 2015-05-07 offbout      7.733     0.55     31.206     18.829
## 5 2015-05-07  onbout      8.200     1.15     19.831     33.141
## 6 2015-05-07 offbout      9.150     0.20     32.080     27.959

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