This vignette was created using incR
version r packageVersion("incR")
and
r R.Version()$version.string
.
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 pipelineincRprep
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)
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)
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")
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[[1]], 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[[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.
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")
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).
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.