mrangr: An R package for mechanistic simulation of metacommunities

1. Metacommunity theory unifies ecology by integrating local biotic interactions with regional dispersal and environmental filtering. However, testing theoretical predictions against empirical data remains challenging due to the difficulty of disentangling these processes in nature and the confounding effects of imperfect detection. 2. Here, we introduce mrangr, an R package designed for the mechanistic, spatially explicit simulation of multispecies communities. Unlike correlative approaches, mrangr strictly distinguishes between the fundamental niche (determined by abiotic carrying capacity) and the realised niche (an emergent property of biotic interactions). 3. The package implements a generalized Lotka-Volterra framework on a lattice grid (via the terra ecosystem), allowing users to simulate diverse interaction types — including competition, predation, and facilitation — alongside species-specific dispersal kernels. A defining feature is the "Virtual Ecologist" module, which samples the simulated "ground truth" with user-defined observation errors and sampling designs, thereby mimicking the constraints of real-world biodiversity surveys. 4. We demonstrate the package’s capabilities through three case studies: (i) quantifying the scale-dependent effects of dispersal on α, β, and γ diversity, (ii) testing the conditions under which the competition-colonization trade-off promotes coexistence in the presence of fitness inequalities, and (iii) assessing the recoverability of fundamental niches from imperfect observational data constrained by biotic interactions. 5. By providing a flexible platform to generate synthetic data with known underlying mechanisms, mrangr enables researchers to benchmark statistical models, assess sampling strategies, and rigorously test hypotheses at the interface of theoretical and empirical macroecology.