mrangr: An R package for mechanistic simulation of metacommunities

Katarzyna Markowska , Michał Wawrzynowicz , Lechosław Kuczyński

Validating complex correlative algorithms requires synthetic spatial data in which the mechanisms underlying community assembly are known. However, generating realistic "ground truth" datasets remains computationally challenging, primarily because many spatial simulators implicitly conflate the fundamental and realised niches in their environmental inputs. Here, we introduce mrangr, a high-performance R package designed for the mechanistic, spatially explicit simulation of multispecies communities. Built upon the terra spatial ecosystem, the software implements a population-level generalised Lotka-Volterra (GLV) framework across lattice grids. By strictly separating abiotic carrying capacities from an asymmetric interaction matrix, mrangr enables the realised niche to emerge dynamically through local demography, biotic interactions and dispersal. A defining feature of the package is the integrated "Virtual ecologist" module: dedicated observation layer that applies spatial masking and probabilistic detection errors to the simulation outputs, mimicking the constraints of empirical biodiversity surveys. We demonstrate the computational flexibility of the package through three case studies: (i) generating synthetic spatiotemporal arrays to quantify the scale-dependent effects of dispersal on α, β, and γ diversity; (ii) constructing an in-silico sandbox to isolate the competition-colonisation trade‑off; and (iii) benchmarking the ability of correlative models to successfully reconstruct fundamental niches under strong biotic constraints. By providing a complete, end-to-end generative data pipeline, mrangr enables computational ecologists to rigorously benchmark statistical models, optimize sampling geometries, and rigorously test hypotheses at the interface of theoretical ecology and spatial data science.