Documentation Standards

The ODD Protocol

The ODD (Overview, Design concepts, Details) protocol is a standard format for describing agent-based models. It was introduced in 2006 (Grimm et al.. 2006), has been used widely in ecology and other disciplines (Polhill et al. 2008, Vincenot 2018), and has been a recommended as a documentation protocol by CoMSES since its original inception as OpenABM.

Still, authors of ODD model descriptions can struggle to understand and follow the standard. There were also some important aspects of using ODD which 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).