Boxology: How we designed an ABM collaboratively with the Open Data Institute

In order to build an ABM you need to work from a design. At Sandtable, we have long separated the formal, mathematical design that is used as the basis for creating model code from a more informal, conceptual design that we work through with clients. We call this conceptual design a boxology, mainly because it has lots of boxes in it. (The term ‘boxology’ appears to have originated in the hacker community, as a phrase to describe ‘box and arrow drawings’ (Raymond, Eric (1996). The New Hacker’s Dictionary. The MIT Press. ISBN 978-0262680929.). It’s occasionally used as a perjorative, but we’re reclaiming it here.)

In developing the thinking behind boxology development we owe a debt of gratitude to ecological modeller Volker Grimm, whose work on the ODD (Overview, Design concepts, and Details) protocol has been so important in standardising the way that agent-based models are presented in academic papers (See Grimm et al, ‘The ODD protocol: A review and first update.’ Ecological Modelling. 221 (2010) 2760-2768). Our boxology approach is a light-touch, informal hommage to Grimm and his colleagues.

We have refined the boxology development process as we have used it with our clients over the years. With clients that are open to reflecting with us on process, we are able to refine it more. The Open Data Institute (ODI), with whom we recently developed a model of the Data Economy, are very much open to reflecting on process, so we owe them particular thanks for moving our approach further forward

What follows is a very brief overview of the boxology development process we used (and refined) with the ODI.

Start with the questions the model is trying to address

  • The questions are likely to be of the form: what happens to X if we do Y (or if Y happens), where X and Y are some kind of macro variable or property
  • Think about how X and Y will manifest themselves in the model. Are they aggregates of micro-level properties across agents (such as wealth or economic output or frequency of acquisition)? Are they themselves aspects of the environment (such as ease of access to capital)?
  • Think about what other things and properties, in addition to those that have to do with X and Y, that will need to be in the model in order for it to make sense as a whole, e.g. demographic variation.

What types of agent will we need?

  • Agents are elements of the model that make choices: decision-making units.
  • There may be different types of agent. Agents of different types have fundamentally different structures, and typically have different choices available to them
  • Everything that isn’t an agent in the model is an element of the environment. The environment can include things that agents consume, or sell. It can also include global conditions, such as the weather.

Think about the properties (or attributes) of the agents

  • Individual agents may differ from agents of the same type in terms of their properties (the values of their attributes)
  • Are the properties of the agents static or dynamic? If they are dynamic, are they programmed as time series to evolve over the course of the simulation (e.g. age), or do they change in response to what’s going on in the model (e.g. wealth)?

Think about the choices and decisions the agent will need to make (the behavioural rules)

    • The best way to start thinking about model behaviour is to think about the choices that agents might make and the factors that might drive those choices

Choices are likely to be driven by a range of environmental factors, as well as by the properties of other agents.

  • If the order in which those choices are made makes a difference, in what order do they need to be made? Or should agents be allowed to decide for themselves what order to make the choices? If they decide the order themselves, on what basis do they make that decision?
  • Agents make choices by selecting the option that looks best to them from their perspective. This means they compare their options on a range of measures and assign some kind of ‘score’ to each
  • In technical terms, we often implement choices as utility functions: the agent tends to make choices based on a consideration of the utility of the range of options available to them. Individual agents attempt to maximise utility through their choices.
  • If choices involve other agents (interactions) how will they work? Will the agents just ‘do’ things to other agents or will they make requests and get responses (i.e. some notion of agreement or mutual consent)?


Think about the environment, and its properties

  • What aspects of the environment are static, and which dynamic?
  • If aspects of the environment are dynamic, how do they change? Do they change according to a pre-programmed time-series input, or do they change in response to what is going on in the model – for example, the choices made by agents?

Think about the granularity of time in the model

  • What is the correct time step for the model, and what happens in a single time step?
  • What ‘housekeeping’ or other process steps need to take place in the model (e.g agents get older, new agents are born or die)?

Capture all of the above on a single, A3 sized, sheet of paper

The output of the boxology development process is the boxology itself. The format is flexible, but we aim to capture, at least:

  • The different kinds of agent in the model and their attributes
  • The elements of the environment
  • The behavioural rules that govern the choices the agents make, and any process steps that need to take place
  • The ‘tick cycle’, which covers the order in which choices or process steps take place

The boxology we developed for the ODI Data Economy Model is shown below:


In conclusion

  • The boxology development process is a very useful tool for creating model designs collaboratively with clients.
  • It is accessible to people unfamiliar with ABM, whilst being informative and useful as a guide for modellers. It fosters a shared understanding.
  • Once completed, the boxology document is a go-to reference for modellers and clients alike.

Comments are closed.