| Title: | Analysis of Incubation Data |
|---|---|
| Description: | Suite of functions to study animal incubation. At the core of incR lies an algorithm that allows for the scoring of incubation behaviour. Additionally, several functions extract biologically relevant metrics of incubation such as off-bout number and off-bout duration - for a review of avian incubation studies, see Nests, Eggs, and Incubation: New ideas about avian reproduction (2015) edited by D. Charles Deeming and S. James Reynolds <doi:10.1093/acprof:oso/9780198718666.001.0001>. |
| Authors: | Pablo Capilla-Lasheras [aut, cre] |
| Maintainer: | Pablo Capilla-Lasheras <[email protected]> |
| License: | GPL-3 |
| Version: | 2.1.1.9000 |
| Built: | 2025-02-18 06:58:49 UTC |
| Source: | https://github.com/pablocapilla/incr |
This packages is formed by a suite of R functions that help the user to get useful biological information from raw time-series data of incubation temperatures. It is thought to be of interest for the study of uni-parental or intermittent incubating species.
Check the package vignettes to find a suggested workflow
and calibrate the main function in incR.
The current version of incR contains the following functions and three example data sets:
incRprep, incRenv,
incRscan,
incRact,
incRatt
incRbouts and
incRt, along with three example data sets.
link{incRenv}.A dataset containing environmental temperatures for the study area
where the data in incR_rawdata were collected.
This raw data set
was produced by an iButton device (Maxim Integrated).
incR_envdataincR_envdata
A data frame with 1570 rows and two variables, representing two days of environmental temperature recordings at two different locations in one study site.
a date-time column. Both elements, date and time, are concatenated in one column.
environmental temperature recordings.
use this data set to try out link{incRenv} after the very first
application of incRprep using incR_rawdata.
incRprep and incRenv.A dataset containing temperatures, time and date for a blue tit nest.
It also includes variables added by incRprep
and incRenv.
The raw data set incR_rawdata
was produced by an iButton device (Maxim) and represents raw data to start the analysis
of incubation behaviour
incR_procdataincR_procdata
A data frame with 954 rows and 11 variables, representing two days of nest temperatures.
a date-time column. Both elements, date and time, are concatenated in one column.
nest temperature recordings.
running number from first to last observation.
time in decimal hours.
difference between the ith and the ith-1 nest temperature recording.
environmental temperature, calculated per as hour average using
incRenv.
Incubation scores (0/1) as calculated by incRscan
see incRprep and incRenvfor more details on the variables of this data set
and how it was produced.
A dataset containing date, time and temperatures for a blue tit nest. This data set was produced by an iButton device (Maxim Integrated) and represents raw data to start the analysis of incubation behaviour.
incR_rawdataincR_rawdata
A data frame with 954 rows and 2 variables, representing three days of nest temperatures.
a date-time column. Both elements, date and time, are concatenated in one column
temperature recordings in Celsius
Using a vector of incubation scores, incRact calculates onset of activity (first off-bout in the morning), and end of daily activity (last on-bout in the evening) per day. A column for dates, named "date" is needed in the data argument.
incRact(data, time_column, vector.incubation)incRact(data, time_column, vector.incubation)
data |
data frame containing a numeric vector of 1's and 0's (incubation scores), where "1"
means "incubating individual inside nest" and "0" means "incubating individual
outside the nests". This vector,
under the name of |
time_column |
(character class) name of the column containing times. |
vector.incubation |
(character class) name of the vector containing
incubation scores. |
a data frame containing fist off-bout and last on-bout per day in data.
Pablo Capilla-Lasheras
#' # loading example data data(incR_procdata) incRact (data=incR_procdata, time_column="time", vector.incubation="incR_score")#' # loading example data data(incR_procdata) incRact (data=incR_procdata, time_column="time", vector.incubation="incR_score")
This function calculates percentage of day time spent inside nest
based on the "inc.vector" variable produced by incRscan (or any other method).
Current version do not discriminate day and night times.
incRatt(data, vector.incubation)incRatt(data, vector.incubation)
data |
data frame containing a time-series vector of 1's and 0's, where "1"
means "incubating individual inside nest" and "0" means "incubating individual
outside nest". This vector,
under the name of "inc.vector" is provided by |
vector.incubation |
name of the column (vector class) storing the information about the presence/absence of the incubating individual in the nest. |
The 'date' column must have a 'year-month-day' format for this function to run correctly.
Daily percentage of time in nest, returned in a data frame with one day per raw.
#' # loading example data data(incR_procdata) incRatt (data=incR_procdata, vector.incubation="incR_score")#' # loading example data data(incR_procdata) incRatt (data=incR_procdata, vector.incubation="incR_score")
Calculation of number and duration of incubation on- and off-bouts.
incRbouts(data, vector.incubation, dec_time, temp, sampling.rate)incRbouts(data, vector.incubation, dec_time, temp, sampling.rate)
data |
data frame containing a time-series vector of 1's and 0's, where "1"
means "incubating individual inside nest" and "0" means "incubating individual
outside nest". This vector,
under the name of "inc.vector", is provided by |
vector.incubation |
name of the column (vector class) storing the information about the presence/absence of the incubating individual in the nest. |
dec_time |
(character class) name of the column with decimal time. |
temp |
(character class) name of the column with incubation temperatures. |
sampling.rate |
time difference between two consecutive recording points. Effectively, the rate at which data points were recorded (e.g. 1 data point per 50sec). The time units of the returned object will depend on the units of this argument. |
This function returns a list with two objects. The first object, named total_bouts, is a list of
individual on- and off-bouts, giving information about their start time, duration, start nest temperature and
final nest temperature. The second object, day_bouts, provides a summary of on-
and off-bouts per day of observation. This second table shows number and mean duration of on- and off-bout
per day. Mean times are shown in those time units you specify the argument sampling.rate.
Pablo Capilla-Lasheras
incRprep incRscan incRact
incRatt
#' # loading example data data(incR_procdata) incRbouts (data=incR_procdata, vector.incubation="incR_score", dec_time="dec_time", temp="temperature", sampling.rate=240) # sampling rate in seconds.#' # loading example data data(incR_procdata) incRbouts (data=incR_procdata, vector.incubation="incR_score", dec_time="dec_time", temp="temperature", sampling.rate=240) # sampling rate in seconds.
This function takes a data frame with recordings of environmental temperature and another
with nest temperatures and merges both by time. The user can do this work manually, however,
incRenv is thought to
automate data preparation (in combination with incRprep) to use
incRscan after. Code to update and improve this function provided by Natalie van Dis.
incRenv( data.nest, data.env, env.temperature.name, env.date.name, env.date.format, env.timezone )incRenv( data.nest, data.env, env.temperature.name, env.date.name, env.date.format, env.timezone )
data.nest |
data frame containing nest temperature recordings. It must have two compulsory
columns 'date' and 'hour' displaying dates and the hour of each observation. These two columns
are provided if the user uses |
data.env |
data frame containing environmental temperatures to be merged with nest temperature
records. Please, provide date and time of each observation in one unique column as requested
for |
env.temperature.name |
name of the column containing temperature recordings in the data.env data frame. |
env.date.name |
name of the column containing date and time in the data.env data frame. |
env.date.format |
format of env.date.name. Similar to |
env.timezone |
time zone of the environmental recordings. Similar to |
This function is thought to be used after incRprep as it uses some of the
additional variables created by incRprep.
The original data.nest with an additional column for hour-averaged environmental
temperature. This new variable is thought to serve as env_temp in
incRscan.
Pablo Capilla-Lasheras
data(incR_envdata) # environmental data head (incR_envdata) data(incR_rawdata) # loading nest data head (incR_rawdata) # the first step in to format the raw data using incRprep new.data <- incRprep (data=incR_rawdata, date.name= "DATE", date.format= "%d/%m/%Y %H:%M", timezone="GMT", temperature.name="temperature") # then use incRenv to merge environmental data new.data2 <- incRenv (data.nest = new.data, 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 (new.data2, 3)data(incR_envdata) # environmental data head (incR_envdata) data(incR_rawdata) # loading nest data head (incR_rawdata) # the first step in to format the raw data using incRprep new.data <- incRprep (data=incR_rawdata, date.name= "DATE", date.format= "%d/%m/%Y %H:%M", timezone="GMT", temperature.name="temperature") # then use incRenv to merge environmental data new.data2 <- incRenv (data.nest = new.data, 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 (new.data2, 3)
This function takes a data frame with recordings of environmental temperature and another
with nest temperatures and merges both per unit of time. The user can do this work manually, however,
incRenv is thought to
automate data preparation (in combination with incRprep) to use
incRscan after.
incRenv_old( data.nest, data.env, env.temperature.name, env.date.name, env.date.format, env.timezone )incRenv_old( data.nest, data.env, env.temperature.name, env.date.name, env.date.format, env.timezone )
data.nest |
data frame containing nest temperature recordings. It must have two compulsory
columns 'date' and 'hour' displaying dates and the hour of each observation. These two columns
are provided if the user uses |
data.env |
data frame containing environmental temperatures to be merged with nest temperature
records. Please, provide date and time of each observation in one unique column as requested
for |
env.temperature.name |
name of the column containing temperature recordings in the data.env data frame. |
env.date.name |
name of the column containing date and time in the data.env data frame. |
env.date.format |
format of env.date.name. Similar to |
env.timezone |
time zone of the environmental recordings. Similar to |
This function is thought to be used after incRprep as it uses some of the
additional variables created by incRprep.
The original data.nest with an additional column for hour-averaged environmental
temperature. This new variable is thought to serve as env_temp in
incRscan.
Pablo Capilla-Lasheras
data(incR_envdata) # environmental data head (incR_envdata) data(incR_rawdata) # loading nest data head (incR_rawdata) # the first step in to format the raw data using incRprep new.data <- incRprep (data=incR_rawdata, date.name= "DATE", date.format= "%d/%m/%Y %H:%M", timezone="GMT", temperature.name="temperature") # then use incRenv to merge environmental data new.data2 <- incRenv_old (data.nest = new.data, 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 (new.data2, 3)data(incR_envdata) # environmental data head (incR_envdata) data(incR_rawdata) # loading nest data head (incR_rawdata) # the first step in to format the raw data using incRprep new.data <- incRprep (data=incR_rawdata, date.name= "DATE", date.format= "%d/%m/%Y %H:%M", timezone="GMT", temperature.name="temperature") # then use incRenv to merge environmental data new.data2 <- incRenv_old (data.nest = new.data, 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 (new.data2, 3)
After incRscan has been used, incRplot
provides a quick visualisation of the incubation temperature trace with coloured
on- and off-bouts. Environmental temperatures can also be added to the plot
incRplot( data, time.var, day.var, inc.temperature.var, env.temperature.var = NULL, vector.incubation )incRplot( data, time.var, day.var, inc.temperature.var, env.temperature.var = NULL, vector.incubation )
data |
data table with incubation temperature data |
time.var |
Character string. Name of the variable with time of the day for
temperature data. Please, have time in
decimal hours. If |
day.var |
Character string. Name of the variable with date for
temperature observation. No specific format is needed.
If |
inc.temperature.var |
Character string. Name of the variable with incubation temperatures. |
env.temperature.var |
Character string. Name of the variable with environmental temperatures. If no value is provided, a plot with no environmental temperatures is produced. |
vector.incubation |
name of the binary variable storing
information about the presence/absence of the incubating individual in the nest.
If |
Plot of incubation temperature, on-bouts and off-bouts with (optional)
environmental temperatures. The plot is generated using ggplot2.The
user can customised the appearance of the plot using tools
within ggplot2(see example)
# loading example data data(incR_procdata) my_plot <- incRplot(data = incR_procdata[complete.cases(incR_procdata$temperature),], time.var = "dec_time", day.var = "date", inc.temperature.var = "temperature", env.temperature.var = "env_temp", vector.incubation = "incR_score") # see your plot my_plot # add new labels (ggplot2 required) my_plot + ggplot2::labs(x = "New X label", y = "New Y label")# loading example data data(incR_procdata) my_plot <- incRplot(data = incR_procdata[complete.cases(incR_procdata$temperature),], time.var = "dec_time", day.var = "date", inc.temperature.var = "temperature", env.temperature.var = "env_temp", vector.incubation = "incR_score") # see your plot my_plot # add new labels (ggplot2 required) my_plot + ggplot2::labs(x = "New X label", y = "New Y label")
Preparing incubation time series for further analysis. This function takes a data file containing a temporal series of temperature recordings and adds some the extra variables needed to use further functions embedded in the incR package. It simply accommodates a raw data frame, reformatting date and time columns automatically.
incRprep(data, date.name, date.format, timezone, temperature.name)incRprep(data, date.name, date.format, timezone, temperature.name)
data |
raw data from incubation time series. It must contain a column with date and time information for each observation (e.g. "2017-05-01 21:01"). The function is written to handle date and time concatenated in one unique column (see example below). |
date.name |
name of the date and time column |
date.format |
format for date and time column.
It must be a character object as specified in the function |
timezone |
time zone for time calculations. See |
temperature.name |
name of the column storing temperature information. |
The original data frame with additional columns for:
index: a running number identifying every row in the data set.
time: in '
hour: in 'H' format.
minute: in 'M' format.
second: in 'S' format.
date: in 'Y-m-d' format.
dec_time: time in decimal hours (e.g. "22:30" becomes 22.5).
temp1: difference between the ith temperature value and the i-1 one.
Pablo Capilla-Lasheras
# loading example data data(incR_rawdata) new.data <- incRprep (data=incR_rawdata, date.name= "DATE", date.format= "%d/%m/%Y %H:%M", timezone="GMT", temperature.name="temperature") head (new.data, 3)# loading example data data(incR_rawdata) new.data <- incRprep (data=incR_rawdata, date.name= "DATE", date.format= "%d/%m/%Y %H:%M", timezone="GMT", temperature.name="temperature") head (new.data, 3)
This is the core algorithm of incR and classifies time points as 1's or 0's depending on
whether or not the incubating individual is considered to be on the eggs.
The algorithm
uses night variation to daily calibrate itself to temperature variation when the incubating
individual is assumed to be on the eggs.
A major assumption of this algorithm is that
there is a period of time in which temperature can be assumed to be constant or
representative of time windows of constant incubation. This time window is defined by
two arguments: lower.time and upper.time. The function is optimised to work using
a data frame produced by incRprep.
incRscan( data, temp.name, lower.time, upper.time, sensitivity, temp.diff, temp.diff.threshold, maxNightVariation, env.temp )incRscan( data, temp.name, lower.time, upper.time, sensitivity, temp.diff, temp.diff.threshold, maxNightVariation, env.temp )
data |
data frame for analysis. It must contained four columns named as follow:
|
temp.name |
(character object) name of the column containing temperature data
in |
lower.time |
lower limit of time window for calibration (numeric). |
upper.time |
upper limit of time window for calibration (numeric). |
sensitivity |
ratio of reduction in temperature threshold. When nest temperature does not drop close to environmental temperatures, this value can be kept to 1. If nest temperature follows environmental temperature at any point, then adjustment of this value may be required to detect short on/off-bouts at lower nest temperatures (see details). |
temp.diff |
deprecated. Use temp.diff.threshold. |
temp.diff.threshold |
threshold for temperature difference between |
maxNightVariation |
maximum temperature variation between two consecutive points within the calibrating window that is considered normal of this period. If this variation value is surpassed, the calibrating window is discarded and a previous night is used for calibration. |
env.temp |
name of a column containing environmental temperatures. |
The function returns a list with two objects. The first object, named incRscan_data, is the original
data frame with an extra column named 'incR_score'. This variable is formed by 1's and 0's,
representing whether the incubating individual is inside (1) or outside the nest (0).
The second object, named incRscan_threshold, is a data frame with one day per row. Four columns tell the user
the thresholds employed to calculate the 'incR_score' column. A fifth column accounts
for the ratio between temperature variation in the calibrating window and the variation in temperature
between 11am and 3pm for each day morning. The lower this value the more clear the pattern between night
and day variation and, therefore, stronger the signal in the data.
This value may serve the user as an indication of the signal / noise ratio in the analysed
data set.
For further details about the calculation performed by incRscan, consult the package vignettes and
the associated publications.
Pablo Capilla-Lasheras
# incR_procdata is a dataframe processed by incRprep and incRenv. # it contains suitable information to run incRscan data(incR_procdata) incubation.analysis <- incRscan (data=incR_procdata, temp.name="temperature", lower.time=22, upper.time=3, sensitivity=0.15, temp.diff.threshold=5, maxNightVariation=2, env.temp="env_temp") inc.data <- incubation.analysis[[1]] inc.thresholds <- incubation.analysis[[2]]# incR_procdata is a dataframe processed by incRprep and incRenv. # it contains suitable information to run incRscan data(incR_procdata) incubation.analysis <- incRscan (data=incR_procdata, temp.name="temperature", lower.time=22, upper.time=3, sensitivity=0.15, temp.diff.threshold=5, maxNightVariation=2, env.temp="env_temp") inc.data <- incubation.analysis[[1]] inc.thresholds <- incubation.analysis[[2]]
Modified version of incRscan. Data points are assigned to incubation on/off-bout based on
a fixed temperature threshold for the difference in nest temperature expected when an off-bout starts.
incRscan_v2( data, temp.name, sensitivity, temperature_threshold, temp.diff.threshold, env.temp )incRscan_v2( data, temp.name, sensitivity, temperature_threshold, temp.diff.threshold, env.temp )
data |
data frame for analysis. It must contained four columns named as follow:
|
temp.name |
(character object) name of the column containing temperature data
in |
sensitivity |
percentage of reduction in temperature threshold. When nest temperature does not drop close to environmental temperature, this value can be kept to 1. If nest temperature follows environmental temperature at any point, then, adjustment of this value may be required to detect short on/off-bouts at lower nest temperatures (see details). |
temperature_threshold |
Maximum temperature difference between two consecutive nest temperature recordings allowed for an on-bout. When the difference in nest temperature between two consecutive recordings is higher than this value, an off-bout is detected. |
temp.diff.threshold |
threshold for temperature difference between |
env.temp |
name of a column containing environmental temperatures. |
The function returns the original data frame with a new column named 'incR_score'.
This new variable is formed by 1's and 0's,
representing whether the incubating individual is inside ("1") or outside the nest ("0").
#' @section Details:
See incRenv for more details
Pablo Capilla-Lasheras
# incR_procdata is a data frame processed by incRprep and incRenv. # It contains suitable information to run incRscan data(incR_procdata) incubation.analysis <- incRscan_v2 (data=incR_procdata, temp.name="temperature", temperature_threshold = 0.75, sensitivity=0.15, temp.diff.threshold=5, env.temp="env_temp")# incR_procdata is a data frame processed by incRprep and incRenv. # It contains suitable information to run incRscan data(incR_procdata) incubation.analysis <- incRscan_v2 (data=incR_procdata, temp.name="temperature", temperature_threshold = 0.75, sensitivity=0.15, temp.diff.threshold=5, env.temp="env_temp")
incRscan) and fixed temperature thresholds
(as in incRscan_v2
Modified version of incRscan. It combines the assignment of incubation on/off-bout implemented in
incRscan and incRscan_v2.
incRscan_v3( data, temp.name, temperature_threshold, lower.time, upper.time, sensitivity, temp.diff, temp.diff.threshold, maxNightVariation, env.temp )incRscan_v3( data, temp.name, temperature_threshold, lower.time, upper.time, sensitivity, temp.diff, temp.diff.threshold, maxNightVariation, env.temp )
data |
data frame for analysis. It must contained four columns named as follow:
|
temp.name |
(character object) name of the column containing temperature data
in |
temperature_threshold |
Maximum temperature difference between two consecutive nest temperature recordings
allowed for an on-bout. When the difference in nest temperature between two consecutive recordings is higher than
this value, an off-bout is detected. Only applies for days when a calibration window is not available or |
lower.time |
lower limit of time window for calibration (numeric). |
upper.time |
upper limit of time window for calibration (numeric). |
sensitivity |
percentage of reduction in temperature threshold. When nest temperature does not drop close to environmental temperature, this value can be kept to 1. If nest temperature follows environmental temperature at any point, then, adjustment of this value may be required to detect short on/off-bouts at lower nest temperatures (see details). |
temp.diff |
deprecated. Use temp.diff.threshold. |
temp.diff.threshold |
threshold for temperature difference between |
env.temp |
name of a column containing environmental temperatures. |
The function returns the original data frame with a new column named 'incR_score'.
This new variable is formed by 1's and 0's,
representing whether the incubating individual is inside ("1") or outside the nest ("0").
#' @section Details:
See incRenv for more details
Pablo Capilla-Lasheras
Calculation of temperature average and variation between two customised
time periods per day. Time windows can be defined by the user using the limits argument,
defined by bird activity time (using the activity.times parameter) or set according to
twilight times if coordinates are provided (coor).
incRt( data, temp.name, limits = NULL, coor = NULL, activity.times = FALSE, civil.twilight = FALSE, time.zone = NULL, ... )incRt( data, temp.name, limits = NULL, coor = NULL, activity.times = FALSE, civil.twilight = FALSE, time.zone = NULL, ... )
data |
data frame containing a time-series vector of 1's and 0's (incubation scores),
where "1"
means "incubating individual inside nest" and "0" means "incubating individual
outside the nests". This vector,
under the name of |
temp.name |
(character object) name of the column containing temperature data in data. |
limits |
vector of length 2 giving the time limits for calculations. For example, 'c(6,20)' would calculate temperature averages and variances for two time periods, from 6 to 20 and from 20 to 6 of the next day. 'civil.twilight' and 'activity.times' must be FALSE to allow the use of 'limits'. |
coor |
coordinates for the location where temperature was recorded,
formatted as decimal degrees N/S, decimal degrees E/W.
When 'civil.twilight' is TRUE, 'coor' allows the user to define sunrise and sunset times
based on the |
activity.times |
TRUE or FALSE. Set as TRUE when time periods for calculation
are defined by |
civil.twilight |
TRUE or FALSE. Set as TRUE when time periods for calculation
are to be defined by civil twilight times - calculated using |
time.zone |
time zone for |
... |
use parameters in |
a data frame containing temperature means and variance for the defined time window.
Pablo Capilla-Lasheras
incRprep incRscan incRact
getSunlightTimes
# loading example data data(incR_procdata) # calculation based on chosen times from 6am to 7pm and 7pm to 6am incRt (data=incR_procdata, temp.name="temperature", limits=c(6,19), coor=NULL, civil.twilight=FALSE, activity.times=FALSE, time.zone=NULL) # calculation based on activity times incRt (data=incR_procdata, temp.name="temperature", limits=NULL, coor=NULL, civil.twilight=FALSE, activity.times=TRUE, time.zone=NULL, time_column="time", # extra argument needed for incRact vector.incubation="incR_score") # extra argument needed for incRact # calculation based on civil twilight incRt (data=incR_procdata, temp.name="temperature", limits=NULL, coor=c(42,0.89), civil.twilight=TRUE, activity.times=FALSE, time.zone="GMT")# loading example data data(incR_procdata) # calculation based on chosen times from 6am to 7pm and 7pm to 6am incRt (data=incR_procdata, temp.name="temperature", limits=c(6,19), coor=NULL, civil.twilight=FALSE, activity.times=FALSE, time.zone=NULL) # calculation based on activity times incRt (data=incR_procdata, temp.name="temperature", limits=NULL, coor=NULL, civil.twilight=FALSE, activity.times=TRUE, time.zone=NULL, time_column="time", # extra argument needed for incRact vector.incubation="incR_score") # extra argument needed for incRact # calculation based on civil twilight incRt (data=incR_procdata, temp.name="temperature", limits=NULL, coor=c(42,0.89), civil.twilight=TRUE, activity.times=FALSE, time.zone="GMT")