The Formal Model article format: justifying modelling intent and a critical review of data foundations through publication

Documenting complex models has long been a problem. Models are currently developed, implemented, and applied before review. Combined this leads to details hidden in the appendices or too little detail in the methods section to be reproducible. Modellers involve reviewers too late in the process. This does not allow them to flag issues, suggesting redesigns and reruns only after the analysis is complete. We propose splitting the model documentation, before analysis, into three steps: the Formal Model, Implementation Documentation, and Evaluation and Testing. Researchers can then use the well-built model for analysis. We introduce the first of these, the Formal Model as a peer-reviewed paper format that lays out the intentions for the model. The Formal Model includes reviewed literature that identifies the components of the model. Lays out the theoretical framework, modelling approaches and externalities. Plans to implement each process, with equations, descriptions, state variables and scales. Finally, the Formal Model gives the model’s strengths, weaknesses, exclusions, and place in the literature. We provide a flexible template for a Formal Model to aid in establishing a new common format. The Formal Model aims to improve transparency and provide a formal approach to documentation. Reviewers can help improve the model by identifying problems early. The Formal model contains the details needed to allow for reproducibility. It also encourages modellers to think about the consequences of what is and is not included within the model. And finally, it gives the credit that modellers deserve for the involved process of creating a model.