<b><i>figsimR</i></b><b>: A Mechanistic Simulator for Diagnosing Community Assembly and Quantifying Theoretical Boundaries</b>

One of the central challenges in ecology is to account for the variability observed in nature. Traditional models have largely focused on predicting mean patterns, often overlooking the information embedded in ecological variance itself. We argue that mismatches between theory and empirical reality should not be dismissed as model failure, but instead embraced as a powerful diagnostic of theoretical limits. Standardizing and replicating such diagnostic assessments requires dedicated computational tools. To this end, we present <i>figsimR</i>, an open-source, modular R package designed to construct a “Full Intrinsic Model” (FIM)—a system-specific theoretical model that incorporates all known internal mechanisms. From this, figsimR generates a purely theory-driven “Stochastic Envelope” that defines the boundary of model-predicted community variability. By comparing this envelope with empirical observations, users can quantify what we call the “Variation Gap”—the divergence between theoretical predictions and real-world variability. Moreover, figsimR’s modular architecture enables systematic “mechanism knockout experiments,” allowing researchers to dissect the relative contribution of each internal process to community structure, much like gene knockout approaches in genetics. Using a well-studied fig–wasp mutualistic system as a case study, we demonstrate how figsimR reveals a substantial variation gap and identifies spatial niche partitioning as the key internal driver maintaining theoretical community structure. figsimR offers both a transferable research framework and a powerful computational toolbox, designed to shift ecological modeling from predicting means to explaining variability—a step toward a more diagnostic and mechanistic science of community assembly.figsimR_mee_run_all.R: A one-click script reproduces Figs. 1–4 with fixed random seeds.生态学领域的核心挑战之一，便是阐释自然界中观测到的变异性。传统模型大多聚焦于预测均值格局，却往往忽略了生态学变异本身所蕴含的信息。我们认为，理论与实证现实之间的偏差不应被简单归因于模型失效，而应被视作诊断理论局限性的有力依据。标准化与复现这类诊断评估，需要专门的计算工具。为此，我们推出figsimR——一款开源模块化R语言工具包，旨在构建“全内在模型（Full Intrinsic Model，FIM）”，即针对特定生态系统、纳入所有已知内在机制的理论模型。基于该模型，figsimR可生成完全由理论驱动的“随机包络线（Stochastic Envelope）”，用以界定模型预测的群落变异性边界。通过将该包络线与实证观测结果进行对比，用户可量化我们所称的“变异缺口（Variation Gap）”，即理论预测与现实变异性之间的偏差程度。此外，figsimR的模块化架构支持开展系统性的“机制敲除实验”，使研究者能够剖析各内在过程对群落结构的相对贡献，这与遗传学中的基因敲除方法类似。我们以研究较为充分的榕-蜂互利共生系统作为案例，展示了figsimR如何揭示显著的变异缺口，并确定空间生态位分化是维持理论群落结构的核心内在驱动因子。figsimR既提供了可迁移的研究框架，也打造了功能强大的计算工具箱，旨在推动生态学建模从预测均值转向解释变异性，这是迈向更具诊断性、更注重机制的群落构建科学的重要一步。附：figsimR_mee_run_all.R：一键式脚本可通过固定随机种子复现图1至图4。