A first step towards improved model documentation: the Formal Model
Documenting complex models has been a long-standing problem, with currently applied methods often lacking the opportunity for reviewers to flag issues or suggest redesigns before the analysis is complete. The Formal Model, introduced recently in the open access journal Food and Ecological Systems Modelling Journal (FESMJ), aims to improve this process by providing a reproducible formal approach to model documentation, which allows reviewers to identify problems early on. Additionally, it encourages modellers to dive deep into the consequences of what is and is not included within the model. Last but not least, the Formal Model gives modellers the credit they very well deserve.
FESMJ is an open access journal, providing innovative publication forms on various outcomes of the research cycle, such as data, models, model validation studies, software, data analytics pipelines and visualisation methods. The authors of the Formal Model article format recently published in FESMJ – among whom two PoshBee members – propose splitting the documentation of models into three steps before analysis:
1) the Formal Model,
2) Implementation Documentation,
3) Evaluation and Testing.
The modelling cycle as it is often applied to ecological models. The Formal Model as described in this article occupies the top-right quadrant.
The first step – the Formal Model – includes reviewed literature, identifying the components of the model, lays out the theoretical framework, modelling approaches and externalities, and outlines the plans to implement each process, with equations, descriptions, state variables and scales. It also identifies the model’s strengths, weaknesses, exclusions, and place in the literature. Additionally, to help establish this reproducible common format of model documentation, the authors provide a flexible template for the Formal Model.
The PoshBee project is working on a new agent-based risk assessment model for Bombus terrestris, which will serve to look at the landscape-level effect of farming decisions, such as the amounts and timing of pesticide use or the use of field margins, wildflower strips and land set aside for nature. Such modelling can contribute to a deeper insight into complicated systems and will certainly make use of the Formal Model and all it has to offer.
Read the full paper "The Formal Model article format: justifying modelling intent and a critical review of data foundations through publication" here.