Authors: Rory Watts, Director, Forecast Health Australia
Botech (back of the envelope technology) is a protocol for the simulation of state transition models. The protocol dictates model creation and execution. Models are composed of nodes and links: nodes store values (balance), and links transmit values using a transition rate. Both balance and rate are arrays of 202 elements, representing populations from Males aged 0 to Females aged 100. Links have a direction from source to target, thus models are DiGraphs. All model components are nodes or links: people, resources, costs, constants, etc.
Botech is a superset of traditional state-transition models, adding features beyond expected behaviors. Botech is not software itself but has implementations that take a model file and produce an observation file based on simulation. Implementation requires:
- Code to parse the model file and create the runtime environment.
- Code to simulate the model.
- Code to log and export observations.
Botech files should be shareable and are intended to be plain text (e.g., JSON for configuration and CSV for observations).
Botech aims to:
- Produce complex, understandable, and reproducible models.
Complex models capture intricate behaviors. Understandable models allow assessment without programming expertise. Reproducibility ensures transparent assumptions and adaptable models. The protocol and implementation are open-source to leverage distributed intelligence and ensure good modeling practices.
- The protocol is under development, primarily through the
botech-pythonimplementation. - Links in other contexts may be referred to as
edgesorvertices. - Programming conventions typically follow Python naming conventions (e.g., dictionaries
{}, lists[]).
The model configuration should be plain text, suitable formats include json, yaml, and xml.
A typical configuration file:
{
"nodes": [],
"links": [],
"runtime": {},
"metadata": {},
"subroutines": []
}nodes: List of dictionaries where each element is the configuration of a node.links: List of dictionaries where each element is the configuration of a link.subroutines: List of dictionaries where each element is a subroutine.runtime: Optional dictionary of runtime variables.metadata: Optional dictionary of metadata key-value pairs.
Nodes hold a balance.
Components have a unique ID, recommended to use ULID.
Plain-text, human-readable label.
Plain-text description of the node's purpose.
May change the behavior of the node or link.
Nodes can generate arrays to store in their balance.
Specifications of the datafetcher are detailed elsewhere.
Boolean, whether to reset the balance of nodes to 0 at the end of each timepoint.
Boolean, whether to "age" the balance of nodes (shift values by 1 index) at each trigger.
Links take a balance from a source node, and pass it (or part of it) to a target node.
Components have a unique ID, recommended to use ULID.
Plain-text, human-readable label.
Plain-text description of the node's purpose.
Links require source and target IDs of the nodes they connect.
Links can generate arrays to determine their transition rate.
Specifications of the datafetcher are detailed elsewhere.
Links can occur after a certain trigger.
Specifications of the trigger are detailed elsewhere.
startYear: Integer indicating the start index/year (e.g., 2024).endYear: Integer indicating the end index/year (exclusive, e.g., 2030).
Key-value pairs for metadata about the model, e.g.:
{
"metadata": {
"author": "Botech",
"title": "Metadata Example",
"description": "An example metadata dictionary",
"year": "2023"
}
}Order of operations in a model, allowing specification of event sequences. If not links or nodes are specified, the method is called on all nodes.
The string corresponding to the method that the node or edge should perform e.g. flush or age or generate_balance.
A string description of what the subroutine is doing e.g. "distribute diagnosed cancers to stage I -> IV"
Applies only to subroutines where one node is running the method push_balance_to_edges to many edges. If False, then the balance is recalculated after each method (e.g. foo -> bar, recalculate balance, foo -> baz, recalculate balance, foo -> bux, recalculate balance). If True, then the balance is the same for all method calls, then the total is subtracted from the balance (e.g. foo -> bar, foo -> baz, foo -> bux, recalculate balance).
The set of link IDs to call the method on.
The set of link IDs not to call the method on.
The set of source nodes to call the method on.
The set of source nodes not to call the method on.
The set of target nodes to call the method on.
The set of target nodes not to call the method on.
The environment instantiates methods and data sources required for model simulation, running the simulate method to produce the observation file.
The environment creates a Botech Graph from the model configuration, translating nodes and links into components that maintain state, adjust balances, transmit values, and generate arrays.
Generate or retrieve data for nodes and links. Datafetchers are APIs returning values in a 2x101 array, registered with the environment.
Attach an observation file to the environment for data retrieval instead of using datafetchers, ensuring replicable models without sharing databases.
Attaching an observation file allows model replication and assumption modification, requiring identical runtime order.
The simulate method runs from start to end time, iterating through subroutines and performing specified methods on nodes. Events are recorded in the observation file.
Links can use source node values for dynamic interactions with target nodes.
Surrogate nodes affect transition rates around them, providing transparency in complex processes.
Trigger actions based on conditions, enabling complex behaviors and resource allocation.
botech-python is in development by Forecast Health Australia.
Email info@forecasthealth.org to contribute to Botech development.
Botech and its implementations are licensed under the Apache 2.0 license. License
- The OneHealth Tool (OHT) and Integrated Health Tool (IHT)
- The C4P Implementation by Levin Morgan LLC
- The TLO Model from the Thanzi La Onse collaboration
- Vivarium by IHME
- Squiggle
- TreeAge Software
- The Policy1 Modelling Platform
- The Optima Model
We acknowledge contributions from the World Health Organization, Cancer Research UK, Mr. Joseph Dunne, Mr. Timothy Knowles, and Mr. Angus Watkins.