Creating a package to infer species coexistence

Post provided by Ignasi Bartomeus, David García-Callejas, and Oscar Godoy

Ignasi Bartomeus and colleagues share the story behind their recent Methods article ‘cxr: A toolbox for modelling species coexistence in R’.

This post recalls the journey on how we ended up developing cxr (acronym for CoeXistence relationships in R), an R package for quantifying interactions among species and their coexistence relationships. In other words, it provides tools for telling apart the situations in which different species can persist together in a community from the cases in which one species completely overcomes another.

To be honest, we didn’t have the initial intention to create such a package, but sometimes there are ideas that take their own path, and once this happens, you may as well just follow along and enjoy the journey. In the end, we couldn’t be happier with the result.

How did it happen? We guess three stories converge here:

First act. Open, reproducible science

Part of the story started many years ago, probably in 2011, when a young(er) Ignasi was wandering, half lost, in a huge conference of the Ecological Society of America and entered a workshop by the amazing @ropensci community. In this workshop they outlined the concept of reproducible science as applied to quantitative analysis in ecology. The idea of having reproducible, open tools really stuck on Ignasi and, over the years, he adopted the mantra of functionalizing any script that needed to be used more than once (i.e. creating self-contained functions that can be reused in different projects). First, because this is the best way to generate and share reproducible results, but most importantly, because it is the most efficient procedure in the long term.

When Ignasi and Oscar started collaborating in coexistence models (see below), we ended up working on several papers using such models (e.g. Lanuza et al. 2018), but each one with a slightly different enhancement or particularity. Copy-pasted code was everywhere, so we started functionalizing the code, mainly to help us be more efficient and to be able to fix bugs for all projects at once. Our code worked, but was pretty ugly to share and lacked the flexibility that the community needed.

Second Act. Coexistence models

Oscar had spent several years working with coexistence models. Understanding coexistence theory is not difficult, but can be complex, especially if you are not mathematically oriented. In a nutshell, ecological theory has revealed that the coexistence of species belonging to a single trophic level (i.e. species sharing similar requirements for development and reproduction) is largely determined by the balance between average species fitness differences, which drive competitive superiority, and species niche differences, which can stabilize coexistence among competitors when intraspecific competition exceeds interspecific competition (Chesson 2000). Coexistence theory predicts that when differences in competitive superiority between species are large, then large stabilizing niche differences are also necessary to prevent competitive exclusion. Conversely, if species are very similar competitors, then stabilizing forces may be weak but still maintain diversity  following quasi-neutral dynamics. Don’t worry if you don’t grasp all of this at once… like we said, coexistence theory can be complex!

Caracoles ranch: Saline grasslands where more than 20 plant species coexist. This system was used by the team to empirically parameterise coexistence models. (Photo: María Hurtado de Mendoza)

This theory is a cornerstone of contemporary community ecology, and has been pivotal to understand the role of species interactions on a wide range of questions from evolutionary biology to macroecology. Nevertheless, we noticed that theoretical developments were not used by empiricists as much as they could (Bartomeus and Godoy 2018). A major barrier is to translate this mathematical theoretical framework to something directly applicable by end users. As we are strong believers in that ecological studies need to be rooted in solid theory, by then we really wanted to facilitate the use of coexistence theory. In addition, for us, writing such functions was pivotal to fully understand the mathematical models and scripting this models was a way to really understand the theoretical models. But remember, by then, our code was functional, but pretty ugly…

Third Act, I’m sending the wolf

Finally, we obtained some funding to work on this topic, which originated as a side project (side projects often end up being your main research focus!) and David came to the rescue. David has a programming background and, at the time, a newly minted PhD on theoretical community Ecology. David was able to re-script and enhance the models so they are widely applicable across different types of organisms and distinct mathematical formulations. It took quite some time to come up with a way to incorporate flexibility in the models that could be fed to the package while keeping it user-friendly (and by “quite some time” we mean the time it took to completely recode all end-user functions) but we eventually cleaned up the mess just like the wolf did in Pulp Fiction. In the end, we believe we struck a fine balance between usability and complexity. Working on cxr also helped us better understand parts of coexistence theory and clarify concepts for our ongoing projects. While there is always the question of how it will be received by the community, we had a great time working on it (well, except for the endless tiny bugs and infinite documentation!).

To find out more about coexistence models, read the Methods in Ecology and Evolution article, ‘cxr: A toolbox for modelling species coexistence in R

1 thought on “Creating a package to infer species coexistence

  1. Pingback: Book reviews and stories behind the papers | Bartomeus lab

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s