Gently brewing matrix and integral projection models with lefko3
by Judy Che-Castaldo on Oct 12, 2022(blog post written by Richard P. Shefferson, University of Tokyo)
Life is always better when espresso is involved. Add the white noise of a café, and the atmosphere is ripe for scientific progress. This was the setting I was in roughly four years ago (and many times since then…). At the time, I had just finished working on a macro-scale analysis of vegetative dormancy, and had developed matrix projection models (MPMs) for somewhere between 30 and 50 different demographic datasets provided by my co-authors for the project (Shefferson et al. 2018). This project was quite intense, because as a part of it, I developed not only regular function-based MPMs for all of the datasets, but also historical MPMs. Historical MPMs include state information on three consecutive years, instead of the standard two consecutive years that MPMs regularly portray, and so are from large to huge and extremely sparse. The intensity stemmed from the fact that it took roughly 1000 lines of code to standardize each dataset, and a further 1000-2000 lines of code per dataset to develop the projection matrices that I needed, yielding somewhere around 100,000 lines of code for this single project. It was during this time that I began to understand why van Gogh cut his own ear off….
Figure 1. Espresso art at Saza Coffee in Tsukuba, Japan. All the best cafes draw espresso plants worthy of demographic study. Photo: R. Shefferson
But, in that café, the half-dismembered espresso art drawing on my cappuccino stared back at me as it dawned on me that I could probably write a software package that standardized demographic data, created all sorts of projection matrices, and even ran full projections and conducted analyses of those matrices and projections. Most importantly, putting a little effort into doing this could mean that in the future, 20-50 lines of code might accomplish what several thousand lines did before. This was the birth of the R package lefko3.
lefko3 is a software package for R (R Core Team 2022), available on CRAN and easily accessible through the Install Packages… interface in R Studio (or the R command install.packages()). When the package originally went live in August 2020, it was devoted to the production and analysis of historical matrices. However, the genesis of lefko3 lay in that café and its espresso art, and in the goal of the creation of a general working environment for matrix projection analysis. It has now become that.
Why might you try lefko3? Well, suppose that you’ve taken your third year of demographic data as a PhD student and are looking for the next step. Or perhaps you are an experienced population ecologist who has just extracted some interesting matrices from COMPADRE or COMADRE, or an interesting IPM from Madrino or Padrino, and you wish to explore what might happen if you projected them in a particular way, for example under a climate change simulation. Or perhaps you’ve worked with matrix projection for decades but only with deterministic or stochastic analysis, and are considering experimenting with density dependence. In all of these cases, you might consider giving lefko3 a shot, particularly with a shot of espresso. But how to do so?
Learning how to use R packages can be tedious work. R is a programming language with a culture that demands that functions that provide answers, regardless of what the question is. This can make it relatively easy to code in R, but quite difficult to code in R properly and correctly. As many readers will know, learning a new suite of R functions or an entire package typically requires sitting down with your laptop and surfing the web for anything and everything related to the package. Vignettes, course notes, study guides, StackExchange queries, Facebook rants, and Twitter threads… all are fair game. But the most useful materials have a tendency to be step-by-step guides illustrating how to move from the most basic of steps to the most advanced. For this purpose, I have created a full-blown manual for the package, called lefko3: a gentle introduction (Shefferson 2022) (https://bookdown.org/cdorm/lefko3gentle/).
The gentle introduction is currently an online book on the bookdown.org website, and is also available as a roughly 600 page PDF via the Shefferson Lab website (www.sheffersonlab.com/downloads/lefko3gentle.pdf). It currently has 13 chapters that cover everything from the basics, such as building a life history model and standardizing demographic datasets, to intermediate topics such as building Leslie matrices, Lefkovitch matrices, age-by-stage matrices, and discretized IPMs, to advanced topics such as density-dependent, function-based projection, stochastic LTRE analysis, enforced substochasticity, and the use of alternative probability estimation routines and distributions in discretized IPMs and other function-based matrices. So, a new graduate student in population ecology can learn everything from the very basics of R, to the use of the cumulative probability distribution in place of the midpoint method in IPM development (Doak et al. 2021), to methods of projecting matrices under changing climate and density dependence.
I have generally hoped to make this package easy to use, and compatible with other packages such as popbio, popdemo, ipmr, Rcompadre, and Rpadrino (Stubben & Milligan 2007; Stott et al. 2012; Levin et al.2021, 2022; Jones et al. 2022). In the process, I have particularly hoped to make the manual as easy to use as possible (it is, after all, a GENTLE introduction, particularly modeled on Evan Cooch and Gary White’s famous manual for program MARK (Cooch & White 2019). Both the package itself and the manual are continuously evolving, and both grow a bit every few months with new functions and new capabilities. The manual was originally developed as a textbook for a graduate course in matrix model building and analysis at the University of Tokyo, and so can be used as the practical component of a class in population ecology. It also provides plenty of detail to help ecologists ranging from beginners in population ecology and scientific programming, to eco-code gurus sitting in the binary lotus position.
A number of new features are planned for lefko3 in the near to mid-term future. Substantially faster vital rate modeling routines, the incorporation of additive models, lower-level sensitivity analysis, and speed ups to existing modeling routines are all currently planned. All of these topics will eventually be covered in the manual. I am also hoping to work with the Salgo Team to produce some functions that more easily move MPMs and IPMs between packages and databases, particularly expanding functionality with COMPADRE and related databases. Indeed, the future of matrix modeling in R looks quite exciting!
So if you are new to MPMs and IPMs, or are an expert looking to predict the demographic apocalypse, I suggest that you find an interesting café, and go there with your laptop. Order some form of espresso drink, preferably a cappuccino from an artistic barista, and think of the long academic tradition of scientific thought done in cafes (think 19th century Vienna, consider the great physicists of the early 20th century, and ponder Leonard Lefkovitch thinking about life stages and matrices). And then, let ecological and demographic inspiration come!
Literature Cited
Cooch, E.G. & White, G.C. (2019). Program MARK: a gentle introduction. 19th edn.
Doak, D.F., Waddle, E., Langendorf, R.E., Louthan, A.M., Isabelle Chardon, N., Dibner, R.R., et al. (2021). A critical comparison of integral projection and matrix projection models for demographic analysis. Ecological Monographs, 91, e01447.
Jones, O.R., Barks, P., Stott, I., James, T.D., Levin, S., Petry, W.K., et al. (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, 770–781.
Levin, S.C., Childs, D.Z., Compagnoni, A., Evers, S., Knight, T.M. & Salguero-Gómez, R. (2021). ipmr: flexible implementation of integral projection models in R. Methods in Ecology and Evolution, 12, 1826–1834.
Levin, S.C., Evers, S., Potter, T., Peña Guerrero, M., Childs, D.Z., Compagnoni, A., et al. (2022). Rpadrino: an R package to access and use PADRINO, an open access database of integral projection models. Methods in Ecology and Evolution, 13, 1923–1929.
R Core Team. (2022). R: a language and environment for statistical computing.
Shefferson, R.P. (2022). lefko3: a gentle introduction. bookdown.org.
Shefferson, R.P., Kull, T., Hutchings, M.J., Selosse, M.-A., Jacquemyn, H., Kellett, K.M., et al. (2018). Drivers of vegetative dormancy across herbaceous perennial plant species. Ecology Letters, 21, 724–733.
Stott, I., Hodgson, D.J. & Townley, S. (2012). popdemo: an R package for population demography using projection matrix analysis. Methods in Ecology and Evolution, 3, 797–802.
Stubben, C.J. & Milligan, B.G. (2007). Estimating and analyzing demographic models using the popbiopackage in R. Journal of Statistical Software, 22, 11.
Social Media
