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)## DATE temperature
## 1 06/05/2015 21:42 32.018
## 2 06/05/2015 21:44 32.018
## 3 06/05/2015 21:47 32.143
## 4 06/05/2015 21:49 32.205
## 5 06/05/2015 21:52 32.205
## 6 06/05/2015 21:54 32.143incRprep 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 date dec_time
## 1 06/05/2015 21:42 32.018 1 21:42 21 42 2015-05-06 21.70000
## 2 06/05/2015 21:44 32.018 2 21:44 21 44 2015-05-06 21.73333
## 3 06/05/2015 21:47 32.143 3 21:47 21 47 2015-05-06 21.78333
## temp1
## 1 NA
## 2 0.000
## 3 0.125Combining 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 temperature index time hour minute date dec_time
## 1 06/05/2015 21:42 32.018 1 21:42 21 42 2015-05-06 21.70000
## 2 06/05/2015 21:44 32.018 2 21:44 21 44 2015-05-06 21.73333
## 3 06/05/2015 21:47 32.143 3 21:47 21 47 2015-05-06 21.78333
## temp1 env_temp
## 1 NA 8.759136
## 2 0.000 8.759136
## 3 0.125 8.759136Automatic 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 temperature index time hour minute date
## 1 <NA> NA NA <NA> NA NA <NA>
## 57 07/05/2015 00:02 31.456 57 00:02 0 2 2015-05-07
## 58 07/05/2015 00:04 31.581 58 00:04 0 4 2015-05-07
## 59 07/05/2015 00:07 31.706 59 00:07 0 7 2015-05-07
## 60 07/05/2015 00:09 31.893 60 00:09 0 9 2015-05-07
## 61 07/05/2015 00:12 31.830 61 00:12 0 12 2015-05-07
## 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 1head(incubation.analysis$incRscan_threshold)## date first.maxIncrease final.maxIncrease first.maxDrop
## 1 2015-05-06 <NA> <NA> <NA>
## 2 2015-05-07 <NA> 0.312 <NA>
## 3 2015-05-08 <NA> 0.749 <NA>
## final.maxDrop night_day_varRatio
## 1 <NA> <NA>
## 2 -0.562 0.034
## 3 -0.499 0.08There 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 rows containing missing values (geom_path).## Warning: Removed 1 rows containing missing values (geom_point).## Warning: Removed 1 rows containing missing values (geom_path).
## 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.63354Incubation 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 20:49
## 2 2015-05-08 05:52 13:14Note 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 NA2
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 NA3
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.63784 29.76609 33.34038 1.265154
## 2 2015-05-08 25.76023 148.19003 NA NACalculation 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.959Please, if you use the package, cite it as:
incR: a free new R package to analyse incubation behaviour. Pablo Capilla-Lasheras. bioRxiv 232520; doi: https://doi.org/10.1101/232520.