This vignette was created using incR version 0.3.1 and R version 3.4.1 (2017-06-30).
This vignette serves as an example of the suggested incR working pipeline. The accuracy of the method is found in another vignette which will be publicly available soon. Throughout this vignette, I follow the examples found in the documentation for incR and use data distributed with the package.
incR working pipelineincRprepThe data set contains raw nest temperature data coming from an iButton device (Maxim Integrated Products) and has two columns, date/time and temperature values in ºC. 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 found in the raw data table.
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.125incRenvFollowing 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.759136incRscanAfter using incRprep and incRenv, our 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 classifies presence or absence of the incubating individual (incubation score) for every line in the data set. The details of the algorithm can be read here: LINK TO PAPER.
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 come up with 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 decrease. For this example, we use parameter values known to work well (in this case incRscan correctly scores over 95% of the data points).
incubation.analysis <- incRscan (data=incR_data,
temp.name="temperature",
lower.time=22,
upper.time=3,
sensitivity=0.15,
temp.diff=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[[1]])## 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[[2]])## 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.
Once we have produced incubation scores (located in incR_score), we can apply other incR functions to extract incubation information.
This is defined and calculated as the percentage of daily time spent in the nest.
incRconstancy(data = incubation.analysis[[1]], vector.incubation = "incR_score")## date percentage_in
## 1 2015-05-07 78.64583
## 2 2015-05-08 68.63354incRactivity calculates onset and end of activity: firs off-bout in the morning and last on-bout in the evening.
incRactivity(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 incRconstancy is needed - e.g., in the example above, last_onbout for May 8 is not telling us end of daily activity but rather the last on-bout in an uncompleted day of temperature recordings.
This function offers three options. To calculate temperature averages and variance between 1) two user-defined time windows, 2) first off-bout and last on-bout as calculated by incRactivity and 3) calculate twilight times using crepuscule{maptools} and apply twilight times as times 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, # incRactivity 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 NAincRbout 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")
# 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