Author: Pablo Capilla-Lasheras
Date: 2020-06-21

# incR Working Pipeline

#### Pablo Capilla-Lasheras

#### 2020-06-21

This vignette was created using `incR` version 2.1.1 and R version 4.4.2 (2024-10-31).

# Introduction

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 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.

`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)

    ##               DATE temperature index     time hour minute second       date
    ## 1 06/05/2015 21:42      32.018     1 21:42:00   21     42      0 2015-05-06
    ## 2 06/05/2015 21:44      32.018     2 21:44:00   21     44      0 2015-05-06
    ## 3 06/05/2015 21:47      32.143     3 21:47:00   21     47      0 2015-05-06
    ##   dec_time temp1
    ## 1 21.70000    NA
    ## 2 21.73333 0.000
    ## 3 21.78333 0.125

## Combining 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 hour             DATE temperature index     time minute second
    ## 1 2015-05-06   21 06/05/2015 21:42      32.018     1 21:42:00     42      0
    ## 2 2015-05-06   21 06/05/2015 21:44      32.018     2 21:44:00     44      0
    ## 3 2015-05-06   21 06/05/2015 21:47      32.143     3 21:47:00     47      0
    ##   dec_time temp1 env_temp
    ## 1 21.70000    NA 8.759136
    ## 2 21.73333 0.000 8.759136
    ## 3 21.78333 0.125 8.759136

## Automatic 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 hour             DATE temperature index     time minute second
    ## 1        <NA>   NA             <NA>          NA    NA     <NA>     NA     NA
    ## 57 2015-05-07    0 07/05/2015 00:02      31.456    57 00:02:00      2      0
    ## 58 2015-05-07    0 07/05/2015 00:04      31.581    58 00:04:00      4      0
    ## 59 2015-05-07    0 07/05/2015 00:07      31.706    59 00:07:00      7      0
    ## 60 2015-05-07    0 07/05/2015 00:09      31.893    60 00:09:00      9      0
    ## 61 2015-05-07    0 07/05/2015 00:12      31.830    61 00:12:00     12      0
    ##      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          1

    head(incubation.analysis$incRscan_threshold)

    ##         date first.maxIncrease final.maxIncrease first.maxDrop final.maxDrop
    ## 1 2015-05-06              <NA>              <NA>          <NA>          <NA>
    ## 2 2015-05-07              <NA>             0.312          <NA>        -0.562
    ## 3 2015-05-08              <NA>             0.749          <NA>        -0.499
    ##   night_day_varRatio
    ## 1               <NA>
    ## 2              0.034
    ## 3               0.08

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")

    ## Warning: Removed 1 row containing missing values or values outside the scale range
    ## (`geom_line()`).

    ## Warning: Removed 1 row containing missing values or values outside the scale range
    ## (`geom_point()`).

    ## Warning: Removed 1 row containing missing values or values outside the scale range
    ## (`geom_line()`).

## 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.63354

### Incubation 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:00    20:49:00
    ## 2 2015-05-08      05:52:00    13:14:00

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. ### 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        NA

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")

    ##         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        NA

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")

    ##         date day.mean   day.var night.mean night.var
    ## 1 2015-05-07 30.60936  29.91397   33.35018  1.264417
    ## 2 2015-05-08 25.76023 148.19003         NA        NA

### Calculation 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.959

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).