ODD Updated

An update to Volker Grimm and colleagues' Overview, Design concepts and Details (ODD) protocol for documenting individual and agent based models (I/ABM) has recently been published in Ecological Modelling. This renames the 'State variables and scales' element to 'Entities, state variables and scales', and the 'Input' element to 'Input data', introduces two new Design concepts ('Basic principles' and 'Learning'), and renames another ('Fitness' is now generalised to 'Objectives'). The Design concepts element can now also be shortened such that it is not required to include any design concept that is irrelevant to the model, and expanded to include new design concepts more appropriate to the model being described. Other clarifications of intentions in the original protocol have been made.


Introduction
originally developed the Overview, Design concepts and Details (ODD) protocol for documenting individual and agent based models (I/ABM) to address frustrations with the lack of consistency in the text describing such models in journal articles (mainly in the field of ecology). In particular, such descriptions were often incomplete in the sense that they did not provide enough information to replicate the results, and/or were difficult to read because the information was not presented in a logical order. Similar frustrations have been expressed by authors concerned with agent-based social simulations (Treibig and Klugl 2009 ;Janssen et al. 2008;Richiardi et al. 2006 ), some making their own proposals for documentation standards. The ODD protocol has been widely adopted in ecological models (about 70% of articles citing Grimm et al. (2006) are in that area (Grimm et al. 2010 )).
Issues with replication are commonplace in social simulation just as they are in ecology, and there have been various activities in the community that have been specifically aimed at addressing them. Three model-to-model workshops have been held, two of which have been the subject of special sections in this journal (Hales et al. 2003;Rouchier et al. 2008 ). Furthermore, the forum of JASSS has been allocated to reports on replications of agent-based models (recent examples include Miodownik et al. (2010), Macy and Sato ( 2010) and Will (2009)). Further, the annual Volterra prize for replication has been issued with the aim of demonstrating the robust use of agent-based models, the first winner of which was Radax and Rengs (2010).
In the meantime, the use of ODD in the social simulation community is small but growing. Grimm et al.'s ( 2010) review of uses of ODD categorised just two of 54 papers as being in the social sciences, though two of the other papers might also be regarded as social simulations. Purpose Many articles were found to have left out 'Purpose', one possible motivation being that it repeats material that may already have been provided in the introduction to the article. Though the new protocol retains 'Purpose' there is an emphasis on keeping the statement short.

Entities, state variables and scales
This element has been renamed from 'State variables and scales' to 'Entities, state variables and scales', to move beyond a point where all that matters is the variables in the model; often grouping the variables into entities allows the model to be more clearly described. It is also clarified that 'state variables' can include nonnumeric discriminants of objects, such as variables determining behaviour or strategies.

Process overview and scheduling
The review found that schedules were often still not described in enough detail to enable replication, despite using ODD. The definition of 'Process overview and scheduling' has therefore been specified more precisely, and recommends the use of pseudo-code to describe the schedule, which should include descriptions of how execution is ordered when a process is conducted for multiple agents.

Design concepts
Two new headings were introduced to this element: 'Basic principles' and 'Learning', and the 'Fitness' design concept was generalised to 'Objectives'. However, the main change to the 'Design concepts' element was to introduce greater flexibility. For smaller models, some of the design concepts are not relevant, in which case they can be ignored. For other models, authors may feel that important concepts underlying the design are not in the ODD protocol. Here, these concepts should be given a short heading and included at the end of the element, making it clear that they are not 'ODD-standard' design concepts.
The 'Objectives' design concept encompasses a more general idea than that of 'Fitness', which applies to any aspect of an individual's behaviour that is aimed at increasing their success in achieving one or more objectives. Here, the protocol stipulates that authors record those objectives, how success is measured, and how agents choose between several options with differing expected success (a particular issue where there are multiple objectives). The 'Learning' design concept was introduced to allow authors to describe how agents adapt their decision-making processes to improve the expected success with which objectives are achieved. The distinction between 'Objectives' and 'Learning' is somewhat subtle; if an agent decides what it will do using a set of rules R, then the 'Objectives' are what the agent is trying to do by applying R. By contrast, 'Learning' refers to how R is changed in the light of experience to improve the agent's ability to achieve its objectives.
The 'Basic principles' design concept is provided to allow authors to describe theories, hypotheses, and modelling approaches underpinning the design. No significant changes were made to the 'Initialisation' element.

Input data
The name and description of the 'Input' element were changed slightly to clarify that it refers to time-series data used while the model is running. (Initialisation, by contrast, describes how values are found for the state variables at time 0.) Such data might be referred to as scenario, or driving data, and the variables they give values for as exogenous.

Submodels
The review found a mismatch between the processes named in the 'Process overview and scheduling' element and subheadings of the 'Submodels' element. It was also not clear in the original protocol specification that the factual description of a submodel (i.e. its equations, rules and algorithms) and its rationale should be separated. The protocol description was amended to make appropriate clarifications.

Conclusion
Hopefully the revisions to ODD increase its relevance and utility to the social simulation community. Indeed, at the 2010 World Congress on Social Simulation in Kassel, Janssen's (2010) plenary talk announced progress on initiating a new journal emphasising empirically embedded uses of agent-based models, and that this journal would encourage use of ODD when describing models in its articles. However, an issue acknowledged in Polhill et al. (2008) was also raised in the ensuing debate: whilst the revised ODD has attempted to distance itself further from a focus that might be deemed better suited to describing models built with object-oriented programming languages, it may be that it is still not a good fit for models built in declarative programming languages popular with many researchers in agent-based social simulation (e.g. Alam et al. 2007 ;Edmonds and Hales 2004;Harbers et al. 2009 ;Moss 1998;Pajares et al. 2004 ). To assess this properly will require such researchers to evaluate ODD and see where it presents obstacles to the more natural description of declarative models. One area likely to be difficult is the 'Process Overview and Scheduling' element: in declarative models the order of execution of the rules is determined by the question asked of the model and the inference engine's mechanics [1] . One suggestion is that this element be used to give such information instead, with, perhaps, an interaction diagram showing which rules fire which other rules [2] , albeit that possibly the title of the element wouldn't match quite with the content. Similarly, though the element title and information content don't quite match, the 'Submodels' element could be used to give details on the rules. This is unlikely to be the final version of ODD, and should it become popular in the social simulation community there will be more feedback on which to base future revisions. In the meantime, you are encouraged to use and try ODD in your own articles, and invited to comment through the openabm.org forum.