ODD Protocol

The ODD Protocol: An Updated Definition

The following description and explanation of the seven elements of ODD is designed to fix the problems and ambiguities of the original protocol and its description. This updated ODD protocol fully replaces the original description given by Grimm et al. (2006), which is obsolete because of its ambiguities; however, the description of ODD’s overall purpose and rationale given by Grimm et al. (2006) is still valid. The ODD protocol is defined by the seven elements described below, their labels or identifiers, and the sequence in which they are described. For clarification, a few identifiers have been renamed slightly and two design concepts have been added (Table 1).

Using ODD means using exactly these identifiers in the order specified by the protocol (numbering the elements, though, from 1 to 7 is optional and can depend on journal formatting requirements). There are manuscripts that claimed to follow the ODD protocol, but the order of elements was changed, elements were lumped, modified identifiers were used, or entire elements omitted. The purpose of a standard is, however, to assure a common understanding of the work done. Therefore it must be followed consistently.

When ODD is used, it should be referred to in the following way: “the model description follows the ODD (Overview, Design concepts, Details) protocol (Grimm et al., 2006, this work)”. This is important because when using a standard it is necessary to refer to where it has been described. Moreover, systematic evaluation of the practice of using ODD, as has been done in this review, would be impossible without references to the publications presenting ODD and its update.

In the following update of ODD, each element is described by questions providing a kind of checklist and explanations. A template document for writing ODD model descriptions that contains the following questions and explanations is included in Supplementary material.

3.1. Purpose

• Question: What is the purpose of the model?
• Explanation: Every model has to start from a clear question, problem, or hypothesis. Therefore, ODD starts with a concise summary of the overall objective(s) for which the model was developed. Do not describe anything about how the model works here, only what it is to be used for. We encourage authors to use this paragraph independently of any presentation of the purpose in the introduction of their article, since the ODD protocol should be complete and understandable by itself and not only in connection with the whole publication (as is also the case for figures, tables, and their legends). If one of the purposes of a model is to expand from basic principles to a richer representation of real-world scenarios, this should be stated explicitly.

3.2. Entities, State Variables, and Scales

• Questions: What kinds of entities are in the model? By what state variables, or attributes, are these entities characterized? What are the temporal and spatial resolutions and extents of the model?
• Explanation: An entity is a distinct or separate object or actor that behaves as a unit and may interact with other entities or be affected by external environmental factors. Its current state is characterized by its state variables or attributes. A state variable or attribute is a variable that distinguishes an entity from other entities of the same type or category, or traces how the entity changes over time. Examples are weight, sex, age, hormone level, social rank, spatial coordinates, or which grid cell the entity is in, model parameters characterizing different types of agents (e.g., species), and behavioral strategies. The entities of an ABM are thus characterized by a set, or vector (Chambers, 1993; Huse et al., 2002), of attributes, which can contain both numerical variables and references to behavioral strategies.

One way to define entities and state variables is the following: if you want (as modelers often do) to stop the model and save it in its current state, so it can be re-started later in exactly the same state, what kinds of information must you save? If state variables have units, they should be provided. State variables can change in the course of time (e.g., weight) or remain constant (e.g., sex, species-specific parameters, location of a non-mobile entity). State variables should be low level or elementary in the sense that they cannot be calculated from other state variables. For example, if farmers are represented by grid cells which have certain spatial coordinates, the distance of a farmer to a certain service centre would not be a state variable because it can be calculated from the farmer’s and service centre’s positions.

Most ABMs include the following types of entities:

• Agents/Individuals: A model can have different types of agents; for example, wolves and sheep, and even different sub-types within the same type, for example different functional types of plants or different life stages of animals. Examples of types of agents include the following: organisms, humans, or institutions. Example state variables include: identity number (i.e., even if all other state variables would be the same, the agent would still maintain a unique identity), age, sex, location (which may just be the grid cell it occupies instead of coordinates), size, weight, energy reserves, signals of fitness, type of land use, political opinion, cell type, species-specific parameters describing, for example, growth rate and maximum age, memory (e.g., list of friends or quality of sites visited the previous 20 time steps), behavioral strategy, etc.
• Spatial Units (e.g., grid cells): Example state variables include the following: location, a list of agents in the cell, and descriptors of environmental conditions (elevation, vegetation cover, soil type, etc.) represented by the cell. In some ABMs, grid cells are used to represent agents: the state and behavior of trees, businesses, etc., that can be modeled as characteristics of a cell. Some overlap of roles can occur. For example, a grid cell may be an entity with its own variables (e.g., soil moisture content, soil nutrient concentration, etc., for a terrestrial cell), but may also function as a location, and hence an attribute, of an organism.
• Environment: While spatial units often represent environmental conditions that vary over space, this entity refers to the overall environment, or forces that drive the behavior and dynamics of all agents or grid cells. Examples of environmental variables are temperature, rainfall, market price and demand, fishing pressure, and tax regulations.
• Collectives: Groups of agents can have their own behaviors, so that it can make sense to distinguish them as entities; for example, social groups of animals, households of human agents, or organs consisting of cells. A collective is usually characterized by the list of its agents, and by specific actions that are only performed by the collective, not by their constitutive entities.

