Documentation Standards

The ODD Protocol

The ODD (Overview, Design concepts, Details) protocol is a set of documentation guidelines designed to describe agent-based models as fully as possible. It was introduced in 2006 (Grimm et al.. 2006) and has been adopted broadly in ecology and other disciplines (Polhill et al. 2008, Vincenot 2018). It has been recommended as a documentation protocol since 2007 when CoMSES.Net was still emerging as OpenABM.org.

Authors of ODD model descriptions sometimes struggle to fully adopt the spirit of the standard, however. There were also some important aspects of ODD that were not always addressed in published ODD descriptions. In Grimm et al. (2020), 19 authors from ecology and social sciences list several issues that may have prevented a wider and more consistent use of ODD and offer possible solutions with extensive supplementary material to illustrate these solutions.

Supplement 1 (S1) is a detailed introduction and guide on how to use ODD with a summary of the rationale for each ODD element, a list of typical misinterpretations, a checklist of questions, and examples from existing publications. S1 should help ODD beginners write complete and consistent ODDs, and help reviewers check for ODD consistency.

The remaining supplements also address:

• How to write summary ODD model descriptions for the main text of a publication, while the full ODD is in the supplement. (summary ODD; S2)
• How to write ODDs for very complex models, where complex submodels have their own ODD structure (nested ODDs; S3)
• How to write ODDs for models based on earlier models and their ODDs (delta ODD; S4)
• How to license your ODD so others can use them (licensing ODD; S5)
• Examples of TRACE documents (transparent and comprehensive ecological modeling), which document the entire modelling process, not just the model itself (TRACE examples; S6)
• Suggestions for standardizing the description of simulation experiments carried out to test, analyze, and use a model (simulation experiments in ODD; S7)

The only change to ODD itself is in the element, 1. Purpose which is now called 1. Purpose and patterns, i.e., it also lists the patterns observed in reality which will be used to claim that the model is realistic enough for its purpose (Edmonds et al. 2019). This is important because those patterns strongly influence model design. This also links ODD to the general strategy of pattern oriented modelling (Grimm and Railsback 2012, Railsback and Grimm 2019).

The authors also discuss how ODDs can be better linked to program code and how to deal with the tension between the narrative of a model and its technical description via ODD.

The authors hope that the new Open Access article and the supplements will make it easier to use ODD and make ODD model descriptions more useful and coherent. They should also facilitate the use of ODD+D, a refined standard for describing models that include human decision making (Müller et al. 2013).

If you are interested in contributing to the development of ODD or have feedback on it, please feel free to drop us a line in our documentation standards forum category.