This vignette was created using
r packageVersion("incR") and
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.
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
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)
Following the example with the data generated by
incRprep, we can apply
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)
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
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
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
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
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.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
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")
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.
incRatt(data = incubation.analysis[], vector.incubation = "incR_score")
incRact calculates onset and end of activity: firs off-bout in the morning and last on-bout in the evening.
incRact(data = incubation.analysis[], time_column = "time", vector.incubation = "incR_score")
Note that if temperature data exists for the entire day,
times correspond to onset and end of activity. Biological interpretation of the times yielded
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
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
incRact and 3) calculate twilight times using
and apply twilight times as the temporal window for calculation.
incRt(data = incubation.analysis[], temp.name = "temperature", limits = c(5,21), # time window coor = NULL, activity.times = FALSE, civil.twilight = FALSE, time.zone = NULL)
incRt(data = incubation.analysis[], 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")
incRt(data = incubation.analysis[], temp.name = "temperature", limits = NULL, coor = c(39.5, 40.5), # choose your coordinates activity.times = FALSE, civil.twilight = TRUE, time.zone = "GMT")
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
bouts <- incRbouts(data = incubation.analysis[], vector.incubation = "incR_score", sampling.rate = incubation.analysis[]$dec_time - incubation.analysis[]$dec_time, # 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:
incR: a free new R package to analyse incubation behaviour. Pablo Capilla-Lasheras. bioRxiv 232520; doi: https://doi.org/10.1101/232520.
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.