In describing spatial and temporal scales and extents (the amount of space and time represented in a simulation), it is important to specify what the model’s units represent in reality. For example: “One time step represents 1 year and simulations were run for 100 years. One grid cell represents 1 ha and the model landscape comprised 1000×1000 ha; i.e., 10,000 square kilometers”.

3.3. Process Overview and Scheduling

• Questions: Who (i.e., what entity) does what, and in what order? When are state variables updated? How is time modeled, as discrete steps or as a continuum over which both continuous processes and discrete events can occur? Except for very simple schedules, one should use pseudo-code to describe the schedule in every detail, so that the model can be re-implemented from this code. Ideally, the pseudo-code corresponds fully to the actual code used in the program implementing the ABM.
• Explanation: The “does what?” in the first question refers to the model’s processes. In this ODD element only the self-explanatory names of the model’s processes should be listed: ‘update habitat’, ‘move’, ‘grow’, ‘buy’, ‘update plots’, etc. These names are then the titles of the submodels that are described in the last ODD element, ‘Submodels’. Processes are performed either by one of the model’s entities (for example: ‘move’), or by a higher-level controller that does things such as updating plots or writing output to files. To handle such higher-level processes, ABM software platforms like Swarm (Minar et al., 1996) and NetLogo (Wilensky, 1999) include the concept of the ‘Model’, or ‘Observer’, itself; that is, a controller object that performs such processes.

By “in what order?” we refer to both the order in which the different processes are executed and the order in which a process is performed by a set of agents. For example, feeding may be a process executed by all the animal agents in a model, but we must also specify the order in which the individual animals feed; that is, whether they feed in random order, or fixed order, or size-sorted order. Differences in such ordering can have a very large effect on model outputs (Bigbee et al., 2006; Caron-Lormier et al., 2008).

The question of when variables are updated includes the question of whether a state variable is immediately assigned a new value as soon as that value is calculated by a process (asynchronous updating), or whether the new value is stored until all agents have executed the process, and then all are updated at once (synchronous updating). Most ABMs represent time simply by using time steps: assuming that time moves forward in chunks. But time can be represented in other ways (Grimm and Railsback, 2005, Chapter 5). Defining a model’s schedule includes stating how time is modeled, if it is not clear from the ‘Entities, State Variables, and Scales’ element.

3.4. Design Concepts

