Tutorial 1 Preface

This tutorial accompanies the manuscript Iannarilli et al. (2024) and contains step-by-step examples on how to use trigonometric and cyclic cubic spline hierarchical models to analyze activity patterns from time-stamped data. We present case studies based on camera-trap data, but these approaches can be applied to data collected via other static sensors (e.g., acoustic recorders).

Suggested Citation:

  • Iannarilli, F., Gerber, B. D., Erb, J., and Fieberg, J. R. (2024). A “How-to” Guide for Estimating Animal Diel Activity Using Hierarchical Models. Journal of Animal Ecology.

  • Iannarilli, F., Gerber, B. D., Erb, J., and Fieberg, J. R. (2024). Data, R Code, and Output Supporting: A “How-to” Guide for Estimating Animal Diel Activity Using Hierarchical Models Retrieved from the Data Repository for the University of Minnesota.

License: This work is licensed under a Creative Commons Attribution 4.0 International License.

1.1 Structure of the Tutorial

We start the tutorial by introducing the concept of site-to-site variability in diel activity patterns. Using simulated data, we explore two components of this variability, variability in frequency of site-use and variability in timing of activity (Tutorial 2). We then introduce trigonometric generalized linear mixed models and cyclic cubic spline hierarchical generalized additive models as approaches to estimate animals’ diel activity patterns (Tutorial 3). From Tutorial 4 to 7, we use real-case studies to illustrate how to organize the data (Tutorial 4) and apply these hierarchical model approaches. In particular, we present three applications typical of ecological studies focused on activity patterns. We explore:

  • whether a certain species of interest concentrates its activity at one or two specific times of the day (i.e. unimodal and bimodal patterns), or whether its activity is constant throughout the 24-hour cycle (i.e. cathemeral pattern; Tutorial 5);
  • whether changes in diel activity are driven by seasonal or other biotic and abiotic sources of variation (Tutorial 6). We present examples using both categorical (section 6.1) and continuous (section 6.2) variables;
  • whether changes in diel activity are linked to the co-occurrence of another species, providing support for the existence of time-partitioning mechanisms that facilitate species’ coexistence (Tutorial 7).

The tutorials also include a description of the difference between conditional and marginal mean activity patterns, how we can obtain both means and how this difference is relevant depending on the ecological questions at hand (Tutorial 8). We also provide a Tutorial focused on Kernel Density Estimators (KDEs), currently the most used approach for the estimate of activity patterns (Tutorial 9). We compare the three R-packages currently available to estimate diel activity using KDEs (section 9.2), illustrate the consequences of non-aggregating the data in independent events when estimating diel activity (section 9.3), and compare estimates of activity based on KDEs and hierarchical models (section 9.4).

In the Appendix, we provide several additional resources, including:

1. a description of the function sim_activity, a custom-built function used in Tutorials 2 and 3 and throughout the tutorial to simulate activity patterns under different conditions (section 10.1);

2. a formulation of the trigonometric and cyclic cubic hierarchical models based on the Poisson distribution, an alternative to the formulation based on the binomial distribution used throughout the tutorial (section 10.2);

3. an example of how to apply these models in a Bayesian framework (section 10.3);

4. a link to the Diel.Niche R package, a framework recently introduced to robustly characterize animal activity patterns as diel phenotypes (section 10.4).

All analyses were performed in R Core Team (2024) and the tutorial was compiled using bookdown (Xie 2024a, 2016a). The camera-trap data used in the real-case examples were collected at 100 locations sampled between 2016 and 2018 in Northern Minnesota, USA (Iannarilli et al. 2021). Further details on these data can be found in Iannarilli et al. (2021), and data and code to reproduce this tutorial can be accessed at https://github.com/FabiolaIannarilli/HMs_Activity.

1.2 Requirements

Throughout this tutorial, we use several packages. Users interested in compiling the tutorial from source or in reproducing the analysis on their own machine should install them. The code below provides a list of all the libraries needed, checks if they are already installed in the user’s local machine, and installs those packages that are not.

list.of.packages <- c("dplyr", "grid", "gridExtra", "GLMMadaptive", "ggpubr", "mgcv", 
                      "tidyr", "lubridate", "lmtest", "activity", "overlap", "circular", 
                      "nimble", "brms", "forcats", "MESS", "suncalc", "grateful"
                      )
new.packages <- list.of.packages[!(list.of.packages %in% installed.packages()[,"Package"])]
if(length(new.packages)>0) install.packages(new.packages)
if(!("Diel.Niche" %in% installed.packages()[,"Package"])){
  # Install package from GitHub via the devtools package.
  devtools::install_github("diel-project/Diel-Niche-Modeling",
                         ref="main", dependencies = TRUE,
                         build_vignettes = FALSE
                         )
}