Methods that link traits, phylogenies, biogeography and metacommunities in R, to analyse data and to simulate it.
The simulations work at the level of populations in ecological time: abundances in every site grow, compete and disperse, and, when asked, each population carries the genetic means of one or more traits that evolve by selection and drift under quantitative genetics (Lande 1979), with a covariance matrix G per species. Lineages can split into new species inside the metacommunity, so the same run gives communities, trait distributions of individuals and the true phylogeny. Because the truth is known, the analysis functions of the package can be tested on these simulations before they are applied to field data.
comdynamite is a modular framework rather than a model that contains the others: processes are switched on as options (evolution, speciation, disturbance, lottery recruitment, overlapping generations), in the spirit of the flexible mechanistic models called for by Cabral, Valente & Hartig (2017). The nesting map shows which settings approximate six published models, which of their mechanisms are missing, and what happened when we tried to reproduce the results of Urban & De Meester (2009) and Leibold et al. (2019).
Analyse data
| Question | Functions | Article |
|---|---|---|
| Which clades respond to the environment or to biogeographic events? |
node_contrasts(), biogeography_matrix(), node_test()
|
Analysing clades |
| Does phylogenetic composition follow the environment across the whole tree? |
pcc_test(), pcps_test(), phylo_beta_test()
|
Testing the whole tree |
| Which phylogenetic axis relates to a predictor? | phylo_vector() |
Analysing clades |
| How much of trait or phylogenetic variation is due to environment and space? |
trait_partition(), plot_trait_partition()
|
Analysing clades |
| My sites are neighbours: which null model? |
torus_permutations(), rigid_permutations(), patch_permutations()
|
Analysing clades |
| How do I format my own data? | Preparing your data |
Simulate data
| Question | Functions | Article |
|---|---|---|
| Dynamics with growth, competition and dispersal, as in Thompson et al. (2020) | simulate_metacommunity() |
Get started |
| Static communities along gradients |
simulate_static(), simulate_logistic()
|
Testing the whole tree |
| Assembly by rules, without dynamics, as in Kraft et al. (2007) | assemble_community() |
Watching assembly |
| Traits with phylogenetic signal or under Ornstein-Uhlenbeck regimes |
species_traits(), trait_ou()
|
Get started |
| Local adaptation, migration load and evolutionary rescue, with one or several traits |
evolution_control(), genetic_matrices(), maladaptation()
|
Quantitative genetics in the metacommunity |
| Speciation inside the metacommunity, with the full and reconstructed trees |
simulate_evolving_metacommunity(), speciation_control()
|
|
| Individuals sampled from simulated populations, and tests of drift |
sample_individuals(), drift_test()
|
|
| Does a method work? Type I error and power by simulation | all of the above | Evaluating methods |
In R, ?comdynamite gives the same map.
install.packages("comdynamite", repos = c("https://diogoprov.r-universe.dev",
"https://cloud.r-project.org"))
# or
remotes::install_github("diogoprov/comdynamite")
The permutations of pcc_test(), pcps_test(), phylo_beta_test() and trait_partition() run
in parallel when you choose a plan with the future package, and results can be reproduced with set.seed() for any number of workers. node_test() has its own
cores argument: it took about 4 minutes with 600 species, 100 sites and 999 permutations on
one core.
future::plan(future::multisession, workers = 4)
Inputs can be tibbles of numeric columns, and as.data.frame() or tibble::as_tibble() turn
results into tables.
library(comdynamite)
set.seed(1)
tr <- treeshapesim::sim_tree_shape(40)
sim <- simulate_metacommunity(
landscape = landscape_implicit(50),
traits = species_traits(tr, lambda = 1),
alpha = competition_matrix(tr, type = "phylo"),
dispersal = 0.01,
n_steps = 1000
)
sim$abundance # sites x species
The website has the articles and the function
reference. To read the vignettes in R, install with build_vignettes = TRUE.
mcomsimr, by Patrick
Thompson, is the original R implementation of the model of Thompson et al.
(2020). comdynamite was written independently from the published equations.
It differs in its conventions (sigma is the standard deviation of the
Gaussian response, so it equals sqrt(2) times the niche breadth of
Thompson et al.; alpha[j, k] is the effect of species k on species j) and
adds phylogenetic traits and competition, grid landscapes on a torus with
their restricted permutations, and abundances recorded over time.
gen3sis (Hagen et al.
2021) is a general engine for eco-evolutionary simulations on landscapes
that change over geological time. Speciation, extinction, dispersal and trait
evolution are simulated, so the phylogeny is an outcome of the
simulation, and the ecological rules are functions that the user writes.
comdynamite works in ecological time, at the level of populations and their
quantitative genetics. In simulate_metacommunity() the phylogeny is an
input: the tree is fixed and traits are placed on it with a chosen
phylogenetic signal, which is what simulation studies of methods need,
because tree shape and phylogenetic signal can be set independently and
replicates can be paired by tree across scenarios. In
simulate_evolving_metacommunity() lineages also split inside the
metacommunity, but over ecological rather than geological time and on a
static set of sites. The two engines are complementary, and a phylogeny
produced by gen3sis can be used as the regional pool of a comdynamite
simulation.
treeshapesim simulates trees with separately controlled imbalance and branching times, to use as regional pools in comdynamite. Tree shape can then be a factor in the design of a simulation study:
tr <- treeshapesim::sim_tree_shape(40, beta = -1, c = -0.5)
sim <- simulate_metacommunity(landscape_implicit(20), species_traits(tr, lambda = 1),
competition_matrix(tr, type = "phylo"),
dispersal = 0.01, n_steps = 1000)
Provete, D. B. (2026). comdynamite: Linking traits, phylogenies and biogeography in metacommunities. R package. https://doi.org/10.5281/zenodo.23993533
This DOI always points to the latest version; each release also has its own DOI
on Zenodo. In R, citation("comdynamite") gives the entry with the installed
version.
Cabral, J. S., Valente, L., & Hartig, F. (2017). Mechanistic simulation models in macroecology and biogeography: state-of-art and prospects. Ecography, 40, 267–280. https://doi.org/10.1111/ecog.02480
Leibold, M. A., Urban, M. C., De Meester, L., Klausmeier, C. A., & Vanoverbeke, J. (2019). Regional neutrality evolves through local adaptive niche evolution. Proceedings of the National Academy of Sciences, 116, 2612–2617. https://doi.org/10.1073/pnas.1808615116
Urban, M. C., & De Meester, L. (2009). Community monopolization: local adaptation enhances priority effects in an evolving metacommunity. Proceedings of the Royal Society B, 276, 4129–4138. https://doi.org/10.1098/rspb.2009.1382
Lande, R. (1979). Quantitative genetic analysis of multivariate evolution, applied to brain:body size allometry. Evolution, 33, 402–416. https://doi.org/10.1111/j.1558-5646.1979.tb04694.x
Thompson, P. L., Guzman, L. M., De Meester, L., Horváth, Z., Ptacnik, R., Vanschoenwinkel, B., Viana, D. S., & Chase, J. M. (2020). A process-based metacommunity framework linking local and regional scale community ecology. Ecology Letters, 23, 1314–1329. https://doi.org/10.1111/ele.13568
Hagen, O., Flück, B., Fopp, F., Cabral, J. S., Hartig, F., Pontarp, M., Rangel, T. F., & Pellissier, L. (2021). gen3sis: A general engine for eco-evolutionary simulations of the processes that shape Earth's biodiversity. PLoS Biology, 19, e3001340. https://doi.org/10.1371/journal.pbio.3001340
Colwell, R. K., & Winkler, D. W. (1984). A null model for null models in biogeography. In D. R. Strong, D. Simberloff, L. G. Abele, & A. B. Thistle (Eds.), Ecological Communities: Conceptual Issues and the Evidence (pp. 344–359). Princeton University Press. https://doi.org/10.1515/9781400857081.344
Kraft, N. J. B., Cornwell, W. K., Webb, C. O., & Ackerly, D. D. (2007). Trait evolution, community assembly, and the phylogenetic structure of ecological communities. The American Naturalist, 170, 271–283. https://doi.org/10.1086/519400