Your COMPADRE analyses are about to get easier

Understanding the demography of animal and plant populations is crucial to understanding and predicting the fate of species facing environmental change. There are many tools and approaches used to understand species’ demography. Among the most widely used are matrix population models (MPMs). In a nutshell, MPMs are models that classify an organism’s life cycle up into discrete ages or stages (e.g., “juvenile”, “adult”) and projects the populations through time based on transition probabilities of survival or development and contributions to the next generation via reproduction. A parameterised MPM thus describes the age or stage-structured demography of a population in a given place and time - and often experimental treatments.

Researchers have used MPMs in a dizzying array of ways in subfields of biology, including conservation biology, wildlife and resource management, evolutionary biology, invasion biology, and epidemiology. Their popularity has ensured the publication of many hundreds of papers studying many hundreds of species, and this enormous body of literature is a fantastic resource for educators, students, researchers, managers, and governments alike.

The goal of the COMPADRE team (link) is to make these MPMs available in a standardised format to facilitate their use in both research and education. Thanks to generous funding from the US National Science Foundation, we have recently developed a sophisticated online database to hold COMPADRE (released in 2020). This database, which now contains >12000 MPMs for >1,100 species, is more user-friendly than the Excel files of COMPADRE’s early days (shudder!). Now, users can search for and download matrices by metadata, including species name, location, publication author etc. In addition, we provide the entire data sets in two R objects (one for animals and one for plants).

Although we have developed extensive documentation during the last decade and ran over 60 training workshops worldwide, these data objects were essentially an “insiders” tool because of their non-intuitive hierarchical structure and complexity. Therefore, over the last few years, I have led a small team to quietly develop an R package called Rcompadre that makes handling the COMPADRE/COMADRE R database objects a dream. These efforts recently culminated in a publication in Methods in Ecology and Evolution describing the package.

Rcompadre contains functions to download the latest versions of COMPADRE and COMADRE directly into R. Crucially, we use the package to establish two new R object classes: The CompadreDB class defines how the database is represented in R, and the CompadreMat class defines how MPMs are represented within the CompadreDB object. Establishing these object classes means we can specify how these objects respond to familiar R functions. For example, users can now filter/subset the database to any of the included metadata using well-known base-R or tidyverse commands. In addition, users can conveniently pipe these operations to allow for complex filtering requirements. For example, to obtain all matrices for order Carnivora:
 
carnivoreData <- cdb_fetch(cdb = "comadre") |> 
  filter(Order == "Carnivora")

A common request from our workshop attendees was to make it easier to work with large sets of MPMs. We are happy to say that users can now quickly achieve this using Rcompadre functions such as matA or matU (to access all of the MPMs that describe the complete life cycle, or only survival-dependent processes, respectively) directly. This vectorised approach is MUCH more straightforward and programmatically faster than the often-used previous method of using for loops to pull out matrices one-by-one!

During the development of Rcompadre, team members have been actively using the databases for their own research. Much of this research focuses on comparative analyses of demography and life history and has necessitated the development of R functions. We decided to release these functions in a separate R package, Rage. The Rage package contains functionality that facilitates the calculation of a broad range of life-history metrics and associated methods. Broadly, we categorise Rage’s functions into six types: transformation tools; life table-related; calculation of life-history traits; calculation and summary of vital rates; matrix visualisation and perturbation analysis.  The full functionality of these tools is too broad to cover in a single blog post, but in the vignettes available at https://jonesor.github.io/Rage/, we illustrate how Rage can work seamlessly with Rcompadre to quickly conduct a large-scale comparative analysis.

These two packages are valuable additions to R's ecosystem of demographic tools. Rcompadre eases access to the enormous wealth of published data. At the same time, Rage supports the calculation of metrics previously unavailable in R. We hope these tools will be widely used not only by researchers but also by those educating the next generation of population biologists.

Check out our code vignettes at (click on "Articles" at the top of the page):
https://jonesor.github.io/Rage/ and https://jonesor.github.io/Rcompadre/.

Read more about the packages in our recent paper in Methods in Ecology and Evolution: 
Jones, O. R., Barks, P., Stott, I., James, T. D., Levin, S., Petry, W. K., Capdevila, P., Che-Castaldo, J., Jackson, J., Römer, G., Schuette, C., Thomas, C. C., & Salguero-Gómez, R. (2022). Rcompadre and Rage—Two R packages to facilitate the use of the COMPADRE and COMADRE databases and calculation of life‐history traits from matrix population models. Methods in Ecology and Evolution. 13(4):770-781  https://doi.org/10.1111/2041-210x.13792