• Questions: There are 11 design concepts, which were identified as explaining the main ideas underlying the design of ABMs (Railsback, 2001). To enhance readability, they should be presented in paragraphs with the following titles, and the following order:
  • Basic Principles: What are the general concepts or assumptions that underlie the model’s design? For example, if the model includes an equation for the temperature-dependence of the number of eggs laid by an animal, this equation should be introduced here. This part of the ODD should also describe what theories or hypotheses the model is built on, and the general way these are represented. Is there an optimization or adaptation underlying behavior? If individual or collective adaptive behavior is a central part of the model, this should be stated here. If the model represents processes for which competing theories or hypotheses exist, the theory or hypothesis chosen for the model should be stated and justified.
  • Emergence: What key results or outputs of the model are modeled as emerging from the adaptive traits, or behaviors, of individuals? In other words, what model results are expected to vary in complex and perhaps unpredictable ways when particular characteristics of individuals or their environment change? Are there other results that are more tightly imposed by model rules and hence less dependent on what individuals do, and hence ‘built in’ rather than emergent results?
  • Adaptation: What adaptive traits do the individuals have? What rules do they have for making decisions or changing behavior in response to changes in themselves or their environment? Do these traits explicitly seek to increase some measure of individual success regarding its objectives (e.g., “move to the cell providing fastest growth rate,” where growth is assumed to be an indicator of success; see the next concept)? Or do they instead simply cause individuals to reproduce observed behaviors (e.g., “go uphill 70% of the time”) that are implicitly assumed to indirectly convey success or fitness?
  • Objectives: If adaptive traits explicitly act to increase some measure of the individual’s success at meeting some objective, what exactly is that objective and how is it measured? When individuals make decisions by ranking alternatives, what criteria do they use? Some synonyms for ‘objectives’ are ‘fitness’ for organisms assumed to have adaptive traits evolved to provide reproductive success, ‘utility’ for economic reward in social models, or simply ‘success criteria.’ Note that the objective of such agents as members of a team, social insects, organs (e.g., leaves of an organism), or cells in a tissue may not refer to themselves but to the team, colony, or organism of which they are a part.
  • Learning: If applicable, how do agents change their adaptive traits as a consequence of their experience? Learning is a special kind of adaptation in which agents change their behavioral rules or action-selection probabilities in response to interactions of the agent with its environment or other agents.
  • Prediction: Prediction is fundamental to successful decision-making; if an agent’s adaptive traits or learning procedures are based on estimating future consequences of decisions, how do agents predict the future conditions (either environmental or internal) they will experience? If appropriate, what internal models are agents assumed to use to estimate future conditions or consequences of their decisions? What tacit or hidden predictions are implied in these internal model assumptions?
  • Sensing: What internal and environmental state variables are individuals assumed to sense and consider in their decisions? What state variables of which other individuals and entities can an individual perceive; for example, signals that another individual may intentionally or unintentionally send? Sensing is often assumed to be local, but can happen through networks or can even be assumed to be global (e.g., a forager on one site sensing the resource levels of all other sites it could move to). If agents sense each other through social networks, is the structure of the network imposed or emergent? Are the mechanisms by which agents obtain information modeled explicitly?
  • Interaction: What kinds of interactions among agents are there? Are there direct interactions, for example, by mating or fighting, or indirect interactions, such as food competition or information exchange? If a grid is used, interactions between agents and their environment via the grid should be listed here.
  • Stochasticity: What processes are modeled by assuming they are random or partly random? Is stochasticity used, for example, to reproduce variability in processes for which it is unimportant to model the actual causes of the variability? Is it used to cause model events or behaviors to occur with a specified frequency?
  • Collectives: Do the individuals form or belong to aggregations that affect, and are affected by, the individuals? Such collectives can be an important intermediate level of organization in an ABM; examples include social groups, fish schools and bird flocks, and human networks and organizations. How are collectives represented? Is a particular collective an emergent property of the individuals, such as a flock of birds that assembles as a result of individual behaviors, or is the collective simply a definition by the modeler, such as the set of individuals with certain properties, defined as a separate kind of entity with its own state variables and traits?
  • Observation: What data are collected from the ABM for testing, understanding, and analyzing it, and how and when are they collected? For example, a model study may analyze results at the end of a simulation run and generate statistical samples for testing hypotheses or observing the emergence of certain behaviors.

The design concepts are an open-ended list that could be expanded as new concepts are identified. Concepts that are not relevant to a particular model should nevertheless be listed, but simply described as not applicable. Alternatively, if the list of design concepts grows long and more concepts need to be discussed, relevant subsets could be presented, and the relevance of the concepts included in the description should be made explicit.

3.5. Initialization

• Questions: What is the initial state of the model world, that is, at time t=0 of a simulation run? In detail, how many entities (of each type) are in the model and what are their state variables? Do the state variables have particular values or are they drawn from a distribution? Is initialization always the same, or is it allowed to vary among simulations?
• Explanation: For example, if initial agent numbers are drawn from a distribution, it is usually appropriate to state what mean and variance or other distributional parameters are used. If initial agent numbers, locations, and/or state variables come from data, this should be stated and data sources provided.

3.6. Input Data

• Questions: Does the model use input from external sources such as data files or other models to represent processes that change over time? What input data does the model use?
• Explanation: Aside from initialization, many models use input data to drive environmental variables that change over time, or that represent different scenarios. For example, weather data might be read in from files. If the model is coupled to another model, this should be stated and the other model described. In this context, coupling means that the input from one model drives the other, rather than both models running simultaneously.

3.7. Submodels

• Questions: What, in detail, are the submodels that represent the processes listed in “Process Overview and Scheduling”? What are the equations used? If appropriate, what are the parameters of the equations, their units, and the sources of values for parameters? This element may include any assumptions about processes or parameters that were required to simplify the model.
• Explanation: Submodels are usually represented by blocks of pseudocode, including equations, by algorithms, or by flow charts. Often submodels are described in sub-sections under the main heading “Submodels”. Descriptions of submodels should be as detailed as possible, so that the model could be reproduced without looking at the source code of the model.

Summary

Table 1: Comparison of the original and updated ODD protocols.

The table summarizes the changes to the ODD protocol and the detailed explanations provided above aim to clarify the requirements for documenting an agent-based model comprehensively. Adhering to this updated ODD protocol ensures clarity, reproducibility, and thorough understanding of the model for anyone reviewing the description.