Welcome to IDM tuberculosis modeling¶
The Institute for Disease Modeling (IDM) develops complex software modeling. The primary software, Epidemiological MODeling software (EMOD), helps determine the combination of health policies and intervention strategies that can lead to disease eradication. We share this modeling software with the research community to advance the understanding of disease dynamics.
Documentation structure¶
IDM recently separated the documentation into a training set that walks through tutorials that provide an introduction to disease modeling and disease-specific sets that provide guidance for researchers modeling particular diseases. For example, this documentation set includes general installation and usage instructions in addition to content specific to modeling tuberculosis and other airborne diseases.
“Using the model” contains information for researchers who want to create simulations of disease dynamics using EMOD as developed by IDM.
“Advancing the model” contains information for researchers and developers who want to modify the EMOD source code to add more functionality to the model.
What’s new¶
This topic describes new functionality and breaking changes for recently released versions of Epidemiological MODeling software (EMOD).
EMOD v2.10¶
The EMOD source v2.10 release includes new and updated malaria configuration, demographic, and intervention parameters. With this release, EMOD now uses Visual Studio 2015, Boost 1.61.0, and SCons 2.5.0.
EMOD software upgrades¶
- Microsoft Visual Studio
EMOD now uses Visual Studio 2015, and Visual Studio 2012 is no longer supported. The Visual Studio solution file in the EMOD source, EradicationKernel, has been updated for Visual Studio 2015. If you have custom reporter EMODules (DLLS) that were built using Visual Studio 2012, you will need to rebuild them with Visual Studio 2015; otherwise, your simulation will crash when it attempts to load the DLLs built by Visual Studio 2012.
- Boost
EMOD now supports using Boost 1.61.0. If you continue to use Boost 1.51.0, you will get the following warning, “Unknown compiler version - please run the configure tests and report the results.”
- Environment variables
To make it easier to use Boost and Python with Visual Studio, IDM paths have been created. These two paths, IDM_BOOST_PATH and IDM_PYTHON_PATH, need to be added to your environment variables by using either the setx command from a command line or the Windows System Properties panel.
- SCons
EMOD was tested using SCons 2.5.0, as it supports Visual Studio 2015. If you do not add the new IDM environment variables for Boost and Python, you will need to modify the Boost and Python paths in the SConstruct file in the EMOD root directory.
- Python
EMOD was tested with Python 2.7.11 and 2.7.12. If you are building the EMOD executable (Eradication.exe) and have an earlier version of Python (for example, 2.7.2), you will see the following warning message on some files, “c:python27includepymath.h(22): warning C4273: ‘round’: inconsistent dll linkage.” Upgrade to Python 2.7.11 or 2.7.12 to get rid of the warning message.
For more information, see Prerequisites for working with EMOD source code.
EMOD installation¶
Epidemiological MODeling software (EMOD) can be installed on computers running Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit) or CentOS 7.1 on Azure. For both operating systems, there are relatively few prerequisites required and the EMOD executable (Eradication.exe) or Eradication binary is pre- built from the latest EMOD source code release. After completing installation, you can run simulations locally or on an HPC cluster using real-world data.
If you are not familiar with disease modeling, we recommend using the training documentation that uses the Quick Start with Excel Front End to walk through several disease modeling tutorials before installing and working directly with EMOD. You are also free to walk through those tutorials running simulations directly with EMOD as described here.
Note
The Quick Start can only be run locally on a 64-bit Windows computer and the Excel Front End is only supported on 32-bit Microsoft Excel, though there is a workaround if you do not want to reinstall your version of Excel. See Troubleshooting EMOD simulations.
The Quick Start is not updated as frequently as the EMOD source, so may not contain all parameters available in the latest version of EMOD. In addition, while you can modify the parameter values, you cannot add or subtract parameters from JSON files within the Excel Front End.
If you want to download and modify the EMOD source code and build the Eradication.exe or Eradication binary yourself, see EMOD source code installation.
Install EMOD on Windows¶
Follow the steps below to install EMOD on computers running Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit).
The EMOD executable (Eradication.exe) is tested using Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit). Windows HPC Server is used for testing remote simulations on a high-performance computing (HPC) cluster and the other Windows operating systems are used to test local simulations.
Install the Microsoft HPC Pack 2012 Client Utilities Redistributable Package (64-bit). See http://www.microsoft.com/en-us/download/details.aspx?id=36044 for instructions.
Install the Microsoft MPI v8. See https://www.microsoft.com/en-us/download/details.aspx?id=54607 for instructions, being sure to run the MSMpiSetup.exe file.
Download the EMOD executable (Eradication.exe). See EMOD releases on GitHub.
(Optional) Install plotting software¶
None of the following plotting software is required to run simulations with EMOD, but they are useful for creating graphs from and evaluating the model output. In addition, EMOD provides many Python scripts for analyzing data.
Note
IDM does not provide support or guarantees for any third-party software, even software that we recommend you install. Send feedback if you encounter any issues, but any support must come from the makers of those software packages and their user communities.
Python and Python packages¶
Python is required to install many of the software packages described below.
We recommended that you download some of the Python packages from http://www.lfd.uci.edu/~gohlke/pythonlibs, a page compiled by Christoph Gohlke, University of California, Irvine. The libraries there are compiled Windows binaries, including the 64-bit versions required by EMOD.
Install Python 2.7.11 or 2.7.12. See https://www.python.org/downloads/ for instructions.
In the Customize Python dialog box, verify that Add python.exe to PATH is selected to add Python to the PATH environment variable on your computer.
From Control Panel, select Advanced system settings, and then click Environment Variables.
Add a new variable called IDM_PYTHON_PATH and set it to the directory where you installed Python, and then click OK.
Open a Command Prompt window and type the following to verify installation:
python --version
The Python package manager, pip, is installed as part of Python 2.7.11 or 2.7.12 and is used to install other software packages.
The Python utilities dateutil, six, and pyparsing provide text parsing and datetime functionality.
Open a Command Prompt window.
Enter the following commands:
pip install python-dateutil pip install pyparsing
The NumPy package adds support for large, multi-dimensional arrays and matrices to Python.
Go to http://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy and select the WHL file for NumPy 1.11.3 (64-bit) that is compatible with Python 2.7.11 or 2.7.12.
Save the file to your Python installation directory.
Open a Command Prompt window and navigate to the Python installation directory, then enter the following, substituting the name of the specific NumPy WHL file you downloaded:
pip install numpy-1.x.x+mkl-cp27m-win_amd64.whl
Matplotlib is a Python library for making publication quality plots using syntax familiar to MATLAB users. Matplotlib also uses NumpPy for numeric manipulation. Output formats include PDF, Postscript, SVG, and PNG, as well as a screen display.
Go to http://www.lfd.uci.edu/~gohlke/pythonlibs/#matplotlib and select the WHL file for Matplotlib 1.5.3 (64-bit) that is compatible with Python 2.7.11 or 2.7.12.
Save the file to your Python installation directory.
Open a Command Prompt window and navigate to the Python installation directory, then enter the following, substituting the name of the specific matplotlib WHL file you downloaded:
pip install matplotlib-1.x.x+mkl-cp27m-win_amd64.whl
R¶
R is a free software environment for statistical computing and graphics.
Go to https://www.r-project.org/ and install R 3.2.0 (64-bit).
MATLAB¶
MATLAB is a high-level language and interactive environment for numerical computation, visualization, and programming. The MATLAB Statistics and Machine Learning Toolbox™ provides functions and applications to describe, analyze and model data using statistics and machine learning algorithms.
Go to http://www.mathworks.com/products/matlab/ and install MATLAB R2015a.
If desired, go to https://www.mathworks.com/products/statistics.html and install the MATLAB Statistics and Machine Learning Toolbox™ R2015a.
Install EMOD on CentOS on Azure¶
Follow the steps below to install EMOD on CentOS 7.1 on Azure environments. The setup script installs most prerequisite software, including Python and the Python packages dateutil, six, pyparsing, NumPy, and matplotlib. Other prerequisites, such as Boost 1.61.0 and Microsoft MPI v8, are declared by the script as required. Because the installation instructions will vary based on the particular distribution you are running, instruction information is not included here.
The Eradication binary is tested and supported on a CentOS 7.1 on Azure virtual machine. It has also been successfully built and run on Ubuntu, SUSE, and Arch, but has not been tested and is not supported on those Linux distributions.
Note
IDM does not provide support or guarantees for any third-party software, even software that we recommend you install. Send feedback if you encounter any issues, but any support must come from the makers of those software packages and their user communities.
The script provides the option of installing the EMOD source code and input data files provided by IDM, but these steps will install a pre-built version of the Eradication binary. For information on building the Eradication binary from source code, see EMOD source code installation.
Before you begin, you must have the following:
sudo privileges to install packages
15 GB free in your home directory (if you install the EMOD source code and input data files)
An Internet connection
Download and run the PrepareLinuxEnvironment.sh script on EMOD releases on GitHub.
Respond to the prompts for information while the script is running. If you choose not to download the EMOD source and input data files, do the following. This example assumes that a directory named IDM is in your home directory and contains the subdirectories EMOD, containing the EMOD source code, and EMOD_InputData, containing the input data files directory.
Set the EMOD_ROOT environment variable to the path to the EMOD source path:
EMOD_ROOT=~/IDM/EMOD
Put Scripts and . in the path:
export PATH=$PATH:.:$EMOD_ROOT/Scripts
Create a symlink from the EMOD directory to InputDataFiles:
ln -s /home/general/IDM/EMOD-InputData $EMOD_ROOT/InputData
If you run simulations using in the same session that you updated EMOD_ROOT and the Scripts path, reload the .bashrc file using
source .bashrc.
Download the Eradication binary for CentOS 7.1 on Azure. See on EMOD releases on GitHub.
(Optional) Install plotting software¶
None of the following plotting software is required to run simulations with EMOD, but they are useful for creating graphs from and evaluating the model output. In addition, EMOD provides many Python scripts for analyzing data.
Note
IDM does not provide support or guarantees for any third-party software, even software that we recommend you install. Send feedback if you encounter any issues, but any support must come from the makers of those software packages and their user communities.
R¶
R is a free software environment for statistical computing and graphics.
Go to https://www.r-project.org/ and install R 3.2.0 (64-bit).
MATLAB¶
MATLAB is a high-level language and interactive environment for numerical computation, visualization, and programming. The MATLAB Statistics and Machine Learning Toolbox™ provides functions and applications to describe, analyze and model data using statistics and machine learning algorithms.
Go to http://www.mathworks.com/products/matlab/ and install MATLAB R2015a.
If desired, go to https://www.mathworks.com/products/statistics.html and install the MATLAB Statistics and Machine Learning Toolbox™ R2015a.
Introduction to the software¶
The Institute for Disease Modeling (IDM) develops detailed simulations of disease transmission through the use of extensive and complex software modeling. The primary software, Epidemiological MODeling software (EMOD), helps determine the combination of health policies and intervention strategies that can lead to disease eradication. EMOD calculates how diseases may spread in particular areas and is used to analyze the effects of current and future health policies and intervention strategies. It supports infectious disease campaign planning, data gathering, new product development, and policy decisions. We share this modeling software with the research community to advance the understanding of disease dynamics.
EMOD supports the following simulation types for modeling a variety of diseases:
Generic disease (GENERIC_SIM)
Vector-borne diseases (VECTOR_SIM)
Malaria (MALARIA_SIM)
Tuberculosis (TB_SIM)
Sexually transmitted infections (STI_SIM)
HIV (HIV_SIM)
The illustration below shows how the simulation types are built upon one another. All parameters available in the generic simulation type are inherited by the vector simulation type. The vector simulation type adds additional parameters specific to the biology of vector-borne diseases, which in turn are inherited by the malaria simulation type and so on. Therefore, depending on the simulation type you select, different parameters are available for you to use.
In addition, simulation types for broader classes of disease can be extended to build your own disease-specific model.
Simulation type inheritance¶
EMOD is a stochastic, agent-based model that simulates the actions and interactions of individuals within geographic areas known as nodes to understand the disease dynamics in a population over time. EMOD can produce statistically significant results over a broad set of parameters and scenarios. Quantitative analysis of the simulated output enables disease eradication efforts to make more data-driven decisions. The IDM research team has published many articles related to modeling, as well as the modeling concepts underpinning EMOD. For a list of published articles, see IDM Publications.
This section provides the conceptual overview of EMOD. The architecture diagram below shows, at a high level, how the system functions. If you run simulations in parallel on a multi-node cluster, there is also a Message Passing Interface (MPI) component used to pass data between multiple instances of EMOD.
High-level EMOD system architecture¶
Input data files¶
Not all files accepted as input for running a simulation are considered input data files. Rather, input data files contain the relatively fixed information about a population to model. For example, climate, geography, demographics, and migration data.
Configuration file¶
The configuration file contains parameters that control many different aspects of the simulation. EMOD provides hundreds of parameters for you to configure your simulation. For example, configuration parameters can control the following:
The disease or disease class to simulate (simulation type)
The name and location for the input data files and output files
Whether to include births, deaths, and migration
Disease attributes, such as infectivity, transmission, immunity, and mortality
The computing resources to use
Campaign file¶
The campaign file contains parameters that distribute outbreaks and the interventions used to control the spread of disease. For example, campaign parameters can control the following:
Target demographic (age, location, gender, etc.) for interventions
Diagnostic tests to use
The cost and timing of interventions
Running a simulation¶
The EMOD executable (Eradication.exe) accepts the input data, configuration, and campaign files and then simulates the susceptibility and infection of individuals within each geographic node. The simulation type controls the transmission mechanism of the disease. After the simulation is complete, the Eradication.exe produces output reports that describe various aspects of the disease dynamics within the modeled population.
You can run simulations locally or on a multi-core cluster. Because the model is stochastic, you must run simulations multiple times to produce scientifically valid results.
Depending on how you run the simulation, other programs or environments external to EMOD may also output error and logging files.
Output files¶
After the simulation finishes, a reporter extracts simulation data, aggregates it, and outputs it to a file (known as an output report). Most of the reports are also JSON files, the most important of which is InsetChart.json. The InsetChart.json file provides simulation-wide averages of disease prevalence at each time step.
See the topics listed below for a more detailed explanation of each of these system components.
Input data files¶
EMOD accepts the following categories of input data files that contain the relatively fixed information about the population within each geographic node. For example, the number of individuals, geographic data, climate, demographics, and migration data. This is in contrast to the demographic, geographic, and migration parameters in the configuration file that control simulation-wide qualities, such as enabling air migration across all nodes in the simulation.
Although a demographics file is the only required input data file, additional files are generally needed for a realistic simulation. The demographics files use JavaScript Object Notation (JSON). The other input data files use both a JSON file for metadata and an associated binary file that contains the actual data.
The Institute for Disease Modeling (IDM) provides collections of input data files for many different locations in the world for download on GitHub. Except for the demographics file, you will typically use these input data files in their default state. See Use input data files for more information.
Demographics¶
Demographics files are JSON formatted files containing information on the demographics of the population in a geographical region to simulate. For example, the number of individuals and the distribution for age, gender, immunity, risk, and mortality.
In addition, demographics files are useful for creating heterogeneous groups within a population. You can define values for accessibility, age, geography, risk, and other properties and assign individuals to groups based on those property values. For example, you might want to divide a population up into different bins based on age so you can target interventions to individuals in a particular age range. Another common use is to configure treatment coverage to be higher for individuals in easily accessible regions and lower for individuals in areas that are difficult to access.
EMOD assumes homogeneous mixing and disease transmission for the generic simulation type. You can use the HINT feature to add heterogeneous transmission to your generic model. You cannot manually configure heterogeneous transmission using HINT with other simulation types because the heterogeneity in transmission for specific diseases and disease classes is already configured by the simulation type.
You can specify multiple demographics files, which function as a “base layer” file and one or more “overlay” files that override the base layer configuration. Overlay files can change the value of parameters already specified in the base layer or add new parameters. Support for multiple demographics layers allows for the following scenarios:
Separating different sets of parameters and values into individual layers (for example, to separate those that are useful for specific diseases into different layers)
Adding new parameters for a simulation into a new layer for easier prototyping
Overriding certain parameters of interest in a new layer
Overriding certain parameters for a particular sub-region
Simulating subsets of a larger region for which input data files have been constructed
Migration¶
Migration files describe the rate of migration of individuals in and out of a geographic node. There are four types of migration files that can be used by EMOD: local migration, regional migration, air migration, and sea migration.
For all types, migration data is contained in a set of two files, a JSON metadata file with header information and a binary data file with the actual migration data. Both files are required. The basic file structure is identical for all types, with the only exception being the number of columns per row allowed to each type.
Local migration describes the foot travel of people into and out of adjacent nodes. A local migration file is required for simulations that support more than one node.
Regional migration describes migration via a road or rail network. If a node is not part of the network, the regional migration of individuals to and from that node considers the closest road hub city. When you create the migration file, you must create a Voronoi tiling based on road hubs of the region, with each non-hub connected to the hub of its tile.
Air migration describes migration via airplane travel. It is usually required for simulations of an entire country or larger geographies.
Sea migration describes migration via ship.
Climate¶
There are two general types of climate files usable by EMOD: climate files generated through actual data, referred to as “climate by data,” and climate files generated from the Koppen classification system, referred to as “climate by Koppen.”
For both types, climate data is contained in a set of two files, a JSON metadata file with header information and a binary file that contains the actual climate data. Both files are required.
Climate by data files contain real data gathered from weather stations in the region to be simulated. This includes rainfall, temperature, relative humidity, and so on.
Climate by Koppen files contain the Koppen classifier for the region. The Koppen classification system is one of the most widely used climate classification systems. It makes the assumption that native vegetation is the best reflection of climate.
Load balancing¶
When running a simulation on a multi-core HPC cluster, you can include a load balancing file to control how the computing load is distributed across the cluster. The load balancing file is a binary file that allocates the simulation of each geographic node to cores in the cluster. If no file is submitted, EMOD allocates nodes to cores according to a checkerboard pattern.
Configuration file¶
The primary means of configuring the disease simulation is the configuration file. This required file is a JavaScript Object Notation (JSON) formatted file that is typically named config.json. The configuration file controls many different aspects of the simulation. For example,
The names of the campaign file and input data files to use
Simulation-wide demographics, climate, and migration data
General disease attributes such as infectivity, immunity, mortality, and so on
Attributes specific to the disease type being modeled, including treatment efficacy
The reports to output from the simulation
IDM provides complete simulation scenarios in the Regression directory on GitHub. Within each of the simulation subdirectories, there is a config.json file. The Scenarios subdirectory contains the files used in the Quick Start training tutorials.
The following is an example of configuration file.
{
"parameters": {
"Acquisition_Blocking_Immunity_Decay_Rate": 0.1,
"Acquisition_Blocking_Immunity_Duration_Before_Decay": 60,
"Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE",
"Animal_Reservoir_Type": "NO_ZOONOSIS",
"Base_Incubation_Period": 0,
"Base_Individual_Sample_Rate": 1,
"Base_Infectious_Period": 4,
"Base_Infectivity": 3.5,
"Base_Mortality": 0,
"Base_Population_Scale_Factor": 1,
"Birth_Rate_Dependence": "POPULATION_DEP_RATE",
"Birth_Rate_Time_Dependence": "NONE",
"Burnin_Cache_Mode": "none",
"Burnin_Cache_Period": 0,
"Burnin_Name": "",
"Campaign_Filename": "campaign.json",
"Climate_Model": "CLIMATE_OFF",
"Config_Name": "00_DEFAULT",
"Custom_Reports_Filename": "NoCustomReports",
"Death_Rate_Dependence": "NONDISEASE_MORTALITY_OFF",
"Default_Geography_Initial_Node_Population": 1000,
"Default_Geography_Torus_Size": 10,
"Demographics_Filenames": [
"../00_Default/demographics.json"
],
"Enable_Absolute_Time": "NO",
"Enable_Aging": 1,
"Enable_Birth": 1,
"Enable_Default_Reporting": 1,
"Enable_Default_Shedding_Function": 1,
"Enable_Demographics_Birth": 0,
"Enable_Demographics_Builtin": 0,
"Enable_Demographics_Gender": 1,
"Enable_Demographics_Other": 0,
"Enable_Demographics_Reporting": 1,
"Enable_Disease_Mortality": 0,
"Enable_Heterogeneous_Intranode_Transmission": 0,
"Enable_Immune_Decay": 0,
"Enable_Immunity": 1,
"Enable_Interventions": 1,
"Enable_Maternal_Transmission": 0,
"Enable_Property_Output": 0,
"Enable_Spatial_Output": 0,
"Enable_Superinfection": 0,
"Enable_Vital_Dynamics": 0,
"Geography": "",
"Immunity_Acquisition_Factor": 0,
"Immunity_Initialization_Distribution_Type": "DISTRIBUTION_OFF",
"Immunity_Mortality_Factor": 0,
"Immunity_Transmission_Factor": 0,
"Incubation_Period_Distribution": "FIXED_DURATION",
"Individual_Sampling_Type": "TRACK_ALL",
"Infection_Updates_Per_Timestep": 1,
"Infectious_Period_Distribution": "EXPONENTIAL_DURATION",
"Infectivity_Scale_Type": "CONSTANT_INFECTIVITY",
"Job_Node_Groups": "Chassis08",
"Job_Priority": "BELOWNORMAL",
"Listed_Events": [],
"Load_Balance_Filename": "",
"Local_Simulation": 0,
"Maternal_Transmission_Probability": 0,
"Max_Individual_Infections": 1,
"Max_Node_Population_Samples": 40,
"Migration_Model": "NO_MIGRATION",
"Minimum_Adult_Age_Years": 15,
"Mortality_Blocking_Immunity_Decay_Rate": 0.001,
"Mortality_Blocking_Immunity_Duration_Before_Decay": 60,
"Mortality_Time_Course": "DAILY_MORTALITY",
"Node_Grid_Size": 0.042,
"Num_Cores": 1,
"Number_Basestrains": 1,
"Number_Substrains": 1,
"PKPD_Model": "FIXED_DURATION_CONSTANT_EFFECT",
"Population_Density_C50": 30,
"Population_Density_Infectivity_Correction": "CONSTANT_INFECTIVITY",
"Population_Scale_Type": "USE_INPUT_FILE",
"Report_Event_Recorder": 0,
"Run_Number": 1,
"Sample_Rate_0_18mo": 1,
"Sample_Rate_10_14": 1,
"Sample_Rate_15_19": 1,
"Sample_Rate_18mo_4yr": 1,
"Sample_Rate_20_Plus": 1,
"Sample_Rate_5_9": 1,
"Sample_Rate_Birth": 1,
"Serialization_Test_Cycles": 0,
"Simulation_Duration": 90,
"Simulation_Timestep": 1,
"Simulation_Type": "GENERIC_SIM",
"Start_Time": 0,
"Susceptibility_Scale_Type": "CONSTANT_SUSCEPTIBILITY",
"Transmission_Blocking_Immunity_Decay_Rate": 0.1,
"Transmission_Blocking_Immunity_Duration_Before_Decay": 60,
"x_Air_Migration": 1,
"x_Birth": 1,
"x_Local_Migration": 1,
"x_Other_Mortality": 1,
"x_Population_Immunity": 1,
"x_Regional_Migration": 1,
"x_Sea_Migration": 1,
"x_Temporary_Larval_Habitat": 1
}
}
Overlay file¶
As you work more with EMOD, you may want to change the values of a view parameters of interest while keeping the rest constant, for example, when running simulation experiments or testing source code changes.
You have the option of creating an overlay file to keep configuration parameters of interest in a separate file from the complete configuration file that contains default values. These files can be flattened into a single file and the values in the overlay file will override those in the default file.
See Configuration parameters for a comprehensive list and description of all parameters available to use in the configuration file for this simulation type.
Campaign file¶
The campaign file is an optional file that distributes outbreaks and contains all parameters that define the collection of interventions that make up a disease eradication campaign. For example,
When, how, and who to test for a disease
When, how, and who to distribute treatments to
The vaccines or other preventative interventions to use
The medications to use for treatment
Like the configuration file, the campaign file is a JavaScript Object Notation (JSON) formatted file. It is hierarchically organized into logical groups of parameters that can have arbitrary levels of nesting. For some interventions, there can be a very complex hierarchical structure, including recursion. Typically, the file is named campaign.json. The relative path to this file is specified by Campaign_Filename in the configuration file.
To distribute an intervention, you must configure the following:
- campaign event
A JSON object that determines when and where an intervention is distributed during a campaign.
- event coordinator
A JSON object that determines who will receive a particular intervention during a campaign.
- intervention
A JSON object that determines what will be distributed to reduce the spread of a disease. An intervention can be distributed either to an individual (such as a vaccine, drug, or bednet) or to a node (such as a larvicide). Sometimes this can be an intermediate intervention that schedules another intervention.
IDM provides complete simulation scenarios in the Regression directory on GitHub. Within each of the simulation subdirectories, there is a campaign.json file. The Scenarios subdirectory contains the files used in the Quick Start tutorials.
Overlay file¶
As you work more with EMOD, you may want to change the values of a view parameters of interest while keeping the rest constant, for example, when running simulation experiments or testing source code changes.
You have the option of creating an overlay file to keep campaign parameters of interest in a separate file from the complete campaign file that contains default values. These files can be flattened into a single file and the values in the overlay file will override those in the default file.
See Campaign parameters for a comprehensive list and description of all parameters available to use in the campaign file for this simulation type.
Running a simulation¶
The EMOD executable (Eradication.exe) consumes the input data files, configuration file, and, optionally, campaign file to run simulations that model disease dynamics and campaign efficacy. You have a few different options for running simulations. The option you choose will depend upon whether you want to run one or more simulations, to run simulations locally or on a remote cluster (for large simulations or multiple simulations), or to run simulations for debugging the source code. This topic briefly describes the different options you have for running simulations.
Run a single simulation¶
You will generally want to run simulations using the EMOD command-line options. This will run a single simulation and put the output files in a local directory.
You must either download the latest version of Eradication.exe from GitHub or clone the EMOD source from GitHub and build Eradication.exe yourself. This gives you access to the latest features and parameters for EMOD.
Run multiple simulations¶
Because the EMOD model is stochastic, simulations must be run multiple times to return scientifically valid results. Therefore, you have the following options to run multiple simulations at a time, either locally or remotely on a high-performance computing (HPC) cluster. Generally, only small simulations should be run locally.
Many of these options are scripting languages that you can also use to modify the files consumed by EMOD, simplifying your workflow when running many simulations.
Run simulations for debugging¶
If you are helping advance the EMOD model by contributing to source code, there are other options for running simulations that provide debugging support. These options for running simulations are not recommended if you are not modifying the source code.
You can run a simulation locally from Visual Studio using the built-in debugger. You will be able to put in breakpoints and step through the code while inspecting the values of different state variables throughout the simulation.
You can use regression_test.py in the GitHub Regression directory to run multiple simulations on a cluster, including running the suite of regression tests run by the IDM testing team.
Output files¶
After running a simulation, the simulation data is extracted, aggregated, and saved as an output report. Depending on your configuration, one or more output reports will be created, each of which summarize different data from the simulation. Output reports can be in JSON, CSV, or binary file formats.
The EMOD functionality that produces an output report is known as a reporter. EMOD provides several built-in reporters for outputting data from simulations. By default, EMOD will always generate the report InsetChart.json, which contains the simulation-wide average disease prevalence by time step. If none of the provided reports generates the output report that you require, you can create a custom reporter.
If you want to visualize the data output from an EMOD simulation, you must use graphing software to plot the output reports. In addition to output reports, EMOD will generate error and logging files to help troubleshoot any issues you may encounter.
Introduction to disease modeling¶
To understand the complex dynamics underlying disease transmission, epidemiologists utilize a set of models called compartmental models. Developed in the early 20th century, these models stratify a population into groups, generally based on their risk or infection status. Underlying these models is a system of differential equations, so the model is able to track the population as a function of time. Further, the models track the number of people in each category, are able to predict the various properties of pathogen spread, can estimate the duration of epidemics, and can be used to understand how different situations or interventions can impact the outcome of pathogen spread. To see a typical plot of a population in SIR conditions, see the plot in Types of compartmental models. If you would like a more in-depth introduction to epidemiology and disease modeling, you may want to take the Epidemics course from The Pennsylvania State University through Coursera.
An agent-based model (ABM) is another powerful tool used to help understand the complexity inherent in disease transmission systems. These models form a type of “microscale model,” where they simulate the simultaneous interactions of agents in an effort to re-crate complex phenomena. Each agent (such as a human, or vector) can be assigned a variety of “properties” (for example, age, gender, etc), and their behavior and interactions with one another are determined by using decision rules. These models have strong predictive power, and are able to leverage spatial and temporal dynamics. Further, complex environments can be developed in which the agents act, and agents may “learn” from interactions or “adapt” to their environment. As a result, ABMs are excellent for identifying “emerging properties” of the system: patterns that are not explicitly modeled, but instead occur as a consequence of the rules that govern the agents.
Agent-based models are extensively used in epidemiology due to their predictive power in modeling the spread (or conversely, control) of epidemics. A popular type of ABM for this is one in which each agent’s rules follow the dynamics specified in the compartmental models, where each agent flows through the compartments as a function of both “within-host” rules (such as duration of infection) and interactions between agents (such as becoming infected when coming into contact with an infectious agent). By combining the epidemiological basis of compartmental models with the flexibility of an agent-based model, this type of ABM is quite powerful due to their ability to simultaneously address the ecology, epidemiology, and pathology of complex systems.
Why use disease modeling¶
Disease models play an important role in understanding and managing the transmission dynamics of various pathogens. We can use them to describe the spatial and temporal patterns of disease prevalence, as well as to explore or better understand the factors that influence infection incidence. Modeling is a key step in understanding what treatments and interventions can be most effective, how cost-effective these approaches may be, and what specific factors need to be considered when trying to eradicate disease.
Types of compartmental models¶
The following diagrams illustrate common compartmental models. See the Generic simulation tutorials in the Training documentation set for more information, as well as exercises on running EMOD simulations utilizing these models.
SIR Plot, showing typical categorization of a population into Susceptible, Infectious, and Recovered states.¶
Definitions¶
- Susceptible
Individual is able to become infected.
- Exposed
Individual has been infected with a pathogen, but due to the pathogen’s incubation period, is not yet infectious.
- Infectious
Individual is infected with a pathogen and is capable of transmitting the pathogen to others.
- Recovered
Individual is either no longer infectious, or “removed” from the population.
SI (Susceptible - Infectious) model¶
In this situation, people never leave the infectious state and have life-long infections. For example, herpes is a disease with life-long infectiousness. The dashed line shows how the model becomes an SIS (Susceptible - Infectious - Susceptible) model, where infection does not confer immunity (or there is waning immunity). Individuals have repeat or reoccurring infections, and infected individuals return to the susceptible state. For example, sexually transmitted diseases such as gonorrhea or chlamydia fall into this group.
SI - SIS model¶
SIR (Susceptible - Infectious - Recovered) model¶
In this category, individuals in the recovered state gain immunity to the pathogen. For example, measles, mumps, rubella, and pertussis may be modeled using the SIR framework. The dashed line shows how the model becomes an SIRS (Susceptible - Infectious - Recovered - Susceptible) model, where recovery does not confer life-long immunity, and individuals may become susceptible again.
SIR - SIRS model¶
SEIR (Susceptible - Exposed - Infectious - Recovered) model¶
In this category, individuals experience a long incubation duration (the “exposed” category), such that the individual is infected but not yet infectious. For example chicken pox, and even vector-borne diseases such as Dengue Hemorrhagic fever have a long incubation duration where the individual cannot yet transmit the pathogen to others. The dashed line shows how the model becomes an SEIRS (Susceptible - Exposed - Infectious - Recovered - Susceptible) model, where recovered people may become susceptible again (recovery does not confer life-long immunity). For example, rotovirus and malaria are diseases with long incubation durations, and where infection only confers temporary immunity.
SEIR - SEIRS model¶
Fundamental concepts in epidemiology and disease modeling¶
- Basic reproductive number (R0)
The average number of secondary infections generated by the first infectious individual in a population of completely susceptible individuals. R0=S*L* \(\beta\) (where S = the number of susceptible hosts, L = length of infection, and \(\beta\) = transmissibility). When R0> 1, disease will spread. It is essentially a measure of the expected or average outcome of transmission. This is the threshold parameter used to determine whether or not an epidemic will occur, and determines:
The initial rate of increase of an epidemic (the exponential growth phase).
The final size of an epidemic (what fraction of susceptibles will be infected).
The endemic equilibrium fraction of susceptibles in a population (=1/ R0).
The critical vaccination threshold, which is equal to 1-(1/ R0), and determines the number of people that must be vaccinated to prevent the spread of a pathogen.
- Disability-adjusted life years (DALY)
The number of years of life lost due to premature mortality plus the years lost due to disability while infected. Used to quantify the burden of disease.
- Epidemic
An outbreak of an infectious disease, such that a greater number of individuals than normal has the disease. Epidemics have very high R0 (Recall R0>1 for a disease to spread) and are often associated with acute, highly transmissible pathogens that can be directly transmitted. Further, pathogens with lower infectious periods create more explosive epidemics.
To control epidemics, it is necessary to reduce R0. This can be done by:
Reducing transmissibility.
Decreasing the number of susceptibles (by vaccination, for example).
Decreasing the mean number of contacts or the transmissibility, such as by improving sanitation, or limiting the number of interactions sick people have with healthy people.
Reducing length of infectious period.
- Force of infection (FoI)
A measure of the degree to which an infected individual can spread infection; the per-capita rate at which susceptibles contract infection. Typically increases with transmissibility and prevalence of infection.
- Herd immunity
Vaccines protect individuals, but also provide indirect protection to anyone those vaccinated people may have infected. The portion of the population that needs to be immunized in order to achieve herd immunity is P > 1 – (1/ R0), where P = proportion vaccinated * vaccine efficacy.
- Incidence (of a pathogen)
The number of new cases or infections in a given time period.
- Immune
Unable to become infected/infectious
- Prevalence (of a pathogen)
The proportion of a population that is infectious at any given time.
- Transmissibility (\(\beta\))
Also known as the effective contact rate, is the product of the contact rate and the probability of transmission per contact.
- Virulence
The capacity of a pathogen to produce disease. It is proportional to parasitemia, or the number of circulating copies of the pathogen in the host. The higher the virulence (given contact between S and I individuals), the more likely transmission is to occur. However, higher virulence means contact may be less likely as infected hosts show more symptoms of the disease. There is a trade-off that occurs between high transmissibility and disease-induced mortality.
How to use the software¶
This section contains detailed procedural information about how to use Epidemiological MODeling software (EMOD). For example, how to download input data files, how to set up groups in a population, how to create a configuration file and campaign file, how to run simulations both locally and on a remote HPC cluster, and more.
The architecture diagram below shows, at a high level, how the system functions.
High-level EMOD system architecture¶
For more information about how each component of the system fits together, see Introduction to the software. That section provides a conceptual overview of EMOD and describes each required or optional component for running a simulation.
Use input data files¶
The input data files contain the relatively fixed information about the population within each geographic node. For example, the number of individuals, geography, climate, demographics, and migration data. This topic describes how to download and use the input data files. These are in contrast to the demographic, geography, and migration parameters in the configuration file that control simulation-wide qualities, such as enabling air migration across all nodes in the simulation.
Except for the demographics file, you will generally use input data files without modifying them in any way. Only the demographics file is required, though migration files may be required for multi-node simulations. See Input data files for an overview of each of the different input files, including which are required for different simulations. See Input data file structure for reference information about the structure of each of these files.
Download input files¶
The EMOD-InputData repository uses large file storage (LFS) to manage the binaries and large JavaScript Object Notation (JSON) files. A standard Git clone of the repository will only retrieve the metadata for these files managed with LFS. To retrieve the actual data, follow the steps below.
Install the Git LFS plugin, if it is not already installed.
For Windows users, download the plugin from https://git-lfs.github.com.
For CentOS on Azure users, the plugin is included with the PrepareLinuxEnvironment.sh script.
Using a Git client or Command Prompt window, clone the input data repository to retrieve the metadata:
git clone https://github.com/InstituteforDiseaseModeling/EMOD-InputData.git
Navigate to the directory where you downloaded the metadata for the input data files.
Cache the actual data on your local machine:
git lfs fetch
Replace the metadata in the files with the actual contents:
git lfs checkout
Specify input files in the configuration file¶
Follow the steps below to specify which input files to use in a simulation. Only the demographics file is required, though additional files are generally needed for a realistic simulation.
Place all input files for a simulation in the same directory. You will specify this directory when you run a simulation. See Run simulations for more information.
In your configuration file, specify the path to each of these files, relative to the directory above, in the appropriate parameter. Generally, these parameters are appended with “_Filename” or “_Filenames”.
For example, the example below shows the relevant portion of a configuration file. See :doc :parameter-configuration for a complete list of the parameters.
{
"parameters": {
"Air_Temperature_Filename": "Namawala_single_node_air_temperature_daily.bin",
"Air_Temperature_Offset": 0,
"Air_Temperature_Variance": 2,
"Base_Rainfall": 100,
"Campaign_Filename": "campaign.json",
"Climate_Model": "CLIMATE_BY_DATA",
"Climate_Update_Resolution": "CLIMATE_UPDATE_DAY",
"Config_Name": "VectorAndMalaria_5_Namawala_Vector_ITNs",
"Demographics_Filenames": [
"Namawala_single_node_demographics.json"
],
"Geography": "Namawala",
"Land_Temperature_Filename": "Namawala_single_node_land_temperature_daily.bin",
"Land_Temperature_Offset": 0,
"Land_Temperature_Variance": 2,
"Load_Balance_Filename": "",
"Rainfall_Filename": "Namawala_single_node_rainfall_daily.bin",
"Rainfall_In_mm_To_Fill_Swamp": 1000.0,
"Rainfall_Scale_Factor": 1,
"Relative_Humidity_Filename": "Namawala_single_node_relative_humidity_daily.bin",
"Relative_Humidity_Scale_Factor": 1,
"Relative_Humidity_Variance": 0.05
}
}
Modify demographics files¶
The demographics files provided by IDM generally contain information about prevalence, immunity, risk, population size, and more for a geographic region. However, you will almost certainly want to modify the file to provide more detail or to set up groups within a population to more accurately model heterogeneous populations in terms of transmission, group transitions, or targeted interventions.
The demographics file is the only required input data file, with one exception. You have the option to run a simulation without a demographics file if you set Enable_Demographics_Builtin to 1 in the configuration file. However, this option is primarily used for software testing. It will not provide meaningful simulation data as it does not represent the population of a real geographic location.
Use demographics overlay files¶
You can use multiple demographic files when setting up a simulation. The “base layer” file contains default parameter settings and one or more overlay files contains additional parameters or different parameter values that override the values in the default file. This topic describes how to set up the base layer and overlay files.
Demographic overlay files allow you to do the following:
Separate different sets of parameters and values into individual overlays (for example, to separate those that are useful for specific diseases into different overlay files)
Add new parameters for a simulation into an overlay for easier prototyping
Override certain parameters of interest in an overlay
Override certain parameters for a particular sub-region
Simulating subsets of a larger region for which input data files have been constructed
Select the demographics file to use as the base layer file. All nodes to be included in the simulation must be listed in this file.
In the metadata, make note of the IdReference value.
You may change this value if you desire, but all input files for a simulation must have the same IdReference value. For more information about this parameter and the structure of demographics files in general, see Demographics file structure and parameters.
Create one or more overlay files. Keep the following things in mind:
In the metadata, the value for IdReference must match the value in the base layer file and all other input data files.
Any nodes listed in an overlay but not in the base layer will not be simulated.
If the demographics files include any JSON array elements, the entire array is overridden. You cannot add or remove individual elements in an array using an overlay file.
Overriding a parameter value on a node will not affect the other parameter values applied to that node.
Values set in the Defaults section of an overlay will be applied to all nodes listed in that file, not all nodes in the entire simulation. Therefore, an overlay file that includes a Defaults section but no Nodes section will not have any effect.
Place all demographics files in the directory where the other input data files are stored.
In the configuration file, set Demographics_Filenames to an array that contains a comma-delimited list of demographics files, listing the base layer file first.
An example base layer demographics file and an overlay file is below. You can see that the overlay adds the TransmissionMatrix for Heterogeneous Intra-Node Transmission (HINT) to only three of the five nodes (which correspond to Washington state counties).
{
"Metadata": {
"Author": "ewenger",
"NodeCount": 5,
"Tool": "table_to_demographics.py",
"IdReference": "SampleContent",
"DateCreated": "2013-08-01 15:37:16.853000"
},
"Defaults": {
"NodeAttributes": {
"BirthRate_DESCRIPTION": "Replacement of stable age distribution: Birth_Rate_Dependence=DEMOGRAPHIC_DEP_RATE (i.e. 14-45 year-old PossibleMothers)",
"BirthRate": 0.00017675,
"Airport": 0,
"Region": 1,
"Altitude": 0,
"Seaport": 0
},
"IndividualAttributes": {
"AgeDistribution_DESCRIPTION": "Box between age 0 and 60 years: Age_Initialization_Distribution_Type=DISTRIBUTION_SIMPLE",
"AgeDistributionFlag": 1,
"AgeDistribution1": 0,
"AgeDistribution2": 21900,
"PrevalenceDistribution_DESCRIPTION": "No initial infections",
"PrevalenceDistributionFlag": 0,
"PrevalenceDistribution1": 0,
"PrevalenceDistribution2": 0,
"RiskDistributionFlag": 0,
"RiskDistribution1": 1,
"RiskDistribution2": 0,
"ImmunityDistributionFlag": 0,
"ImmunityDistribution1": 1,
"ImmunityDistribution2": 0,
"MigrationHeterogeneityDistributionFlag": 0,
"MigrationHeterogeneityDistribution1": 1,
"MigrationHeterogeneityDistribution2": 0,
"MortalityDistribution_DESCRIPTION": "WA state (1999-2010). Source: wonder.cdc.gov",
"MortalityDistribution": {
"NumDistributionAxes": 2,
"AxisNames": [ "gender", "age" ],
"AxisUnits": [ "male=0,female=1", "years" ],
"AxisScaleFactors": [ 1, 365 ],
"NumPopulationGroups": [ 2, 15 ],
"PopulationGroups": [
[ 0, 1 ],
[ 0, 1, 2.5, 7.5, 12.5, 17.5, 22.5, 30, 40, 50, 60, 70, 80, 90, 120 ]
],
"ResultUnits": "annual deaths per 1000 individuals",
"ResultScaleFactor": 0.00000273972602739726027397260273973,
"ResultValues": [
[ 4.8, 0.2, 0.1, 0.2, 0.5, 1.1, 1.1, 1.7, 4.1, 9.2, 19.8, 53.7, 154.2, 1000, 1000 ],
[ 4.2, 0.2, 0.2, 0.2, 0.2, 0.4, 0.5, 1.1, 2.6, 5.5, 14.3, 40.1, 129.3, 1000, 1000 ]
]
}
}
},
"Nodes": [
{
"County": "Adams",
"NodeAttributes": {
"Latitude": 47.1274,
"InitialPopulation": 19200,
"Longitude": -118.38
},
"NodeID": 1
},
{
"County": "Asotin",
"NodeAttributes": {
"Latitude": 46.3393,
"InitialPopulation": 21800,
"Longitude": -117.0482
},
"NodeID": 2
},
{
"County": "Benton",
"NodeAttributes": {
"Latitude": 46.2068,
"InitialPopulation": 183400,
"Longitude": -119.7689
},
"NodeID": 3
},
{
"County": "Chelan",
"NodeAttributes": {
"Latitude": 47.4235,
"InitialPopulation": 73600,
"Longitude": -120.3103
},
"NodeID": 4
},
{
"County": "Clallam",
"NodeAttributes": {
"Latitude": 48.1181,
"InitialPopulation": 72350,
"Longitude": -123.4307
},
"NodeID": 5
}
]
}
{
"Metadata": {
"Author": "cwiswell",
"NodeCount": 10,
"Tool": "table_to_demographics.py",
"IdReference": "SampleContent",
"DateCreated": "2013-08-01 15:37:16.853000"
},
"Defaults": {
"IndividualProperties": [
{
"Property": "Accessibility",
"Values": [ "VaccineTake", "VaccineRefuse"],
"Initial_Distribution": [ 0.85, 0.15],
"Transitions": [],
"TransmissionMatrix": {
"Route": "Contact",
"Matrix": [
[1.1, 0.3],
[0.3, 5.0]
]
}
},
{
"Property": "Age_Bin",
"Age_Bin_Edges_In_Years": [ 0, 5, 13, -1 ],
"Transitions": [],
"TransmissionMatrix": {
"Route": "Contact",
"Matrix": [
[1.4, 1.0, 1.0],
[1.0, 2.5, 0.7],
[1.0, 0.7, 1.0]
]
}
}
]
},
"Nodes": [
{
"NodeID": 1
},
{
"NodeID": 3
},
{
"NodeID": 5
}
]
}
Configure heterogeneous populations¶
Demographics files are used to add heterogeneity to a population. You can define the initial distribution to use for age, prevalence, risk and more. You can also define values for accessibility, age, geography, risk, and other properties and assign individuals to groups based on those property values. This topic describes how to configure the population distribution and define heterogeneous groups.
After you set up the groups, you may want to add more parameters to the demographics file to configure how individuals transition into and out of groups, how transmission occurs between different groups, or how to target interventions to specific groups. For more information about the parameters and structure of demographics files, see Demographics file structure and parameters.
For example, you might want to divide a population up into different groups based on age so you can target interventions to individuals in a particular age range. Another common use is to configure treatment coverage to be higher for individuals in areas that are easy to access and lower for individuals in areas that are difficult to access. For more information on targeting interventions to particular groups, see Target interventions to nodes or groups. For information on how tp configure disease transmission among groups created with any of the properties, see Configure heterogeneous disease transmission.
Nodes are subregions within the geographic area being modeled. Values in the Defaults section of the demographics file will be applied to all nodes, while values in the Nodes section will be applied only to the specified node. Node-level settings take precedence.
You can configure attribute distributions in the population using the IndividualAttributes parameter in the demographics file. The initial value for an individual is a randomly selected value from the distribution. For example, if you use a uniform distribution to initialize age, the initial ages of individuals in the simulation will be evenly distributed between some minimum and maximum value.
In the demographics file, add the IndividualAttributes parameter and assign it an empty JSON object. If you want the groups to apply to all nodes, add it in the Defaults section; if you want the groups to be applied to specific nodes, add it to the Nodes section.
Within this object, add the parameters for different attributes (age, prevalence, etc.) and assign values for available distributions (constant, Gaussian, etc.) See Demographics file structure and parameters for more information about the available parameters.
The example below shows how to set up the age distribution for all nodes in a simulation.
{
"Defaults": {
"IndividualAttributes": {
"AgeDistributionFlag": 3,
"AgeDistribution1": 0.8,
"AgeDistribution2": 0.1
}
}
}
Assigning individuals to different groups based on properties, such as accessibility or risk, uses the IndividualProperties parameter in the demographics file. See Demographics file structure and parameters for a list of supported properties. The values you assign to properties are use-defined and can be applied to individuals in all nodes or only in particular nodes in a simulation.
In the demographics file, add the IndividualProperties parameter and set it to an empty array. If you want the groups to apply to all nodes, add it in the Defaults section; if you want the groups to be applied to specific nodes, add it to the Nodes section.
In the array, add an empty JSON object. Within it, do the following:
Add the Property parameter and set it to one of the supported values.
Add the Values parameter and set it to an array of possible values that can be assigned to individuals. You can define any value here.
Add the Initial_Distribution parameter and set it to an array of numbers that add up to 1. This configures the initial distribution of individuals assigned to each of the groups.
To define how individuals transition into and a out of each group, add the Transitions parameter and set it to it an empty array. Within it, do the following:
Add an empty JSON object and set parameters that define the group that individuals transition from, the group they transition to, the event that triggers the transition, the probability of transition, and more. See doc:parameter-demographics for a list of supported Transitions parameters and values.
If you want to add another property and associated groups, add a new JSON object in the IndividualProperties array as above.
Note
Multiple properties must be defined in one file. They can be defined in either the base layer demographics file or an overlay file, but they cannot be split between the files. The maximum number of property types that can be added is two.
Creating groups based on age ranges works a little differently than creating groups based on other properties. Age_Bin is tied to the simulated age of an individual rather than being an independent property. Some of its characteristics, such as initial distribution and transitions, are dependent on information from the demographics file and EMOD that manages individual aging during the simulation. Because of this, the parameters and structures in IndividualProperties are slightly different.
In the demographics file, add the IndividualProperties parameter and set it to an empty array. If you want the groups to apply to all nodes, add it in the Defaults section; if you want the groups to be applied to specific nodes, add it to the Nodes section.
In the array, add an empty JSON object. Within it, do the following:
Add the Property parameter and set it to “Age_Bin”.
Add the Age_Bin_Edges_In_Years parameter and set it to an array that contains a comma- delimited list of integers in ascending order that define the boundaries used for each of the age bins, in years. The first number must always be 0 (zero) to indicate the age at birth and the last number must be -1 to indicate the maximum age in the simulation.
To define how individuals transition into and a out of each group, add the Transitions parameter and set it to it an empty array. Aging during the simulation will be handled by EMOD.
The example below shows how to set up several groups based on disease risk and physical place, and how to move individuals among these groups. It also defines three age bins: 0 to 5 years, older than 5 to 13, and older than 13 to the maximum age.
{
"Defaults": {
"IndividualProperties": [{
"Property": "Risk",
"Values": ["Low", "Medium", "High"],
"Initial_Distribution": [0.7, 0.2, 0.1],
"Transitions": [{
"From": "High",
"To": "Medium",
"Type": "At_Age",
"Coverage": 1,
"Probability_Per_Timestep": 0.3,
"Timestep_Restriction": 20,
"Age_In_Years": 5,
"Timesteps_Until_Reversion": 0
}, {
"From": "Medium",
"To": "Low",
"Type": "At_Age",
"Coverage": 1,
"Probability_Per_Timestep": 0.3,
"Timestep_Restriction": 20,
"Age_In_Years": 12,
"Timesteps_Until_Reversion": 0
}]
}, {
"Property": "Place",
"Values": ["Community", "School", "Work", "Vacation"],
"Initial_Distribution": [0.3, 0.2, 0.4, 0.1],
"Transitions": [{
"From": "School",
"To": "Vacation",
"Type": "At_Timestep",
"Coverage": 1,
"Timestep_Restriction": {
"Start": 20
},
"Age_In_Years_Restriction": {},
"Probability_Per_Timestep": 1,
"Timesteps_Until_Reversion": 20
}]
}, {
"Property": "Age_Bin",
"Age_Bin_Edges_In_Years": [0, 5, 13, -1],
"Transitions": []
}]
}
}
Configure heterogeneous disease transmission¶
Only generic simulations can use Heterogeneous Intra-Node Transmission (HINT) to manually configure heterogeneous disease transmission within each node. All other simulation types have preconfigured solutions for heterogeneous disease transmission based on the biological processes of the disease being modeled. Because HINT cannot be used with this simulation type, the parameter Enable_Heterogeneous_Intranode_Transmission in the configuration file must be set to 0 (zero).
This topic describes the mathematics governing the Heterogeneous Intra-Node Transmission (HINT) feature. However, only generic simulations can use HINT to manually configure heterogeneous disease transmission within each node. All other simulation types have preconfigured solutions for heterogeneous disease transmission based on the biological processes of the disease being modeled. See the generic disease documentation for more information about HINT.
Create a configuration file¶
You define the general configuration and processing of a simulation through a JSON-formatted configuration file, typically called config.json. Two forms of the simulation configuration file are used: a flattened version and a hierarchical version. This topic describes how to create a configuration file of other form. The EMOD executable (Eradication.exe) and Eradication binary requires a flattened version of the simulation configuration file. The hierarchical version allows you to organize parameters into logical groups, making them easier to manage. If you use hierarchical configuration files, you must flatten them prior to running a simulation.
The EMOD Regression directory contains many different subdirectories that contain configuration, campaign, and other associated files to run simulations that represent real-world scenarios. Within the each subdirectory, there is usually a hierarchical overlay file (param_overrides.json) and a flattened file (config.json), which has been created by combining param_overrides.json with one of the default files in Regression/defaults. The default files are also organized hierarchically. The naming of these files is an arbitrary convention used at IDM; you may name this files anything you choose. See Use configuration overlay files for more information about flattening hierarchical files.
For a complete list of configuration parameters that are available to use with this simulation type, see Configuration parameters. For more information about JSON, see EMOD parameter reference.
Flattened configuration file¶
A flattened configuration file is generally a single-depth JSON file with configuration parameters listed alphabetically. This is the configuration file format that Eradication.exe requires for running simulations.
Below is an example of a flattened configuration file:
{
"parameters": {
"Acquisition_Blocking_Immunity_Decay_Rate": 0.1,
"Acquisition_Blocking_Immunity_Duration_Before_Decay": 60,
"Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE",
"Animal_Reservoir_Type": "NO_ZOONOSIS",
"Base_Incubation_Period": 0,
"Base_Individual_Sample_Rate": 1,
"Base_Infectious_Period": 4,
"Base_Infectivity": 3.5,
"Base_Mortality": 0,
"Base_Population_Scale_Factor": 1,
"Birth_Rate_Dependence": "POPULATION_DEP_RATE",
"Birth_Rate_Time_Dependence": "NONE",
"Burnin_Cache_Mode": "none",
"Burnin_Cache_Period": 0,
"Burnin_Name": "",
"Campaign_Filename": "campaign.json",
"Climate_Model": "CLIMATE_OFF",
"Config_Name": "00_DEFAULT",
"Custom_Reports_Filename": "NoCustomReports",
"Death_Rate_Dependence": "NONDISEASE_MORTALITY_OFF",
"Default_Geography_Initial_Node_Population": 1000,
"Default_Geography_Torus_Size": 10,
"Demographics_Filenames": [
"../00_Default/demographics.json"
],
"Enable_Absolute_Time": "NO",
"Enable_Aging": 1,
"Enable_Birth": 1,
"Enable_Default_Reporting": 1,
"Enable_Default_Shedding_Function": 1,
"Enable_Demographics_Birth": 0,
"Enable_Demographics_Builtin": 0,
"Enable_Demographics_Gender": 1,
"Enable_Demographics_Other": 0,
"Enable_Demographics_Reporting": 1,
"Enable_Disease_Mortality": 0,
"Enable_Heterogeneous_Intranode_Transmission": 0,
"Enable_Immune_Decay": 0,
"Enable_Immunity": 1,
"Enable_Interventions": 1,
"Enable_Maternal_Transmission": 0,
"Enable_Property_Output": 0,
"Enable_Spatial_Output": 0,
"Enable_Superinfection": 0,
"Enable_Vital_Dynamics": 0,
"Geography": "",
"Immunity_Acquisition_Factor": 0,
"Immunity_Initialization_Distribution_Type": "DISTRIBUTION_OFF",
"Immunity_Mortality_Factor": 0,
"Immunity_Transmission_Factor": 0,
"Incubation_Period_Distribution": "FIXED_DURATION",
"Individual_Sampling_Type": "TRACK_ALL",
"Infection_Updates_Per_Timestep": 1,
"Infectious_Period_Distribution": "EXPONENTIAL_DURATION",
"Infectivity_Scale_Type": "CONSTANT_INFECTIVITY",
"Job_Node_Groups": "Chassis08",
"Job_Priority": "BELOWNORMAL",
"Listed_Events": [],
"Load_Balance_Filename": "",
"Local_Simulation": 0,
"Maternal_Transmission_Probability": 0,
"Max_Individual_Infections": 1,
"Max_Node_Population_Samples": 40,
"Migration_Model": "NO_MIGRATION",
"Minimum_Adult_Age_Years": 15,
"Mortality_Blocking_Immunity_Decay_Rate": 0.001,
"Mortality_Blocking_Immunity_Duration_Before_Decay": 60,
"Mortality_Time_Course": "DAILY_MORTALITY",
"Node_Grid_Size": 0.042,
"Num_Cores": 1,
"Number_Basestrains": 1,
"Number_Substrains": 1,
"PKPD_Model": "FIXED_DURATION_CONSTANT_EFFECT",
"Population_Density_C50": 30,
"Population_Density_Infectivity_Correction": "CONSTANT_INFECTIVITY",
"Population_Scale_Type": "USE_INPUT_FILE",
"Report_Event_Recorder": 0,
"Run_Number": 1,
"Sample_Rate_0_18mo": 1,
"Sample_Rate_10_14": 1,
"Sample_Rate_15_19": 1,
"Sample_Rate_18mo_4yr": 1,
"Sample_Rate_20_Plus": 1,
"Sample_Rate_5_9": 1,
"Sample_Rate_Birth": 1,
"Serialization_Test_Cycles": 0,
"Simulation_Duration": 90,
"Simulation_Timestep": 1,
"Simulation_Type": "GENERIC_SIM",
"Start_Time": 0,
"Susceptibility_Scale_Type": "CONSTANT_SUSCEPTIBILITY",
"Transmission_Blocking_Immunity_Decay_Rate": 0.1,
"Transmission_Blocking_Immunity_Duration_Before_Decay": 60,
"x_Air_Migration": 1,
"x_Birth": 1,
"x_Local_Migration": 1,
"x_Other_Mortality": 1,
"x_Population_Immunity": 1,
"x_Regional_Migration": 1,
"x_Sea_Migration": 1,
"x_Temporary_Larval_Habitat": 1
}
}
Hierarchical configuration file¶
The hierarchical version of a configuration file has a more complex structure. As a way of sorting parameters into logical groups, the parameters can be contained inside nested JSON objects. The names you use to create these logical categories are unimportant; the scripts used to flatten the files will search through the hierarchies and retain only the “leaf” values in the resulting flattened file. See Use configuration overlay files for more information on flattening files.
Below is an example of a hierarchical configuration file:
{
"parameters": {
"CAMPAIGNS": {
"Campaign_Filename": "campaign.json",
"Enable_Interventions": 1,
"Listed_Events": [],
"PKPD_Model": "FIXED_DURATION_CONSTANT_EFFECT"
},
"CLIMATE": {
"Climate_Model": "CLIMATE_OFF"
},
"DEMOGRAPHICS": {
"Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE",
"Base_Population_Scale_Factor": 1,
"Birth_Rate_Dependence": "DEMOGRAPHIC_DEP_RATE",
"Birth_Rate_Time_Dependence": "NONE",
"Demographics_Filenames": ["NO_DEFAULT_DEMOGRAPHICS"],
"Default_Geography_Initial_Node_Population": 1000,
"Default_Geography_Torus_Size": 10,
"Enable_Aging": 1,
"Enable_Birth": 1,
"Enable_Demographics_Birth": 0,
"Enable_Demographics_Gender": 1,
"Enable_Demographics_Builtin": 0,
"Enable_Demographics_Other": 0,
"Enable_Demographics_Reporting": 0,
"Enable_Vital_Dynamics": 1,
"Minimum_Adult_Age_Years": 15,
"IMMUNITY": {
"Acquisition_Blocking_Immunity_Decay_Rate": 0.1,
"Acquisition_Blocking_Immunity_Duration_Before_Decay": 60,
"Enable_Immune_Decay": 1,
"Enable_Immunity": 1,
"Immunity_Acquisition_Factor": 0,
"Immunity_Transmission_Factor": 0,
"Immunity_Initialization_Distribution_Type": "DISTRIBUTION_OFF",
"Susceptibility_Scale_Type": "CONSTANT_SUSCEPTIBILITY",
"Transmission_Blocking_Immunity_Decay_Rate": 0.1,
"Transmission_Blocking_Immunity_Duration_Before_Decay": 60
},
"MORTALITY": {
"Base_Mortality": 0,
"Enable_Disease_Mortality": 0,
"Death_Rate_Dependence": "NONDISEASE_MORTALITY_BY_AGE_AND_GENDER",
"Immunity_Mortality_Factor": 0,
"Mortality_Blocking_Immunity_Decay_Rate": 0.001,
"Mortality_Blocking_Immunity_Duration_Before_Decay": 60,
"Mortality_Time_Course": "DAILY_MORTALITY"
},
"Population_Density_C50": 30,
"Population_Scale_Type": "USE_INPUT_FILE",
"SAMPLING": {
"Base_Individual_Sample_Rate": 1,
"Individual_Sampling_Type": "TRACK_ALL",
"Max_Node_Population_Samples": 40,
"Sample_Rate_0_18mo": 1,
"Sample_Rate_10_14": 1,
"Sample_Rate_15_19": 1,
"Sample_Rate_18mo_4yr": 1,
"Sample_Rate_20_Plus": 1,
"Sample_Rate_5_9": 1,
"Sample_Rate_Birth": 2
}
},
"DISEASE": {
"Animal_Reservoir_Type": "NO_ZOONOSIS",
"Enable_Superinfection": 0,
"INCUBATION": {
"Base_Incubation_Period": 3,
"Incubation_Period_Distribution": "FIXED_DURATION"
},
"INFECTIOUSNESS": {
"Base_Infectious_Period": 7,
"Base_Infectivity": 0.3,
"Infectious_Period_Distribution": "EXPONENTIAL_DURATION",
"Infectivity_Scale_Type": "CONSTANT_INFECTIVITY",
"Population_Density_Infectivity_Correction": "CONSTANT_INFECTIVITY"
},
"Infection_Updates_Per_Timestep": 1,
"Max_Individual_Infections": 1,
"TRANSMISSION": {
"Enable_Maternal_Transmission": 0,
"Maternal_Transmission_Probability": 0
}
},
"FUDGE_FACTORS": {
"x_Air_Migration": 1,
"x_Birth": 1,
"x_Local_Migration": 1,
"x_Other_Mortality": 1,
"x_Population_Immunity": 1,
"x_Regional_Migration": 1,
"x_Sea_Migration": 1,
"x_Temporary_Larval_Habitat": 1
},
"HPC": {
"Job_Node_Groups": "Chassis08",
"Job_Priority": "BELOWNORMAL",
"Load_Balance_Filename": "",
"Local_Simulation": 0,
"Num_Cores": 1
},
"INTRANODE_TRANSMISSION": {
"Enable_Default_Shedding_Function": 1,
"Enable_Heterogeneous_Intranode_Transmission": 0
},
"MIGRATION": {
"Migration_Model": "NO_MIGRATION"
},
"OUTPUT": {
"Custom_Reports_Filename": "NoCustomReports",
"Report_Event_Recorder": 0,
"Enable_Default_Reporting": 1,
"Enable_Property_Output": 0,
"Enable_Spatial_Output": 0
},
"POLIO": {},
"PRIMARY": {
"Config_Name": "DEFAULT_CONFIG_NAME_SHOULD_BE_SET",
"ENUMS": {
"Simulation_Type": "GENERIC_SIM"
},
"Geography": "DEFAULT_GEOGRAPHY_SHOULD_BE_SET",
"Node_Grid_Size": 0.042,
"Run_Number": 0,
"Simulation_Duration": 365,
"Simulation_Timestep": 1,
"Start_Time": 0,
"Enable_Absolute_Time": "NO"
},
"SERIALIZATION": {
"Burnin_Cache_Mode": "none",
"Burnin_Cache_Period": 0,
"Burnin_Name": "",
"Serialization_Test_Cycles": 0
},
"STRAIN_TRACKING": {
"Number_Basestrains": 1,
"Number_Substrains": 1
}
}
}
Create or modify configuration files¶
Although you can create configuration files entirely from scratch, it is often easier to start from an existing configuration file and modify it to meet your needs. Any of the configuration files in the Regression directory may be used; in particular the Regression/defaults directory contains hierarchical configuration files with the common parameter settings used with different simulation types.
The simplest method is to use a text editor to directly edit the parameters or parameter values in the JSON file. However, while direct editing of files may be sufficient for small and infrequent changes, you will likely find that scripting tools are more powerful and reliable for both creating and modifying files.
The following example shows how to read a configuration file to a Python dictionary, modify a parameter, and write it back out to the file:
import json
# load the current config.json
config_file = open( "config.json" )
config_json = json.load( config_file )
config_file.close()
# modify one of the parameter values, e.g. "base_infectivity"
config_json["parameters"]["base_infectivity"] = 0.5
# write the modified config file
modified_file = open( "modified_config.json", "w" )
json.dump( config_json, modified_file, sort_keys=True, indent=4 )
modified_file.close()
The following example shows how to modify a configuration file in MATLAB:
addpath Matlab
addpath Matlab\test
% load the simulation configuration file into MATLAB structure
configjson = loadJson( "config.json" );
% modify one of the values
configjson.parameters.Base_Infectivity = 08.5;
% save the new configuration to file
saveJson( "modified_config.json", configjson );
Generate a list of all available parameters (a schema)¶
You can generate a schema from the EMOD executable (Eradication.exe) or Eradication binary that defines all configuration parameters and campaign parameters available in the version of EMOD that is installed, for all available simulation types. This includes parameter names, data types, defaults, ranges, and short descriptions.
Logging information is also produced as part of the schema. If you are using EMOD source and have added or modified configuration parameters or intervention code, this logging information can help you troubleshoot any errors that may occur.
Warning
If you modify the source code to add or remove configuration or campaign parameters, you may need to update the code used to produce the schema. You must also verify that your simulations are still scientifically valid.
The following command-line options are available for providing information about EMOD.
Long form |
Short form |
Description |
|---|---|---|
|
|
Shows help options for Eradication.exe. |
|
|
Shows the version information and supported simulation types. Note capitalization of short alternative. |
|
|
Outputs the configuration and campaign parameters. Unless |
|
|
When used with |
Open a Command Prompt window and navigate to the directory where Eradication.exe is installed.
To output the schema to the Command Prompt window, enter:
Eradication.exe --get-schema
To output the schema to a file, do one of the following (replacing <filename> with the desired filename):
To output a text file that includes logging information, enter:
Eradication.exe --get-schema > <filename>.txt
To display logging in the Command Prompt window and output a text file that does not include logging information, enter:
Eradication.exe --get-schema --schema-path <filename>.txt
To output the schema to a JSON file that includes logging information, enter:
Eradication.exe --get-schema > <filename>.json
To display logging in the Command Prompt window and output a JSON file that does not include logging information, enter:
Eradication.exe --get-schema --schema-path <filename>.json
Perform a parameter sweep¶
Parameter sweeps iteratively update the values of parameters to exhaustively search through the parameter space for a simulation. EMOD does not currently support automated parameter sweeps. However, you can write your own code, such as a Python or MATLAB script, that iterates through the values you want for a particular parameter. This topic describes how to perform a parameter sweep.
For example, you can run simulations using a Python script that uses the parameter values specified in a JSON parameter sweep file to iteratively update the configuration or campaign parameter values. The IDM test team performs parameter sweeps as part of regression testing. See the following examples to see how this is implemented.
The following JSON example illustrates sweeping through configuration parameter values.
{
"sweep" :
{
"path": "43_Vector_Garki_MultiCore_VectorMigration",
"param_name" : "Run_Number",
"param_values" : [ 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144 ]
}
}
The following Python example illustrates how to update the configuration file with the above values. This is excerpted from the regression_test.py script in the Regression directory.
elif "sweep" in reglistjson:
print( "Running sweep...\n" )
param_name = reglistjson["sweep"]["param_name"]
for param_value in reglistjson["sweep"]["param_values"]:
os.chdir(ru.cache_cwd)
sim_timestamp = str(datetime.datetime.now()).replace('-', '_' ).replace( ' ', '_' ).replace( ':', '_' ).replace( '.', '_' )
if regression_id == None:
regression_id = sim_timestamp
configjson = ru.flattenConfig( os.path.join( reglistjson["sweep"]["path"], "param_overrides.json" ) )
if configjson is None:
print("Error flattening config. Skipping " + simcfg["path"])
ru.final_warnings += "Error flattening config. Skipped " + simcfg["path"] + "\n"
continue
# override sweep parameter
configjson["parameters"][param_name] = param_value
campjson_file = open( os.path.join( reglistjson["sweep"]["path"],"campaign.json" ) )
campjson = json.loads( campjson_file.read().replace( "u'", "'" ).replace( "'", '"' ).strip( '"' ) )
campjson_file.close()
configjson["campaign_json"] = str(campjson)
report_fn = os.path.join( reglistjson["sweep"]["path"],"custom_reports.json" )
if os.path.exists( report_fn ) == True:
reportjson_file = open( report_fn )
reportjson = json.loads( reportjson_file.read().replace( "u'", "'" ).replace( "'", '"' ).strip( '"' ) )
reportjson_file.close()
configjson["custom_reports_json"] = str(reportjson)
else:
configjson["custom_reports_json"] = None
thread = runner.commissionFromConfigJson( sim_timestamp, configjson, reglistjson["sweep"]["path"], None, 'sweep' )
ru.reg_threads.append( thread )
else:
print "Unknown state"
sys.exit(0)
Use configuration overlay files¶
You can use two configuration files when setting up a simulation. One file contains default parameter settings and an overlay file contains additional parameters or different parameter values that override the values in the default file. This topic describes how to set up the default and overlay file and flatten them into a single file before running a simulation.
Overlay files allow you to easily separate a subset of parameters that are of particular interest from the rest of the parameters needed to run a simulation. You can easily modify the parameters in the overlay file without needing to maintain a complete configuration or campaign file. This can be especially helpful when you want to experiment with the values set in certain parameters of interest without modifying the rest of the settings. You can have one default file and many different overlay files for different configurations. It also allows you to easily update the default values across multiple simulations.
In addition to being used for model experimentation, overlay files are used when testing the software functionality after making source code changes. If you run the EMOD regression tests using regression_test.py, configuration files will be flattened as part of those tests. However, this may take several hours if run locally. More guidance on modifying the EMOD source code is in the “Advance the model” section.
Follow the steps below to quickly flatten configuration files.
Create the default configuration file in JSON. You may, though it is not required, organize the parameters into logical categories of nested JSON objects to make managing the parameters easier. See Configuration parameters for a complete list of all parameters that are available. See the example default configuration file below.
{ "parameters": { "CAMPAIGNS": { "Campaign_Filename": "campaign.json", "Enable_Interventions": 1, "Listed_Events": [], "PKPD_Model": "FIXED_DURATION_CONSTANT_EFFECT" }, "CLIMATE": { "Climate_Model": "CLIMATE_OFF" }, "DEMOGRAPHICS": { "Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE", "Base_Population_Scale_Factor": 1, "Birth_Rate_Dependence": "DEMOGRAPHIC_DEP_RATE", "Birth_Rate_Time_Dependence": "NONE", "Demographics_Filenames": ["NO_DEFAULT_DEMOGRAPHICS"], "Default_Geography_Initial_Node_Population": 1000, "Default_Geography_Torus_Size": 10, "Enable_Aging": 1, "Enable_Birth": 1, "Enable_Demographics_Birth": 0, "Enable_Demographics_Gender": 1, "Enable_Demographics_Builtin": 0, "Enable_Demographics_Other": 0, "Enable_Demographics_Reporting": 0, "Enable_Vital_Dynamics": 1, "Minimum_Adult_Age_Years": 15, "IMMUNITY": { "Acquisition_Blocking_Immunity_Decay_Rate": 0.1, "Acquisition_Blocking_Immunity_Duration_Before_Decay": 60, "Enable_Immune_Decay": 1, "Enable_Immunity": 1, "Immunity_Acquisition_Factor": 0, "Immunity_Transmission_Factor": 0, "Immunity_Initialization_Distribution_Type": "DISTRIBUTION_OFF", "Susceptibility_Scale_Type": "CONSTANT_SUSCEPTIBILITY", "Transmission_Blocking_Immunity_Decay_Rate": 0.1, "Transmission_Blocking_Immunity_Duration_Before_Decay": 60 }, "MORTALITY": { "Base_Mortality": 0, "Enable_Disease_Mortality": 0, "Death_Rate_Dependence": "NONDISEASE_MORTALITY_BY_AGE_AND_GENDER", "Immunity_Mortality_Factor": 0, "Mortality_Blocking_Immunity_Decay_Rate": 0.001, "Mortality_Blocking_Immunity_Duration_Before_Decay": 60, "Mortality_Time_Course": "DAILY_MORTALITY" }, "Population_Density_C50": 30, "Population_Scale_Type": "USE_INPUT_FILE", "SAMPLING": { "Base_Individual_Sample_Rate": 1, "Individual_Sampling_Type": "TRACK_ALL", "Max_Node_Population_Samples": 40, "Sample_Rate_0_18mo": 1, "Sample_Rate_10_14": 1, "Sample_Rate_15_19": 1, "Sample_Rate_18mo_4yr": 1, "Sample_Rate_20_Plus": 1, "Sample_Rate_5_9": 1, "Sample_Rate_Birth": 2 } }, "DISEASE": { "Animal_Reservoir_Type": "NO_ZOONOSIS", "Enable_Superinfection": 0, "INCUBATION": { "Base_Incubation_Period": 3, "Incubation_Period_Distribution": "FIXED_DURATION" }, "INFECTIOUSNESS": { "Base_Infectious_Period": 7, "Base_Infectivity": 0.3, "Infectious_Period_Distribution": "EXPONENTIAL_DURATION", "Infectivity_Scale_Type": "CONSTANT_INFECTIVITY", "Population_Density_Infectivity_Correction": "CONSTANT_INFECTIVITY" }, "Infection_Updates_Per_Timestep": 1, "Max_Individual_Infections": 1, "TRANSMISSION": { "Enable_Maternal_Transmission": 0, "Maternal_Transmission_Probability": 0 } }, "FUDGE_FACTORS": { "x_Air_Migration": 1, "x_Birth": 1, "x_Local_Migration": 1, "x_Other_Mortality": 1, "x_Population_Immunity": 1, "x_Regional_Migration": 1, "x_Sea_Migration": 1, "x_Temporary_Larval_Habitat": 1 }, "HPC": { "Job_Node_Groups": "Chassis08", "Job_Priority": "BELOWNORMAL", "Load_Balance_Filename": "", "Local_Simulation": 0, "Num_Cores": 1 }, "INTRANODE_TRANSMISSION": { "Enable_Default_Shedding_Function": 1, "Enable_Heterogeneous_Intranode_Transmission": 0 }, "MIGRATION": { "Migration_Model": "NO_MIGRATION" }, "OUTPUT": { "Custom_Reports_Filename": "NoCustomReports", "Report_Event_Recorder": 0, "Enable_Default_Reporting": 1, "Enable_Property_Output": 0, "Enable_Spatial_Output": 0 }, "POLIO": {}, "PRIMARY": { "Config_Name": "DEFAULT_CONFIG_NAME_SHOULD_BE_SET", "ENUMS": { "Simulation_Type": "GENERIC_SIM" }, "Geography": "DEFAULT_GEOGRAPHY_SHOULD_BE_SET", "Node_Grid_Size": 0.042, "Run_Number": 0, "Simulation_Duration": 365, "Simulation_Timestep": 1, "Start_Time": 0, "Enable_Absolute_Time": "NO" }, "SERIALIZATION": { "Burnin_Cache_Mode": "none", "Burnin_Cache_Period": 0, "Burnin_Name": "", "Serialization_Test_Cycles": 0 }, "STRAIN_TRACKING": { "Number_Basestrains": 1, "Number_Substrains": 1 } } }
Create the overlay configuration file in JSON. This file must include the parameter Default_Config_Path, set to the path to the default configuration file, relative to the location of the flatten_config.py script in the EMOD Regression folder. Again, you may organize the parameters into logical categories if you desire. See the example overlay configuration file below.
{ "Default_Config_Path": "defaults/generic-default-config.json", "parameters": { "DEMOGRAPHICS": { "Enable_Demographics_Builtin": 0, "Birth_Rate_Dependence": "POPULATION_DEP_RATE", "Death_Rate_Dependence" : "NONDISEASE_MORTALITY_OFF", "Enable_Vital_Dynamics": 0, "Sample_Rate_Birth": 1, "Enable_Demographics_Reporting": 1 }, "DISEASE": { "Base_Incubation_Period": 0, "Base_Infectious_Period": 4, "Base_Infectivity": 3.5, "Enable_Immune_Decay": 0 }, "PRIMARY": { "Config_Name": "00_Generic_DEFAULT", "Demographics_Filenames": ["demographics.json"], "Geography": "", "Run_Number": 1, "Simulation_Duration": 90 } } }
In a Command Prompt window, navigate to the Regression folder.
Run the flatten_config.py script, providing the relative path to the overlay file:
python flatten_config.py experiment/param_overlay.json
Open the resulting config.json file in the same folder as param_overlay.json and see that it has been flattened into a single layer with all parameters listed alphabetically and any logical categories removed. Eradication.exe will not accept a configuration file with nested JSON objects.
{ "parameters": { "Acquisition_Blocking_Immunity_Decay_Rate": 0.1, "Acquisition_Blocking_Immunity_Duration_Before_Decay": 60, "Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE", "Animal_Reservoir_Type": "NO_ZOONOSIS", "Base_Incubation_Period": 0, "Base_Individual_Sample_Rate": 1, "Base_Infectious_Period": 4, "Base_Infectivity": 3.5, "Base_Mortality": 0, "Base_Population_Scale_Factor": 1, "Birth_Rate_Dependence": "POPULATION_DEP_RATE", "Birth_Rate_Time_Dependence": "NONE", "Burnin_Cache_Mode": "none", "Burnin_Cache_Period": 0, "Burnin_Name": "", "Campaign_Filename": "campaign.json", "Climate_Model": "CLIMATE_OFF", "Config_Name": "00_DEFAULT", "Custom_Reports_Filename": "NoCustomReports", "Death_Rate_Dependence": "NONDISEASE_MORTALITY_OFF", "Default_Geography_Initial_Node_Population": 1000, "Default_Geography_Torus_Size": 10, "Demographics_Filenames": [ "../00_Default/demographics.json" ], "Enable_Absolute_Time": "NO", "Enable_Aging": 1, "Enable_Birth": 1, "Enable_Default_Reporting": 1, "Enable_Default_Shedding_Function": 1, "Enable_Demographics_Birth": 0, "Enable_Demographics_Builtin": 0, "Enable_Demographics_Gender": 1, "Enable_Demographics_Other": 0, "Enable_Demographics_Reporting": 1, "Enable_Disease_Mortality": 0, "Enable_Heterogeneous_Intranode_Transmission": 0, "Enable_Immune_Decay": 0, "Enable_Immunity": 1, "Enable_Interventions": 1, "Enable_Maternal_Transmission": 0, "Enable_Property_Output": 0, "Enable_Spatial_Output": 0, "Enable_Superinfection": 0, "Enable_Vital_Dynamics": 0, "Geography": "", "Immunity_Acquisition_Factor": 0, "Immunity_Initialization_Distribution_Type": "DISTRIBUTION_OFF", "Immunity_Mortality_Factor": 0, "Immunity_Transmission_Factor": 0, "Incubation_Period_Distribution": "FIXED_DURATION", "Individual_Sampling_Type": "TRACK_ALL", "Infection_Updates_Per_Timestep": 1, "Infectious_Period_Distribution": "EXPONENTIAL_DURATION", "Infectivity_Scale_Type": "CONSTANT_INFECTIVITY", "Job_Node_Groups": "Chassis08", "Job_Priority": "BELOWNORMAL", "Listed_Events": [], "Load_Balance_Filename": "", "Local_Simulation": 0, "Maternal_Transmission_Probability": 0, "Max_Individual_Infections": 1, "Max_Node_Population_Samples": 40, "Migration_Model": "NO_MIGRATION", "Minimum_Adult_Age_Years": 15, "Mortality_Blocking_Immunity_Decay_Rate": 0.001, "Mortality_Blocking_Immunity_Duration_Before_Decay": 60, "Mortality_Time_Course": "DAILY_MORTALITY", "Node_Grid_Size": 0.042, "Num_Cores": 1, "Number_Basestrains": 1, "Number_Substrains": 1, "PKPD_Model": "FIXED_DURATION_CONSTANT_EFFECT", "Population_Density_C50": 30, "Population_Density_Infectivity_Correction": "CONSTANT_INFECTIVITY", "Population_Scale_Type": "USE_INPUT_FILE", "Report_Event_Recorder": 0, "Run_Number": 1, "Sample_Rate_0_18mo": 1, "Sample_Rate_10_14": 1, "Sample_Rate_15_19": 1, "Sample_Rate_18mo_4yr": 1, "Sample_Rate_20_Plus": 1, "Sample_Rate_5_9": 1, "Sample_Rate_Birth": 1, "Serialization_Test_Cycles": 0, "Simulation_Duration": 90, "Simulation_Timestep": 1, "Simulation_Type": "GENERIC_SIM", "Start_Time": 0, "Susceptibility_Scale_Type": "CONSTANT_SUSCEPTIBILITY", "Transmission_Blocking_Immunity_Decay_Rate": 0.1, "Transmission_Blocking_Immunity_Duration_Before_Decay": 60, "x_Air_Migration": 1, "x_Birth": 1, "x_Local_Migration": 1, "x_Other_Mortality": 1, "x_Population_Immunity": 1, "x_Regional_Migration": 1, "x_Sea_Migration": 1, "x_Temporary_Larval_Habitat": 1 } }
Note
These same steps can also be used to flatted a single configuration file that has been hierarchically organized into logical categories.
Create a campaign file¶
You define the initial disease outbreak and interventions used a campaign for a simulation through a JSON-formatted campaign file, typically called campaign.json. It is hierarchically organized into logical groups of parameters that can have arbitrary levels of nesting. For some interventions, there can be a very complex hierarchical structure, including recursion. The campaign file must be in the same directory as the configuration file and the name must be specified by the configuration parameter Campaign_Filename. This topic describes how to create the campaign file.
The EMOD Regression directory contains many different subdirectories that contain configuration, campaign, and other associated files to run simulations that represent real-world scenarios. Within the each subdirectory, there is usually a single campaign file (campaign.json), though some directories also include a campaign overlay file (campaign_overrides.json), which has been created by combining campaign_overrides.json with one of the default files in Regression/defaults. The naming of these files is an arbitrary convention used at IDM; you may name this files anything you choose. See Use campaign overlay files for more information flattening two campaign files.
For a complete list of campaign parameters that are available to use with this simulation type, see Campaign parameters. For more information about JSON, see EMOD parameter reference.
To distribute an intervention, you must configure the following:
- Campaign event
A JSON object that determines when and where an intervention is distributed during a campaign.
- Event coordinator
A JSON object that determines who will receive a particular intervention during a campaign.
- Intervention
A JSON object that determines what will be distributed to reduce the spread of a disease. An intervention can be distributed either to an individual (such as a vaccine, drug, or bednet) or to a node (such as a larvicide). Sometimes this can be an intermediate intervention that schedules another intervention.
The following is an example of campaign file that has two events (SimpleVaccine and Outbreak) that occur in all nodes at day 1 and day 30, respectively. Each event contains an event coordinator that describes who receives the intervention (everyone, with the vaccine repeated three times) and the configuration for the intervention itself.
Warning
The Outbreak must be the last event in the campaign file or none of the interventions will take place.
{
"Campaign_Name": "Vaccine",
"Use_Defaults": 1,
"Events":
[
{
"Event_Name": "SimpleVaccine",
"Event_Coordinator_Config": {
"Demographic_Coverage": 0.5,
"Intervention_Config": {
"Cost_To_Consumer": 10,
"Waning_Config": {
"class": "WaningEffectMapLinear",
"Initial_Effect" : 1.0,
"Expire_At_Durability_Map_End" : 0,
"Durability_Map" : {
"Times" : [ 0, 30, 60, 90, 120 ],
"Values" : [ 0.9, 0.3, 0.9, 0.6, 1.0 ]
}
},
"Vaccine_Take": 1,
"Vaccine_Type": "AcquisitionBlocking",
"class": "SimpleVaccine"
},
"Number_Repetitions": 3,
"Target_Demographic": "Everyone",
"Timesteps_Between_Repetitions": 7,
"class": "StandardInterventionDistributionEventCoordinator"
},
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Start_Day": 1,
"class": "CampaignEvent",
},
{
"Event_Name": "Outbreak",
"Event_Coordinator_Config": {
"Demographic_Coverage": 0.001,
"Intervention_Config": {
"Antigen": 0,
"Genome": 0,
"Outbreak_Source": "PrevalenceIncrease",
"class": "OutbreakIndividual"
},
"Target_Demographic": "Everyone",
"class": "StandardInterventionDistributionEventCoordinator"
},
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Start_Day": 30,
"class": "CampaignEvent"
}
]
}
Multiple interventions¶
When creating multiple interventions, either of the same type or different types, they will generally be distributed independently without regard to whether a person has already received another intervention. For example, say you create two SimpleBednet interventions and both interventions have Demographic_Coverage set to 0.5 (50% demographic coverage). This value is the probability that each individual in the target population will receive the intervention. It does not guarantee that the exact fraction of the target population set by Demographic_Coverage receives the intervention.
By default, each individual in the simulation will have a 50% chance of receiving a bednet in both of the distributions and the two distributions will be independent. Therefore, each individual has a 75% chance of receiving at least one bednet.
Create a new campaign event¶
Although you can create campaign files entirely from scratch, it is often easier to start from an existing campaign file and modify it to meet your needs. Any of the campaign files in the Regression directory may be used. The simplest method is to edit the parameters or parameter values in the JSON file in any text editor. You may also create or modify the files using a scripting language, as with configuration files. See Create a configuration file for examples.
In the Events array, create a new empty JSON object. This object will contain all parameters for the new campaign event.
In this object, add and set values for the Event_Name and class parameters.
Add the Nodeset_Config parameter to define in which geographic nodes this even will occur.
Add the Event_Coordinator_Config parameter and assign a JSON object that will contain multiple parameters that control who receives the intervention.
In this object, add the Intervention_Config parameter and assign a JSON object that will contain multiple parameters that control which intervention is distributed.
Use campaign overlay files¶
You can use two campaign files when setting up a simulation. One file contains default campaign settings and an overlay file contains additional parameters or different parameter values that override the values in the default file. This topic describes how to set up the default and overlay file and flatten them into a single file before running a simulation.
Overlay files allow you to easily separate a subset of parameters that are of particular interest from the rest of the parameters needed to run a simulation. You can easily modify the parameters in the overlay file without needing to maintain a complete campaign file. This can be especially helpful when you want to experiment with different interventions without modifying the rest of the settings. You can have one default file and many different overlay files for different intervention settings. It also allows you to easily update the default values across multiple simulations.
In addition to being used for model experimentation, overlay files are used when testing the software functionality after making source code changes. If you run the EMOD regression tests using regression_test.py, campaign files will be flattened as part of those tests. However, this may take several hours if run locally. More guidance on modifying the EMOD source code is in the “Advance the model” section.
Follow the steps below to quickly flatten campaign files.
Create the default campaign file in JSON. You may, though it is not required, organize the parameters into logical categories of nested JSON objects to make managing the parameters easier. See Campaign parameters for a complete list of all parameters that are available. See the example default campaign file below.
{ "Campaign_Name": "Initial Seeding", "Events": [ { "Event_Coordinator_Config": { "Demographic_Coverage": 0.001, "Intervention_Config": { "Antigen": 0, "Genome": 0, "Outbreak_Source": "PrevalenceIncrease", "class": "OutbreakIndividual" }, "Target_Demographic": "Everyone", "class": "StandardInterventionDistributionEventCoordinator" }, "Event_Name": "Outbreak", "Nodeset_Config": { "class": "NodeSetAll" }, "Start_Day": 30, "class": "CampaignEvent" } ], "Use_Defaults": 1 }
Create the overlay campaign file in JSON. This file must include the parameter Default_Campaign_Path, set to the path to the default campaign file, relative to the location of the flatten_campaign.py script in the EMOD Regression folder. Again, you may organize these into logical categories if you desire. See the example overlay campaign file below.
{ "Campaign_Name": "Vaccine", "Default_Campaign_Path": "defaults/generic-default-campaign.json", "Events": [ { "VACCINATION": "BEGIN", "Event_Name": "SimpleVaccine", "Event_Coordinator_Config": { "Demographic_Coverage": 0.5, "Intervention_Config": { "Cost_To_Consumer": 10, "Waning_Config": { "class": "WaningEffectMapLinear", "Initial_Effect" : 1.0, "Expire_At_Durability_Map_End" : 0, "Durability_Map" : { "Times" : [ 0, 30, 60, 90, 120 ], "Values" : [ 0.9, 0.3, 0.9, 0.6, 1.0 ] } }, "Vaccine_Take": 1, "Vaccine_Type": "AcquisitionBlocking", "class": "SimpleVaccine" }, "Number_Repetitions": 3, "Target_Demographic": "Everyone", "Timesteps_Between_Repetitions": 7, "class": "StandardInterventionDistributionEventCoordinator" }, "Nodeset_Config": { "class": "NodeSetAll" }, "Start_Day": 1, "class": "CampaignEvent", "VACCINATION": "END" } ] }
In a Command Prompt window, navigate to the Regression folder.
Run the flatten_campaign.py script, providing the relative path to the overlay file and the path to and name of the new flattened campaign file that will be saved, using the arguments as shown below:
python flatten_campaign.py --overlay experiment/campaign_overlay.json --saveto experiment/campaign.json
Open the resulting campaign.json file and see that it has been flattened into a single file with nested JSON objects and any logical categories retained.
{ "Campaign_Name": "Vaccine", "Default_Campaign_Path": "defaults/generic-default-campaign.json", "Use_Defaults": 1, "Events": [ { "VACCINATION": "BEGIN", "Event_Name": "SimpleVaccine", "Event_Coordinator_Config": { "Demographic_Coverage": 0.5, "Intervention_Config": { "Cost_To_Consumer": 10, "Waning_Config": { "class": "WaningEffectMapLinear", "Initial_Effect" : 1.0, "Expire_At_Durability_Map_End" : 0, "Durability_Map" : { "Times" : [ 0, 30, 60, 90, 120 ], "Values" : [ 0.9, 0.3, 0.9, 0.6, 1.0 ] } }, "Vaccine_Take": 1, "Vaccine_Type": "AcquisitionBlocking", "class": "SimpleVaccine" }, "Number_Repetitions": 3, "Target_Demographic": "Everyone", "Timesteps_Between_Repetitions": 7, "class": "StandardInterventionDistributionEventCoordinator" }, "Nodeset_Config": { "class": "NodeSetAll" }, "Start_Day": 1, "class": "CampaignEvent", "VACCINATION": "END" }, { "Event_Name": "Outbreak", "Event_Coordinator_Config": { "Demographic_Coverage": 0.001, "Intervention_Config": { "Antigen": 0, "Genome": 0, "Outbreak_Source": "PrevalenceIncrease", "class": "OutbreakIndividual" }, "Target_Demographic": "Everyone", "class": "StandardInterventionDistributionEventCoordinator" }, "Nodeset_Config": { "class": "NodeSetAll" }, "Start_Day": 30, "class": "CampaignEvent" } ] }
After the overlay files and default files are combined into a single campaign file, you can run a simulation using the EMOD executable (Eradication.exe).
Target interventions to nodes or groups¶
Generally, you want to target your outbreaks and campaign interventions to specific regions or individuals who meet certain criteria. For example, you may want to distribute bednets only to areas where a mosquito-borne disease is endemic or vaccinate only young children who are at highest risk. This topic describes how to distribute interventions to specific geographic nodes or groups of individuals.
Targeting geographic nodes with a particular intervention is controlled by the Nodeset_Config parameter in the campaign file. To distribute the intervention to all nodes, simply set it to “NodeSetAll”. To distribute to a subset of nodes, follow the steps below.
In the JSON object for the campaign event, set Nodeset_Config using one of the following two options:
Set it to an empty JSON object. Within that object, set the following:
Set class to “NodeSetNodeList”.
Set Node_List to an array that contains a comma-delimited list of nodes that set where the intervention will be distributed.
Set it to an empty JSON object. Within that object, set the following:
Set class to “NodeSetPolygon”.
Set Polygon_Format to “SHAPE”.
Set Vertices to a comma-delimited list of latitude and longitude pairs that define the outer boundary of the region you want to target. The intervention will be distributed to all nodes within the defined bounds.
See the example below.
{
"Use_Defaults": 1,
"Events": [{
"Event_Name": "Outbreak",
"Nodeset_Config": {
"class": "NodeSetNodeList",
"Node_List": [1, 3, 5]
},
"Start_Day": 10,
"class": "CampaignEvent"
}]
}
To target interventions to particular groups in a population, you must first create those groups in the demographics file using IndividualProperties. Then, in the campaign file, you can target an intervention or outbreak to a group of individuals based on the properties applied to them. See Configure heterogeneous populations for instructions on creating the groups.
Just as creating groups based on age works a little differently than groups based on other properties, targeting an intervention to a particular age range works a little differently than targeting an intervention to other properties.
To target interventions to properties other than age:
In the campaign file, in the event you want to target, set Target_Demographic to “Everyone”.
Add the Property_Restrictions parameter and set to an empty array.
In that array, add a list of JSON key-value pairs of the property type and value that specifies the groups to apply the intervention to. If the name of the element is not valid, EMOD will ignore the property restriction.
To target interventions to age ranges:
In the campaign file, in the event you want to target, set Target_Demographic to “ExplicitAgeRanges.”
Add the Target_Age_Min and set to the lower age bound.
Add the Target_Age_Max and set to the upper age bound.
Both of these values must match one the values listed in Age_Bin_Edges_In_Years in the demographics file. EMOD does not verify this range.
The following examples illustrate how to target interventions to different groups. This includes how to configure interventions when there are multiple relevant properties, such as targeting individuals who are both low-risk and in a suburban setting or individuals who are either low- risk or living in suburban settings.
The following examples show how to target interventions based on a single property value.
At day 0 of the simulation, an outbreak starts. Target_Demographic is set to “Everyone” but Property_Restrictions restricts the start of the outbreak to the “Urban” group.
{
"Events": [{
"Event_Coordinator_Config": {
"Number_Distributions": -1,
"Intervention_Config": {
"Antigen": 0,
"Genome": 0,
"Outbreak_Source": "PrevalenceIncrease",
"class": "OutbreakIndividual"
},
"Demographic_Coverage": 1,
"Target_Demographic": "Everyone",
"Property_Restrictions": [
"Place:Urban"
],
"class": "StandardInterventionDistributionEventCoordinator"
},
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Start_Day": 0,
"class": "CampaignEvent"
}]
}
Even if you have multiple properties defined in the demographics file, you can target interventions to a single property value in the same way. Individuals can have membership in any of the groups from the other property type.
In this example, groups are defined for both the “Risk” and “Place” property types. The outbreak only targets the “Suburban” group using the “Place” property type. Individuals can have membership in either of the “Risk” groups.
{
"Events": [{
"Event_Coordinator_Config": {
"Number_Distributions": -1,
"Intervention_Config": {
"Antigen": 0,
"Genome": 0,
"Outbreak_Source": "PrevalenceIncrease",
"class": "OutbreakIndividual"
},
"Demographic_Coverage": 1,
"Target_Demographic": "Everyone",
"Property_Restrictions": [
"Place:Urban"
],
"class": "StandardInterventionDistributionEventCoordinator"
},
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Start_Day": 0,
"class": "CampaignEvent"
}]
}
If you want to target multiple groups with the same property type, such as both “Urban” and “Rural” values with the “Place” property, you must use multiple interventions. You cannot have more than one group with the same property value in one intervention or outbreak.
In this example, an outbreak starts at day 0 in the both the “Rural” and “Urban” groups.
{
"Events": [{
"Event_Coordinator_Config": {
"Number_Distributions": -1,
"Intervention_Config": {
"Antigen": 0,
"Genome": 0,
"Outbreak_Source": "PrevalenceIncrease",
"class": "OutbreakIndividual"
},
"Demographic_Coverage": 1,
"Target_Demographic": "Everyone",
"Property_Restrictions": [
"Place:Rural"
],
"class": "StandardInterventionDistributionEventCoordinator"
},
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Start_Day": 0,
"class": "CampaignEvent"
}, {
"Event_Coordinator_Config": {
"Number_Distributions": -1,
"Intervention_Config": {
"Antigen": 0,
"Genome": 0,
"Outbreak_Source": "PrevalenceIncrease",
"class": "OutbreakIndividual"
},
"Demographic_Coverage": 1,
"Target_Demographic": "Everyone",
"Property_Restrictions": [
"Place:Urban"
],
"class": "StandardInterventionDistributionEventCoordinator"
},
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Start_Day": 0,
"class": "CampaignEvent"
}]
}
To target individuals who belong to multiple groups defined by different property types, such as people who are both urban and low risk, you can use a single intervention or outbreak. When two groups from multiple properties are targeted in one intervention or outbreak, the event is only applied to individuals that belong to both of the groups.
In this example, a vaccine intervention is targeted at the “Low” risk group and the “Suburban” place group. Individuals that are targeted to receive the vaccine must be in both the “Suburban” group and the “Low” risk group.
{
"Events": [{
"Event_Coordinator_Config": {
"Demographic_Coverage": 1.0,
"Intervention_Config": {
"Cost_To_Consumer": 10,
"Durability_Time_Profile": "BOXDECAYDURABILITY",
"Primary_Decay_Time_Constant": 3650,
"Reduced_Acquire": 1,
"Reduced_Transmit": 0,
"Secondary_Decay_Time_Constant": 3650,
"Vaccine_Take": 1,
"Vaccine_Type": "StrainSpecific",
"class": "SimpleImmunoglobulin"
},
"Target_Demographic": "Everyone",
"Property_Restrictions": [
"Risk:Low",
"Place:Suburban"
],
"class": "StandardInterventionDistributionEventCoordinator"
},
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Start_Day": 100,
"class": "CampaignEvent"
}]
}
However, if you want to target multiple groups, but individuals need to be a member of only one of the specified groups to qualify for the intervention, you must create an intervention for each of the targeted groups. The events are applied separately and are not restricted to individuals that belong to both of the groups. Instead, individuals can belong to either of the groups.
In this example, an outbreak is targeted at the “Low” risk group in the first intervention and is targeted at the “Suburban” group in the second intervention.
{
"Events": [{
"Event_Coordinator_Config": {
"Number_Distributions": -1,
"Intervention_Config": {
"Antigen": 0,
"Genome": 0,
"Outbreak_Source": "PrevalenceIncrease",
"class": "OutbreakIndividual"
},
"Demographic_Coverage": 1,
"Target_Demographic": "Everyone",
"Property_Restrictions": [
"Risk:Low"
],
"class": "StandardInterventionDistributionEventCoordinator"
},
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Start_Day": 0,
"class": "CampaignEvent"
}, {
"Event_Coordinator_Config": {
"Number_Distributions": -1,
"Intervention_Config": {
"Antigen": 0,
"Genome": 0,
"Outbreak_Source": "PrevalenceIncrease",
"class": "OutbreakIndividual"
},
"Demographic_Coverage": 1,
"Target_Demographic": "Everyone",
"Property_Restrictions": [
"Place:Suburban"
],
"class": "StandardInterventionDistributionEventCoordinator"
},
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Start_Day": 0,
"class": "CampaignEvent"
}]
}
Targeting an intervention to an age range is set up differently than targeting an intervention to other property types. However, you can combine both kinds of restrictions. In this example, a vaccine campaign is targeted at the “Urban” group for individuals who are age 0 to 5.
{
"Events": [{
"Event_Coordinator_Config": {
"Demographic_Coverage": 1.0,
"Intervention_Config": {
"Cost_To_Consumer": 10,
"Durability_Time_Profile": "BOXDECAYDURABILITY",
"Primary_Decay_Time_Constant": 3650,
"Reduced_Acquire": 1,
"Reduced_Transmit": 0,
"Secondary_Decay_Time_Constant": 3650,
"Vaccine_Take": 1,
"Vaccine_Type": "StrainSpecific",
"class": "SimpleImmunoglobulin"
},
"Target_Demographic": "ExplicitAgeRanges",
"Target_Age_Min": 0,
"Target_Age_Max": 5,
"Property_Restrictions": [
"Place:Urban"
],
"class": "StandardInterventionDistributionEventCoordinator"
},
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Start_Day": 30,
"class": "CampaignEvent"
}]
}
Run simulations¶
There are a number of ways to run an EMOD simulation, whether locally or on a remote HPC cluster. The simplest way is to run a simulation at the command line, however that limits you to running one local simulation at a time. Because the EMOD model is stochastic, you must run many simulations before you can interpret the outcome. You may want to use a scripting language like Python or MATLAB or an application like mpiexec to run multiple simulations at once.
In addition, if you are modifying the EMOD source code to add functionality to the model, you can run simulations in Visual Studio as part of debugging. This process is described in Run debug simulations in Visual Studio.
No matter how you choose to run simulations, you must have a built copy of the EMOD executable (Eradication.exe) or Eradication binary, either downloaded directly from GitHub or built from the EMOD source code. See EMOD installation. In addition, you must know the paths to the configuration file and input data files and where you want to store the output files. You will pass this information as arguments to Eradication.exe.
Directory structure¶
Although there are many ways you can structure the files needed to run a simulation, we recommend the following to keep your files organized and simplify the file paths set in the configuration file or passed as arguments to Eradication.exe.
Place the configuration and campaign files needed for a simulation in the same directory. This is also known as the working directory.
However, if you are using overlay files, you may want the default configuration or campaign file in a separate directory so they can be used with different overlay files for other simulations.
Place all input data files for a given region in the same directory.
Place output for a simulation in a subdirectory of the directory containing configuration and campaign files.
It is not important where you install Eradication.exe or the Eradication binary.
Run a simulation using the command line¶
Using command-line options is the simplest way to run an EMOD simulation. This topic describes the commands available for running simulations.
The EMOD executable (Eradication.exe) and Eradication binary also provide commands that provide information about the version of EMOD that is installed, such as available parameters and simulation types. For more information, see Generate a list of all available parameters (a schema). The examples below show the Windows Eradication.exe, but the options are the same for the Eradication binary on CentOS on Azure.
The following command-line options are available for running EMOD simulations. Paths can be absolute or relative to the directory you are in when running the commands, unless otherwise specified.
Long form |
Short form |
Description |
|---|---|---|
|
|
Path to the configuration file. If not specified, EMOD will look for a file named default-config.json in the current directory. |
|
|
Path to the directory containing input data files. If not specified, EMOD will look for files in the current directory. |
|
|
Path to the directory where output files will be written. If not specified, EMOD will create an “output” directory and overwrite any previous output in that directory. |
|
|
Path to the EMODule root directory. For more information, see Custom reporters. |
The following options are for monitoring the progress of simulations running on an high-performance computing (HPC) cluster. They are optional for any simulation, but they must be used together. To monitor progress, listen for User Datagram Protocol (UDP) messages on the specified host and port.
Long form |
Description |
|---|---|
|
The IP address of the commissioning/monitoring host. Set to “none” for no IP address. |
|
The port of the commissioning/monitoring host. Set to “0” for no port. |
|
The unique ID for this simulation. This ID is needed for self-identification to the UDP host. Set to “none” for no simulation ID. |
Open a Command Prompt window and navigate to the working directory, which contains the configuration and campaign files.
Enter a command like the one illustrated below, substituting the appropriate paths and file names for your simulation:
../Eradication.exe -C config.json -I C:\|EMOD_s|\InputFiles -O Sim1Output
If you do not specify anything when invoking Eradication.exe, it will not execute with all defaults, but will instead tell you how to invoke the
--helpcommand.EMOD will display logging information, including an errors that occur, while running the simulation. See Error and logging files for more information.
Run a simulation using mpiexec¶
The application mpiexec is used to run multi-node simulations in parallel. Eradication.exe is “single threaded”, so it uses only one core for processing. If you run a simulation with multiple geographic nodes using mpiexec instead of invoking Eradication.exe directly, multiple copies of Eradication.exe will be running, with one copy per core processing data for a single node at a time. Message Passing Interface (MPI) communicates between the cores when handling the migration of individuals from one node to another.
Although mpiexec can be used to run a simulation in parallel on your local computer, it is more often used to run complex simulations in parallel on an HPC cluster or several linked computers. Mpiexec is part of the Microsoft HPC Pack 2012 SDK (64-bit) installed as a prerequisite for building Eradication.exe from the EMOD source code. See EMOD source code installation for more information.
Note
If you get an error that the mpiexec command cannot be found, you must add the path to mpiexec to the PATH environment variable. For example, open Control Panel and add the path C:\Program Files\Microsoft HPC Pack 2012\Bin to PATH.
Take note of the number of cores on your computer or cluster.
If running locally, we recommend running mpiexec with one fewer cores than are available, so one core is reserved for the operating system. The simulation can be run on all available cores and will complete faster, but the desktop will not be responsive.
Open a Command Prompt window and navigate to the directory that contains the configuration and campaign files for the simulation.
Invoke Eradication.exe using mpiexec as follows, replacing the number of cores, paths, and command options as necessary for your environment. See Run a simulation using the command line for more information about the command options available for use with Eradication.exe.
mpiexec -n 3 ..\Eradication.exe --config config.json --input-path ..\InputDirectory\Garki --output-path OutputGarki
Mpiexec will start multiple copies of Eradication.exe as specified by -n. Those instances will
communicate with each other via MPI. If all cores are on a single computational node or host, they
will use internal networking to carry the MPI packets.
Note
The EMOD executable (Eradication.exe) does NOT use the configuration file parameter Num_Cores, which is used by the infrastructure that runs the simulation, such as an HPC cluster or regression script.
You can also link together several computers with MPI using the mpiexec -host option. For
example, if you were using six cores on two computers, you could run three copies of Eradication.exe
on the first computer, and three more could be run on the second computer. Again, this assumes that
each computer has at least three cores.
For more information about mpiexec, see MSDN.
Run a simulation using Python¶
If you used Python to create or modify JSON files as shown in Create a configuration file or Create a campaign file, it may be convenient to invoke Eradication.exe to run a simulation from a Python script. One way of doing this is shown below using the subprocess package.
import subprocess
# specify paths
binary_path = "binDirectory\Eradication.exe"
input_path = "inputDirectory\Namawala\
# commission job
subprocess.call( [binary_path, "-C", "config.json", "--input", input_path] )
See Run a simulation using the command line for more information about the command options available for use with Eradication.exe.
Run a simulation using MATLAB¶
If you used MATLAB to create or modify JSON files as shown in Create a configuration file or Create a campaign file, it may be convenient to invoke Eradication.exe to run a simulation from a MATLAB script. One way of doing this is shown below using the dos command.
exe_name = fullfile( binDirectory, 'Eradication.exe' );
exe_args = [ '-C config.json -I ', fullfile( inputDirectory, 'Namawala' ) ];
[status,result] = dos( ['cd ', WorkDirectory, ' && ', exe_name, ' ', exe_args ], '-echo' );
See Run a simulation using the command line for more information about the command options available for use with Eradication.exe.
Improve EMOD performance¶
While small simulations can be run quickly on a local computer, the time and memory needed to complete a simulation can grow significantly when simulations become larger and more complex. For example, a single geographical node simulation might use 3 GB with one core in order to run successfully in one minute or less, while another simulation job may require 32 GB in a dual-core system in order to complete in approximately the same amount of time.
As your simulations grow, you will likely want to run simulations on an HPC cluster or take other steps to improve performance and reduce processing time. This topic describes many of the steps you can take to speed up EMOD simulations.
The EMOD executable (Eradication.exe) is “single threaded”, meaning that for processing, it will use only one core. However, you can use the Message Passing Interface (MPI) to run multiple copies of Eradication.exe in parallel, either locally or on an HPC cluster. To run a simulation in parallel, you must invoke Eradication.exe with the mpiexec command. For more information, see Run a simulation using mpiexec.
You can also set various parameters in the configuration file that will improve performance by scaling down the amount of data used or optimizing data processing. See the parameters listed in the sections below for guidance on making performance adjustments. See Configuration parameters for more information about each of the parameters.
- Simulation_Duration
Obviously, simulating a shorter timespan will take less processing time. However, the processing time is often driven by the number of infections or immune updates, so running a simulation after all infections have cleared may not increase processing time much.
- Individual_Sampling_Type and Base_Individual_Sample_Rate
Instead of the default Individual_Sampling_Type setting of “TRACK_ALL”, you can speed up performance by using “FIXED_SAMPLING” with the Base_Individual_Sample_Rate set to less than one. For example, a simulation with a population of 1 million and sample rate of 0.1 would simulate 100,000 individuals, with each given a weight of 10. There are also sampling parameters that sample the population at different rates by age and by the population of the node.
However, you should be especially careful not to undersample simulations to the point where they are overly sensitive to rare stochastic events.
- Population_Scale_Type and Base_Population_Scale_Factor
Alternatively, you can simply reduce the total population of the simulation using Population_Scale_Type set to “FIXED_SCALING” and Base_Population_Scale_Factor set to less than one.
- Num_Cores
For large, spatially distributed simulations, running the intra-node dynamics (for example, infection and immune dynamics) in parallel on multiple cores may be very advantageous. Ideally, the timing would be reduced inversely to the number of cores. However, there are costs to serializing individuals for migration over MPI, as well as considerations for balancing the CPU load on each core. These issues may be mitigated using a load balancing input file that is suitable to the geography being simulated. See Load-balancing file structure for more information.
Use output files¶
At the end of the simulation, you will notice that a number of files have been written to the output directory. Some are logging or error output files, which you can read about more in Error and logging files. The rest are output reports that contain data from the simulation itself, usually in JSON or CSV format. This topic describes how to parse and use the output reports.
By default, the output report InsetChart.json is always produced, which contains per- timestep values accumulated over the simulation in a variety of reporting channels, for example, “New Infections”, “Adult Vectors”, and “Parasite Prevalence”. EMOD provides several other built-in reports that you can produce if you enable them in the configuration file. See Output report structure for additional information about the reports and how to enable them.
If none of the built-in output reports provide the data you need, you can use a custom reporter that plugs in to the Eradication.exe as a EMODule dynamic link library (DLL). For more information, see Custom reporters.
In order to interpret the output of EMOD simulations, you will find it useful to parse the output reports into an analyzable structure. For example, you can use a Python or MATLAB script to create graphs and charts for analysis.
Use Python to parse data¶
The example below uses the Python package JSON to parse the file and the Python package matplotlib.pyplot to plot the output. This is a very simple example and not likely the most robust or elegant. Be sure to set the actual path to your working directory.
import os
import json
import matplotlib.pyplot as plt
# open and parse InsetChart.json
ic_json = json.loads( open( os.path.join( WorkingDirectoryLocation, "output", "InsetChart.json" ) ).read() )
ic_json_allchannels = ic_json["Channels"]
ic_json_birthdata = ic_json["Channels"]["Births"]
# plot "Births" channel by time step
plt.plot( ic_json_birthdata[ "Data" ], 'b-' )
plt.title( "Births" )
plt.show()
Use MATLAB to parse data¶
The example below uses the MATLAB toolbox JSONlab to parse an InsetChart.json file and plot one channel. This script uses JSONLab to parse the file into a usable form in MATLAB. This is a very simple example and not likely the most robust or elegant. Be sure to set the actual paths to JSONlab and your working directory.
% this sample uses JSONLab toolbox
addpath('PATH TO/jsonlab');
% open and parse InsetChart.json
ic_json = loadjson( fullfile( 'WorkingDirectoryLocation', 'output', 'InsetChart.json' ));
ic_json_allchannels = ic_json.Channels;
ic_json_birthinfo = ic_json_allchannels.Births;
ic_json_birthdata = ic_json_birthinfo.Data;
M = num2cell(ic_json_birthdata);
% plot "Births" channel by time step
plot(cell2mat(M));
title( 'Births' );
Custom reporters¶
Reporters extract simulation data, aggregate it, and output it to a file known as an output report. You can process the report data using tools, such as Python or MATLAB, to create graphs and charts for analysis. EMOD provides built-in reporters that are part of the EMOD executable (Eradication.exe) and can be enabled or disabled by setting parameters in the configuration file. See Output report structure for a list of the reports that are available using built-in reporters.
In addition, you can use custom reporters that extract data from the simulation and aren’t part of the Eradication.exe. A custom reporter is an EMODule that you plug in to EMOD. Custom reporters are not supported for CentOS on Azure. There are several reporters in the GitHub reporters directory that you can use. You may also want to build your own custom reporter to create a new output report.
The Eradication.exe must load the reporter when running a simulation to use it. If it is loaded, the output report will be automatically generated at the end of the simulation. There are three ways to specify their location so Eradication.exe can load them. Eradication.exe attempts to load the file using the following methods, in the order listed:
Define the location of the dynamic link library (DLL) in a JSON-formatted file (emodules_map.json).
Point to the location using the
--dll-pathcommand-line option when invoking Eradication.exe.Place the DLL in the working directory.
First, Eradication.exe looks for an emodules_map.json file in the working directory. This map file lists specific reporter DLLs and their exact location. This is useful if you want to store all custom reporters in the same directory, but only want certain reporters to be used with each simulation.
The emodules_map.json file has three sections: diseases, interventions and reporters. Each section is a JSON array and contains the path to each EMODule in the array. Although reporter EMODules are the only type currently supported, empty disease and intervention sections must be included. You must use either a double backslash (\\) or a single forward slash (/) to represent a single backslash for the path. For example:
{
"disease_plugins": [
],
"interventions": [
],
"reporter_plugins": [
"C:\\src\\EMOD\\x64\\Release\\emodules\\reporter_plugins\\libreportpluginbasic.dll"
]
}
If a map file is not provided, you can include the --dll-path option when you invoke Eradication.exe. It
must point to a directory with a reporter_plugins subdirectory that contains the reporters. The name
of the directory does not matter, but the reporter must be in a subdirectory named reporter_plugins.
Note that this method will load all reporters in the root directory specified.
If you build custom reporters as described here, the DLLs will be saved to the following directories, depending on the build configuration:
<EMOD source directory path>x64Releasereporter_plugins
<EMOD source directory path>x64Debugreporter_plugins
Therefore, if you do not move your reports, you will set --dll-path to one of the following paths:
<EMOD source directory path>x64Release
<EMOD source directory path>x64Debug
For more information on EMOD command-line options, see Run a simulation using the command line.
Finally, if neither the the map file or the command-line option are provided, Eradication.exe looks for the reporter plug-in in the current working directory.
EMOD parameter reference¶
The configurable parameters described in this reference section determine the behavior of a particular simulation and interventions. The parameter descriptions are intended to guide you in correctly configuring simulations to match your disease scenario of interest.
This reference section contains only the parameters supported for use with the tuberculosis simulation type. To see the parameters for a different simulation type, see the corresponding documentation.
These parameters include three major groups: parameters for the demographics file, parameters for the configuration file, and parameters for the campaign file.
If you would rather use a text file for parameter reference than this web documentation, you can also generate a schema with the EMOD executable (Eradication.exe) that defines all configuration and campaign parameters that can be used in a simulation, including names, data types, defaults, ranges, and short descriptions. For instructions, see Generate a list of all available parameters (a schema).
JSON formatting overview¶
All of these parameters are contained in JavaScript Object Notation (JSON) formatted files. JSON is a data format that is human-readable and easy for software to read and generate. It can be created and edited using a simple text editor.
JSON has two basic structures: a collection of key-value pairs or an ordered list of values (an array). These structures are within a JSON object, which is enclosed in a set of braces. You will notice that each of these files begins with a left brace ({) and ends with a right brace (}).
A value can be a string, number, Boolean, array, or an object. The campaign and data input files often use nested objects and arrays. See www.json.org for more information on JSON.
A few important details to call out when creating JSON files:
Add a comma after every key-value pair or array except for the last key-value pair in an array or object.
The keys (parameters) are case-sensitive. For example, “NodeID” is not the same as “NodeId”.
Decimals require a 0 (zero) before the decimal point.
EMOD does not support Booleans (“True”, “False”). Instead, EMOD use the integer 1 for “True” and 0 for “False”.
Every opening brace or bracket ({ or [) requires a corresponding closing brace or bracket (} or ]).
The following is an example of a JSON formatted file.
{
"A_Complex_Key": {
"An_Array_with_a_Nested_Object_Value": [
{
"A_Simple_Key": "Value",
"A_Simple_Array": [ "Value1", "Value2" ],
"An_Array_with_Number_Values": [ 0.1, 0.2 ],
"A_Nested_Object": {
"Another_Simple_Key": "Value",
"Nested_Arrays": [
[ 10, 0.1 ],
[ 0.1, 1 ]
]
}
}
]
}
}
Demographics file structure and parameters¶
The parameters described in this reference section can be added to the JavaScript Object Notation (JSON) formatted demographics file to determine the demographics of the population within each geographic node in a simulation. For example, the number of individuals and the distribution for age, gender, immunity, risk, and mortality. This is in contrast to the configuration parameters related to demographics that are simulation-wide and generally control whether certain events, such as births or deaths, are enabled in a simulation.
At least one demographics file is required for every simulation unless you set the parameter Enable_Demographics_Builtin to 0 (zero) in the configuration file. This is generally only used for testing and validating code pathways by using a standard testing sandbox instead of actual demographics information. If Migration_Model is set to “FIXED_RATE_MIGRATION”, built-in demographics will use a form of local migration where individuals migrate only to adjacent nodes.
Demographics files are usually the only input data file you will modify. Demographics files are named using the name of the region, appended with “_demographics.json”.
Additionally, you can use more than one demographics file, with one serving as the base layer and the one or more others acting as overlays that override the values in the base layer.
Contents
Demographic file structure¶
Demographics files are organized into three sections:
- Metadata
Information such as data source, created date or region name. Metadata is used to provide provenance information.
- Defaults
Default parameter values applied to all nodes.
- Nodes
Parameter values specific to individual geographic nodes, which override the default values. There is one entry for each node in the simulation.
The following example shows the skeletal format of a demographics file.
{
"Metadata": {
"DateCreated": "dateTime",
"Tool": "scriptUsedToGenerate",
"Author": "author",
"IdReference": "ID reference",
"NodeCount": 2
},
"Defaults": {
"NodeAttributes": {},
"IndividualAttributes": {},
"IndividualProperties": {}
},
"Nodes": [{
"NodeID": 1,
"NodeAttributes": {},
"IndividualAttributes": {},
"IndividualProperties": {}
}, {
"NodeID": 2,
"NodeAttributes": {},
"IndividualAttributes": {},
"IndividualProperties": {}
}]
}
Most of the items in the Metadata section informational only and are not used by EMOD. This includes information such as author, date created, and tool used to create the file. However, the following two values are used by EMOD:
- NodeCount
The number of nodes to expect in the demographics file.
- IdReference
The unique string that indicates the method used for generating the NodeID, the identifier used for each node in the simulation.
See Input data file structure for more information about IdReference and NodeID generation.
Parameter values in the Defaults section is applied to all nodes. However, any node-level information provided in the Nodes section will take precedence for that node. The Defaults section is optional and can be completely omitted, as is often the case of single- node simulations. The Defaults section can contain any of the parameters listed below.
Parameter values in the Nodes section is applied to specific nodes. The intent of the Nodes section is to have only the information that is unique to each node, such as identifier and location (longitude and latitude). The section contains an array with each element in the array representing a node that is identified by its NodeID. The NodeID is a unique integer value. If a parameter appears in both the Defaults and Nodes sections, the value in the Nodes section will take precedence.
Parameters¶
The demographic parameters are divided into the following broad categories. The parameters will be contained in a nested JSON object of the same name.
Warning
Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false.
NodeAttributes are a JSON object that contains parameters that add or modify information regarding the location, migration, habitat, and population of a simulation. Some NodeAttributes depend on values set in the configuration parameters.
IndividualAttributes are a JSON object that contains parameters that add or modify the distribution of attributes across individuals in a simulation. For example, the age or immunity distribution. An initial value for an individual is a randomly selected value from a distribution. For example, if you use a uniform distribution to initialize age, the initial ages of individuals in the simulation will be evenly distributed between some minimum and maximum value.
There are two types of distributions: simple and complex. Simple distributions are defined by three parameters where one is the distribution type and the other two are used to further define the distribution. You can use complex distributions to define a distribution that does not fit some standard. For example, a complex distribution is useful when trying to represent real-world data.
The table below shows the simple distributions and their associated parameters.
Distribution |
Demographic parameters |
Related configuration parameters |
|---|---|---|
Age |
|
Age_Initialization_Distribution_Type must be set to “DISTRIBUTION_SIMPLE”. |
Prevalence |
|
Enable_Demographics_Other must be set to 1. |
Immunity |
|
|
Risk |
|
Enable_Demographics_Other must be set to 1. |
Migration heterogeneity |
|
Enable_Migration_Heterogeneity must be set to 1. |
The table below shows the available probability distribution types to use with simple distributions and how to set the other two demographic parameters to initialize the distribution.
Distribution type |
Flag value |
Distribution1 value |
Distribution2 value |
|---|---|---|---|
Constant |
0 |
Value |
N/A (set to 0) |
Uniform |
1 |
Minimum |
Maximum |
Gaussian |
2 |
Mean |
Standard deviation |
Exponential |
3 |
Mean |
N/A (set to 0) |
Poisson |
4 |
Mean |
N/A (set to 0) |
Log normal |
5 |
Mean |
Log (standard deviation) |
Bimodal |
6 |
Proportion of time to return the value specified by Distribution2. Value must be between 0 and 1. |
A positive value to be returned. If the value is not positive, a value of 1 is returned. |
Weibull |
7 |
Scale parameter |
Shape parameter |
EMOD also supports the following complex distributions:
AgeDistribution
FertilityDistribution
MortalityDistribution
MortalityDistributionMale
MortalityDistributionFemale
HIVCoinfectionDistribution
HIVMortalityDistribution
MSP_mean_antibody_distribution
nonspec_mean_antibody_distribution
PfEMP1_mean_antibody_distribution
MSP_variance_antibody_distribution
nonspec_variance_antibody_distribution Malaria
PfEMP1_variance_antibody_distribution
IndividualProperties are a JSON array that contains parameters that add properties to individuals in a simulation as a means of setting up groups. For example, you can define values for accessibility, age, geography, risk, and other properties and assign individuals to different groups based on those property values.
Parameter |
Data type |
Description |
Example |
|---|---|---|---|
Property |
string |
The property type for which you will assign values to create groups. Accepted values are:
|
{
"IndividualProperties": [{
"Property": "Risk"
}]
}
|
Values |
array |
An array of the user-defined values that can be assigned to individuals for this property. You can have up to 125 values for the Geographic property type and up to 5 values for all other types. For “Age_Bin” property types, omit and use Age_Bin_In_Years instead. |
{
"IndividualProperties": [{
"Values": ["Low", "Medium", "High"]
}]
}
|
Initial_Distribution |
array |
An array of numbers that define the proportion of individuals to assign to each group at the beginning of the simulation. Their total must equal 1 and the number of members in this array must match the number of members in Values. For “Age_Bin” property types, omit this parameter as the demographics file controls the age distribution. |
{
"IndividualProperties": [{
"Initial_Distribution": [0.2, 0.4, 0.4]
}]
}
|
Age_Bin_In_Years |
array |
An array of integers that represents the ages, in years, at which to demarcate the age groups. Used only with the “Age_Bin” property type. The first number must be 0, the last must be -1, and they must be listed in ascending order. |
The following example creates three age groups: 0 to 5, older than 5 to 13, and older than 13 to the maximum age. {
"IndividualProperties": [{
"Age_Bin_In_Years": [0, 5, 13, -1]
}]
}
|
Transitions |
array |
An array contains multiple JSON objects that each define how an individual transitions from one property group to another. See the following table for information about the parameters to include in the object. For “Age_Bin” property types, set to an empty array, as individuals will transition to the next age bin based on the passing of time. |
{
"IndividualProperties": [{
"Transitions": []
}]
}
|
TransmissionMatrix |
array |
An object that contains Route and Matrix parameters that define how to scale the base infectivity from individuals in one group to individuals in another. See Configure heterogeneous disease transmission for more information. |
{
"IndividualProperties": [{
"TransmissionMatrix": {
"Route": "Contact",
"Matrix": [
[10, 0.1],
[0.1, 1]
]
}
}]
}
|
The following table contains the parameters that are available to use in the Transitions array.
Parameter |
Data type |
Description |
Example |
|---|---|---|---|
From |
string |
Which group an individual will transition from. |
{
"Transitions": [{
"From": "Low"
}]
}
|
To |
string |
Which group an individual will transition to. |
{
"Transitions": [{
"To": "High"
}]
}
|
Type |
string |
The type of condition that starts transitioning individuals. Set to “At_Age” or “At_Timestep”. The other parameters you must set depend on the condition type set here. |
{
"Transitions": [{
"Type": "At_Age"
}]
}
|
Age_In_Years_Restriction |
nested JSON object |
The age when an individual is eligible to transition. Min is optional and Max is required. Do not use this with “At_Age” types because it will conflict with other age parameters in Age_In_Years. This is required for “At_Timestep” types, though it can be empty for no age restriction. |
{
"Transitions": [{
"Type": "At_Timestep",
"Age_In_Years_Restriction": {
"Min": 5,
"Max": 40
}
}]
}
|
Timestep_Restriction |
nested JSON object |
The time step when transitioning starts and stops. Required for both “At_Age” and “At_Timestep” types. Start is required and End is optional. |
{
"Transitions": [{
"Timestep_Restriction": {
"Start": 20
}
}]
}
|
Coverage |
float |
A value between 0 and 1 that indicates the proportion of the population that EMOD will attempt to transition. The calculation used with Probability_Per_Timeset only uses the proportion of the population specified in Cover to calculate the probability of an individual transitioning at a given time step. Coverage has no effect when the value is set to 1. Required for both “At_Age” and “At_Timestep” types. |
{
"Transitions": [{
"Coverage": 0.5
}]
}
|
Probability_Per_Timestep |
float |
A value between 0 and 1 that is used to calculate the probability of an individual transitioning at the current time step given the number of individuals remaining in the group. Required for both “At_Age” and “At_Timestep” types. |
{
"Transitions": [{
"Probability_Per_Timestep": 0.25
}]
}
|
Age_In_Years |
integer |
The age at which individuals are eligible to transition. Do not use for “At_Timestep” types. Required for “At_Age” types. |
{
"Transitions": [{
"Type": "At_Age",
"Age_In_Years": 10
}]
}
|
Timesteps_Until_Reversion |
integer |
The number of time steps after the start of transitioning when individuals revert back to their original group. The start of transitioning is specified by the Start parameter in Timestep_Restriction. |
{
"Transitions": [{
"Timestep_Restriction": {
"Start": 20
},
"Timesteps_Until_Reversion": 100
}]
}
|
Example¶
The example below shows a complete multi-node demographics file that uses a gridded IdReference type.
{
"Metadata": {
"DateCreated": "03/03/2016",
"Tool": "DemographicsWorker",
"Author": "Institute for Disease Modeling",
"NodeType": "Grid",
"ProjectName": "IDM-Madagascar",
"RegionName": "Madagascar",
"IdReference": "Gridded world grump2.5arcmin",
"NodeCount": 15,
"DataProvenance": "Generated by internally-developed demographic tools",
"Resolution": 150,
"UpperLatitude": -10.6666666666667,
"LeftLongitude": 41.6666666666667,
"BottomLatitude": -27.3333333333333,
"RightLongitude": 51.3333333333333
},
"Defaults": {
"NodeAttributes": {
"Altitude": 0,
"Airport": 0,
"Region": 1,
"Seaport": 0,
"BirthRate": 0.000102,
"AbovePoverty": 0
},
"IndividualAttributes": {
"AgeDistributionFlag": 3,
"AgeDistribution1": 0.00015,
"AgeDistribution2": 0,
"PrevalenceDistributionFlag": 1,
"PrevalenceDistribution1": 0.1,
"PrevalenceDistribution2": 0.2,
"ImmunityDistributionFlag": 0,
"ImmunityDistribution1": 1,
"ImmunityDistribution2": 0,
"RiskDistributionFlag": 0,
"RiskDistribution1": 1,
"RiskDistribution2": 0,
"MigrationHeterogeneityDistributionFlag": 0,
"MigrationHeterogeneityDistribution1": 1,
"MigrationHeterogeneityDistribution2": 0,
"MortalityDistribution": {
"NumDistributionAxes": 2,
"AxisNames": ["gender", "age"],
"AxisUnits": ["male=0,female=1", "years"],
"AxisScaleFactors": [1, 365],
"NumPopulationGroups": [2, 3],
"PopulationGroups": [
[0, 1],
[0, 100, 2000]
],
"ResultUnits": "annual deaths per 1000 individuals",
"ResultScaleFactor": 0.00000273972602739726027397260273973,
"ResultValues": [
[0, 20.0000035, 400.00007],
[0, 20.0000035, 400.00007]
]
}
}
},
"Nodes": [{
"NodeID": 358876977,
"NodeAttributes": {
"Latitude": -13.3125,
"Longitude": 48.1875,
"Altitude": 34,
"Area": 25,
"InitialPopulation": 2088,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 358876978,
"NodeAttributes": {
"Latitude": -13.2708330154419,
"Longitude": 48.1875,
"Altitude": 19,
"Area": 25,
"InitialPopulation": 1682,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 358942512,
"NodeAttributes": {
"Latitude": -13.3541669845581,
"Longitude": 48.2291679382324,
"Altitude": 127,
"Area": 25,
"InitialPopulation": 5160,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 358942513,
"NodeAttributes": {
"Latitude": -13.3125,
"Longitude": 48.2291679382324,
"Altitude": 128,
"Area": 25,
"InitialPopulation": 2860,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 358942514,
"NodeAttributes": {
"Latitude": -13.2708330154419,
"Longitude": 48.2291679382324,
"Altitude": 26,
"Area": 25,
"InitialPopulation": 790,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359008047,
"NodeAttributes": {
"Latitude": -13.3958330154419,
"Longitude": 48.2708320617676,
"Altitude": 48,
"Area": 25,
"InitialPopulation": 6436,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359008048,
"NodeAttributes": {
"Latitude": -13.3541669845581,
"Longitude": 48.2708320617676,
"Altitude": 111,
"Area": 25,
"InitialPopulation": 4983,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359008049,
"NodeAttributes": {
"Latitude": -13.3125,
"Longitude": 48.2708320617676,
"Altitude": 124,
"Area": 25,
"InitialPopulation": 1245,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359008050,
"NodeAttributes": {
"Latitude": -13.2708330154419,
"Longitude": 48.2708320617676,
"Altitude": 57,
"Area": 25,
"InitialPopulation": 1387,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359008051,
"NodeAttributes": {
"Latitude": -13.2291669845581,
"Longitude": 48.2708320617676,
"Altitude": 66,
"Area": 25,
"InitialPopulation": 1516,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359073583,
"NodeAttributes": {
"Latitude": -13.3958330154419,
"Longitude": 48.3125,
"Altitude": 132,
"Area": 25,
"InitialPopulation": 5957,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359073584,
"NodeAttributes": {
"Latitude": -13.3541669845581,
"Longitude": 48.3125,
"Altitude": 44,
"Area": 25,
"InitialPopulation": 643,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359073585,
"NodeAttributes": {
"Latitude": -13.3125,
"Longitude": 48.3125,
"Altitude": 55,
"Area": 25,
"InitialPopulation": 1171,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359073587,
"NodeAttributes": {
"Latitude": -13.2291669845581,
"Longitude": 48.3125,
"Altitude": 36,
"Area": 25,
"InitialPopulation": 378,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359139117,
"NodeAttributes": {
"Latitude": -13.4791669845581,
"Longitude": 48.3541679382324,
"Altitude": 282,
"Area": 25,
"InitialPopulation": 674,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}]
}
Configuration parameters¶
The parameters described in this reference section determine the behavior of a simulation. Simulations are configured in a configuration file. This file is a JavaScript Object Notation (JSON) formatted file that contains mostly a flat list of JSON key-value pairs. For information on JSON, see EMOD parameter reference.
Warning
Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false.
The tables below contain only parameters available when using the tuberculosis simulation type.
Cluster options¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Load_Balance_Filename |
string |
NA |
NA |
UNINITIALIZED STRING |
Path to input file used when a static load balancing scheme is selected. |
|
Num_Cores |
integer |
NA |
NA |
NA |
Number of cores used to run a simulation. This is used by the infrastructure that runs the job, such as an HPC cluster or the Regression scripts, and is not used by the DTK. |
Demographics¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Age_Initialization_Distribution_Type |
enum |
NA |
NA |
DISTRIBUTION_OFF |
Method for initializing the age distribution in the simulated population. Possible values are: DISTRIBUTION_OFF - All individuals default to age 20-years-old. DISTRIBUTION_SIMPLE - Individual ages are drawn from a distribution whose functional form and parameters are specified in the IndividualAttributes demographics input layers: AgeDistributionFlag, AgeDistribution1, and AgeDistribution2. DISTRIBUTION_COMPLEX - Individual ages are drawn from a piecewise linear distribution specified in the IndividualAttributes demographics input layer AgeDistribution. |
|
Base_Population_Scale_Factor |
float |
0 |
3.40E+38 |
1 |
If Population_Scale_Type is set to FIXED_SCALING, the initial simulation population is uniformly scaled over the entire area to adjust for historical or future population density. |
|
Birth_Rate_Dependence |
enum |
NA |
NA |
FIXED_BIRTH_RATE |
This parameter determines how the birth rate specified in the demographics file is used. Possible values are: FIXED_BIRTH_RATE- The absolute rate at which new individuals are born. POPULATION_DEP_RATE - Scales the node population to determine the birth rate. DEMOGRAPHIC_DEP_RATE - Scales the female population within fertility age ranges to determine the birth rate. INDIVIDUAL_PREGNANCIES - Results in a similar birth rate as DEMOGRAPHIC_DEP_RATE, but pregnancies are assigned on an individual basis and result in a 40-week pregnancy for a specific individual with a birth at the end, INDIVIDUAL_PREGNANCIES_BY_URBAN_AND_AGE, and INDIVIDUAL_PREGNANCIES_BY_AGE_AND_YEAR. |
|
Death_Rate_Dependence |
enum |
NA |
NA |
NONDISEASE_MORTALITY_OFF |
This parameter determines how the death rate specified in the demographics file is used. Possible values are: NONDISEASE_MORTALITY_OFF, NONDISEASE_MORTALITY_BY_AGE_AND_GENDER and NONDISEASE_MORTALITY_BY_YEAR_AND_AGE_FOR_EACH_GENDER. |
|
Enable_Aging |
boolean |
0 |
1 |
1 |
Set to 1 to account for aging in the population. Set to 0 to assume that the population does not age. |
|
Enable_Birth |
boolean |
0 |
1 |
1 |
Set to 1 to enable individuals to be added to the simulation by birth. |
|
Enable_Demographics_Birth |
boolean |
0 |
1 |
0 |
Assumes that newborn characteristics such as sickle-cell status are heterogeneous. Set to 0 to assume by default that all newborns have identical characteristics. |
|
Enable_Demographics_Builtin |
boolean |
0 |
1 |
0 |
Uses demographics input files to configure the initial population. Enter 0 to use a standard testing sandbox which is useful for testing and validating code pathways. |
|
Enable_Demographics_Gender |
boolean |
0 |
1 |
1 |
Enable_Demographics_Gender=0 assigns gender based on a 50/50 draw, while Enable_Demographics_Gender=1 draws from a male/female ratio that is randomly smeared by a Gaussian of width 1%. |
|
Enable_Demographics_Other |
boolean |
0 |
1 |
0 |
Includes the impact of other relevant demographic factors. For example, fraction of individuals above poverty, urban/rural characteristics, heterogeneous initial immunity and risk. Set to 0 to run the simulation without other relevant demographic factors. |
|
Enable_Disease_Mortality |
boolean |
0 |
1 |
1 |
Set to 1 to enable disease mortality. Set to 0 to disable disease mortality. |
|
Enable_Heterogeneous_Intranode_Transmission |
boolean |
0 |
1 |
0 |
Set to 1 to enable heterogeneous intra-node disease transmission. Requires individual property definitions and beta matrix to be specified. Set to 0 to disable. |
|
Enable_Vital_Dynamics |
boolean |
0 |
1 |
1 |
Set to 1 as a master switch to enable vital dynamics (births and deaths). Set to 0 to disable vital dynamics. Even when set to 1, the individual toggles for births and deaths can still disable these. |
|
Population_Scale_Type |
enum |
NA |
NA |
USE_INPUT_FILE |
Either use the initial population specified in the demographics input file or a fixed scaling of this value based on the population scaling factor parameter. Possible values are: USE_INPUT_FILE and FIXED_SCALING. |
Event recorder report settings¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Report_Event_Recorder |
boolean |
0 |
1 |
0 |
Enables or disables the ReportEventRecorder.csv report. |
|
Report_Event_Recorder_Ignore_Events_In_List |
boolean |
0 |
1 |
0 |
f this flag is set to true, all events listed in Report_Event_Recorder_Events will be ignored. If it is set to false, all events will be recorded. |
|
Report_Event_Recorder_Individual_Properties |
Dynamic String Set |
NA |
NA |
NA |
Fraction of individuals in the target demographic that will receive this intervention. |
General disease¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Acquisition_Blocking_Immunity_Duration_Before_Decay |
float |
0 |
45000 |
0 |
Number of days after infection until acquisition-blocking immunity begins to decay. Relevant only when Enable_Immunity and Enable_Immune_Decay parameters are set to 1. |
|
Animal_Reservoir_Type |
enum |
NA |
NA |
NO_ZOONOSIS |
Configures whether there is an animal reservoir and how the risk of zoonosis in configured. Use of the animal reservoir sets a low constant baseline of infectivity beyond what is present in the human population. It allows a more random introduction of cases in continuous time, which is more applicable for various situations such as zoonosis. Possible values are: NO_ZOONOSIS, CONSTANT_ZOONOSIS where the daily rate of zoonotic infection is configured by the parameter Zoonosis_Rate, and ZOONOSIS_FROM_DEMOGRAPHICS where the zoonosis rate is additionally scaled by the node-specific Zoonosis value in the NodeAttributes section of a demographics overlay file. See Zoonosis_Rate. |
|
Base_Incubation_Period |
float |
0 |
3.40E+38 |
6 |
Average duration, in days, of the incubation period before infected individuals becomes infectious. |
|
Base_Infectious_Period |
float |
0 |
3.40E+38 |
6 |
Average duration, in days, of the infectious period before the infection is cleared. |
|
Base_Infectivity |
float |
0 |
1000 |
0.3 |
The Base_Infectivity parameter determines the base infectiousness of individuals before accounting for transmission-blocking effects of acquired immunity and/or campaign interventions. It has a slightly different meaning for each of the disease types. GENERIC_SIM: The average number of individuals per time step who will be exposed to infection by one infectious individual. In the case of super-infection, the infectiousness is summed over all infections. VECTOR_SIM: The probability of infecting a mosquito during a successful blood meal (modulated by the vector parameter Acquire_Modifier). For vector simulations, the sum infectiousness of an individual is not allowed to exceed 100%. MALARIA_SIM: This simple scale factor is not used. Instead, gametocyte abundances and cytokine-mediated infectiousness are modeled explicitly. |
|
Base_Mortality |
float |
0 |
1000 |
0.001 |
The base mortality of the infection before accounting for individual immune modification factors. Depending on the setting of Mortality_Time_Course, this is either the daily probability of the disease being fatal (DAILY_MORTALITY) or the probability of death at the end of the infection duration (MORTALITY_AFTER_INFECTIOUS). |
|
Enable_Immune_Decay |
boolean |
0 |
1 |
1 |
Set to 1 if immunity decays after an infection clears. Set to 0 if recovery from the disease confers complete immunity for life. |
|
Enable_Immunity |
boolean |
0 |
1 |
1 |
Set to 1 if an individual has protective immunity after an infection clears. Set to 0 if recovery from the infection does not affect the individual’s future immunity. |
|
Enable_Maternal_Transmission |
boolean |
0 |
1 |
0 |
Set to 1 to account for infection of infants at birth by infected mothers. Set to 0 to assume that infection is not transmitted by mothers to infants at birth. |
|
Enable_Superinfection |
boolean |
0 |
1 |
0 |
Set to 1 if an individual can have multiple infections with the same agent simultaneously. Set to 0 if multiple infections are not possible. See the Max_Individual_Infections parameter. |
|
Immunity_Acquisition_Factor |
float |
0 |
1000 |
0 |
Multiplicative reduction in probability of reacquiring the disease. Relevant only when Enable_Immunity and Enable_Immune_Decay parameters are set to 1. |
|
Immunity_Initialization_Distribution_Type |
enum |
NA |
NA |
DISTRIBUTION_OFF |
Method for initializing the immunity distribution in the simulated population. Possible values are: DISTRIBUTION_OFF - All individuals default to no immunity. DISTRIBUTION_SIMPLE - Individual immunities are drawn from a distribution whose functional form and parameters are specified in the IndividualAttributes demographics input layers: ImmunityDistributionFlag, ImmunityDistribution1, and ImmunityDistribution2. DISTRIBUTION_COMPLEX - Individual immnunities are drawn from an age-dependent piecewise l. |
|
Immunity_Mortality_Factor |
float |
0 |
1000 |
0 |
Multiplicative reduction in probability of dying from infection after getting re-infected. Relevant only when Enable_Immunity and Enable_Immune_Decay parameters are set to 1. |
|
Immunity_Transmission_Factor |
float |
0 |
1000 |
0 |
Multiplicative reduction in probability of transmitting infection after getting re-infected. Relevant only when Enable_Immunity and Enable_Immune_Decay parameters are set to 1. |
|
Incubation_Period_Distribution |
enum |
NA |
NA |
NOT_INITIALIZED |
Distribution of duration of incubation period. Can be fixed or exponentially distributed with an average duration from Base_Incubation_Period. Possible values are: FIXED_DURATION and EXPONENTIAL_DURATION. |
|
Incubation_Period_Max |
float |
0.6 |
3.40E+38 |
0 |
The maximum length of the incubation period. Used when Incubation_Period_Distribution is UNIFORM_DURATION. |
|
Incubation_Period_Mean |
float |
0 |
3.40E+38 |
6 |
The standard deviation used when Incubation_Period_Distribution is either GAUSSIAN_DURATION or POISSON_DURATION. |
|
Incubation_Period_Min |
float |
0 |
3.40E+38 |
0 |
The minimum length of the incubation period. Used when the Incubation_Period_Distribution is UNIFORM_DURATION. |
|
Incubation_Period_Std_Dev |
float |
0 |
3.40E+38 |
1 |
The standard deviation incubation period. Used when the Incubation_Period_Distribution is GAUSSIAN_DURATION. |
|
Infection_Updates_Per_Timestep |
integer |
0 |
144 |
1 |
Number of infection updates executed during each timestep. A timestep defaults to one day. |
|
Infectious_Period_Distribution |
enum |
NA |
NA |
NOT_INITIALIZED |
Distribution of duration of infectious period. Can be fixed or exponentially distributed with an average duration from Base_Infectious_Period. Possible values are: FIXED_DURATION, EXPONENTIAL_DURATION. |
|
Infectious_Period_Max |
float |
0.6 |
3.40E+38 |
0 |
The maximum length of the infectious period. Used when Infectious_Period_Distribution is UNIFORM_DURATION. |
|
Infectious_Period_Mean |
float |
0 |
3.40E+38 |
6 |
The mean of the infectious period. Used when Infectious_Period_Distribution is either GAUSSIAN_DURATION or POISSON_DURATION. |
|
Infectious_Period_Min |
float |
0 |
3.40E+38 |
0 |
The minimum length of the infectious period. Used when the Infectious_Period_Distribution is UNIFORM_DURATION. |
|
Infectious_Period_Std_Dev |
float |
0 |
3.40E+38 |
1 |
The standard deviation of the infectious period. Used when the Infectious_Period_Distribution is GAUSSIAN_DURATION. |
|
Infectivity_Scale_Type |
enum |
NA |
NA |
CONSTANT_INFECTIVITY |
Alter infectivity by time or season. Possible values are: CONSTANT_INFECTIVITY - No infectivity correction is applied. FUNCTION_OF_TIME_AND_LATITUDE - Infectivity is corrected for approximate seasonal forcing. The use of a seasonal infectivity correction is a proxy for the effects of varying climate. From October through March, infectivity increases in the Northern Hemisphere and decreases in the Southern Hemisphere. From April through September, the trend reverses. Regions closer to the equator have reduced forcing compared to temperate regions. This is not a substitute for the weather-driven vector dynamics of vector-borne and malaria simulations. FUNCTION_OF_CLIMATE - Allows infectivity to be modulated by weather directly, for example, relative humidity in airborne simulations or rainfall in environmental simulations. There is no default climate dependence enabled for generic simulations. EXPONENTIAL_FUNCTION_OF_TIME - To facilitate certain burn-in scenarios, infectivity ramps up from zero at the beginning of the simulation according to the functional form, 1-exp(-rate*time), where the rate is specified by the parameter Infectivity_Scaling_Rate. |
|
Maternal_Transmission_Probability |
float |
0 |
1 |
0 |
Probability of transmission of infection from mother to infant at birth. Relevant only if Enable_Maternal_Transmission is set to 1. Note: This parameter should be set to 0 and ignored for malaria and vector simulations. |
|
Max_Individual_Infections |
integer |
0 |
1000 |
1 |
Limit on the number of infections that an individual can have simultaneously. Note: Relevant only if the Enable_Superinfection parameter is set to 1 to allow multiple infections. |
|
Mortality_Blocking_Immunity_Decay_Rate |
float |
0 |
1000 |
0.001 |
Rate at which mortality-blocking immunity decays after the mortality-blocking immunity offset period. Relevant only when Enable_Immunity and Enable_Immune_Decay parameters are set to 1. |
|
Mortality_Time_Course |
enum |
NA |
NA |
DAILY_MORTALITY |
Determines whether disease deaths are calculated on every time step or once at the end of the disease duration. Possible values are: DAILY_MORTALITY and MORTALITY_AFTER_INFECTIOUS. |
|
Number_Basestrains |
integer |
1 |
10 |
1 |
The number of base strains in the simulation, such as antigenic variants. |
|
Number_Substrains |
integer |
1 |
16777200 |
256 |
The number of disease substrains for each base strain, such as genetic variants. |
|
Population_Density_Infectivity_Correction |
enum |
NA |
NA |
CONSTANT_INFECTIVITY |
Correction to alter infectivity by population density set in the Population_Density_C50 parameter. Measured in people per sq. km. Possible values are: CONSTANT_INFECTIVITY and SATURATING_FUNCTION_OF_DENSITY. Note: Sparsely populated areas have a lower infectivity, while densely populated areas have a higher infectivity which rises to saturate at the Base_Infectivity value. |
|
Transmission_Blocking_Immunity_Decay_Rate |
float |
0 |
1000 |
0.001 |
Rate at which transmission-blocking immunity decays after the base transmission-blocking immunity offset period. Relevant only when Enable_Immunity and Enable_Immune_Decay parameters are set to 1. |
|
Transmission_Blocking_Immunity_Duration_Before_Decay |
float |
0 |
45000 |
0 |
Number of days after infection until transmission-blocking immunity begins to decay. Relevant only when Enable_Immunity and Enable_Immune_Decay parameters are set to 1. |
|
Zoonosis_Rate |
float |
0 |
1 |
0 |
The daily rate of zoonotic infection per individual when the Animal_Reservoir_Type parameter is set to either CONSTANT_ZOONOSIS or ZOONOSIS_FROM_DEMOGRAPHICS. |
Geography and environment¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Air_Temperature_Variance |
float |
0 |
5 |
2 |
The standard deviation (in degrees Celsius) for normally distributed noise applied to the daily air temperature values when Climate_Model is configured as CLIMATE_CONSTANT or CLIMATE_BY_DATA. Only used if the Enable_Climate_Stochasticity is set to 1. |
|
Base_Air_Temperature |
float |
-55 |
45 |
22 |
The value of air temperature where Climate_Model is set to CLIMATE_CONSTANT. |
|
Base_Land_Temperature |
float |
-55 |
60 |
26 |
The value of land temperature where Climate_Model is set to CLIMATE_CONSTANT. |
|
Base_Rainfall |
float |
0 |
150 |
10 |
The value of rainfall per day in mm when Climate_Model is set to CLIMATE_CONSTANT. |
|
Base_Relative_Humidity |
float |
0 |
1 |
0.75 |
The value of humidity where Climate_Model is set to CLIMATE_CONSTANT. |
|
Climate_Model |
enum |
NA |
NA |
CLIMATE_OFF |
Determines how the climate of a simulation is configured and from what file(s). Possible values are: CLIMATE_OFF, CLIMATE_CONSTANT - Uses the conditional parameters that give the fixed values of temperature or rain for land temperature, air temperature, rainfall and humidity. CLIMATE_KOPPEN - Uses an input file that decodes Koppen codes by geographic location. CLIMATE_BY_DATA - Reads everything out of several input files with additional parameters that allow the addition of stochasticity or scale offsets. |
|
Climate_Update_Resolution |
enum |
NA |
NA |
CLIMATE_UPDATE_YEAR |
Update resolution for data in climate files. Possible values are: CLIMATE_UPDATE_YEAR, CLIMATE_UPDATE_MONTH, CLIMATE_UPDATE_WEEK, CLIMATE_UPDATE_DAY and CLIMATE_UPDATE_HOUR. |
|
Default_Geography_Initial_Node_Population |
integer |
0 |
1000000 |
1000 |
When using the default geography (i.e. Enable_Demographics_Initial = 0), this is the initial number of individuals in each node. |
|
Default_Geography_Torus_Size |
integer |
3 |
100 |
10 |
When using the default geography (i.e. Enable_Demographics_Initial = 0), this is the square root of the number of nodes in the simulation. For migration, the nodes are assumed to be a torus. |
|
Enable_Climate_Stochasticity |
boolean |
0 |
1 |
0 |
Controls overall stochasticity for climate. Use value 0 to disable all additional climate stochasticity. Use value 1 to enable additional variation as specified by the parameters: Air_Temperature_Variance, Land_Temperature_Variance, Enable_Rainfall_Stochasticity and Relative_Humidity_Variance. |
|
Enable_Rainfall_Stochasticity |
boolean |
0 |
1 |
1 |
Set to 0 to disable rainfall stochasticity. Set to 1 to enable stochastic variation of rainfall drawn from an exponential distribution (with a mean value as the daily rainfall from the Climate_Model values, CLIMATE_CONSTANT or CLIMATE_BY_DATA). |
|
Land_Temperature_Offset |
float |
-20 |
20 |
0 |
The linear shift of land surface temperature in degrees Celsius. This is only used or needed when Climate_Model is set to CLIMATE_BY_DATA. |
|
Land_Temperature_Variance |
float |
0 |
7 |
2 |
The standard deviation (in degrees Celsius) for normally distributed noise applied to the daily land temperature values when Climate_Model is configured as CLIMATE_CONSTANT or CLIMATE_BY_DATA. Only used if the Enable_Climate_Stochasticity is set to 1. |
|
Node_Grid_Size |
float |
0.004167 |
90 |
0.004167 |
Spatial resolution indicating the node grid size for a simulation in degrees. |
|
Rainfall_In_mm_To_Fill_Swamp |
float |
1 |
10000 |
1000 |
Millimeters of rain to fill larval habitat to capacity. Only used for vector species with Habitat_Type set to BRACKISH_SWAMP. |
|
Rainfall_Scale_Factor |
float |
0.1 |
10 |
1 |
The scalar used in multiplying rainfall value(s). This is only used or needed when Climate_Model is set to CLIMATE_BY_DATA. |
|
Relative_Humidity_Scale_Factor |
float |
0.1 |
10 |
1 |
The scalar used in multiplying relative humidity value(s). This is only used or needed when Climate_Model is set to CLIMATE_BY_DATA. |
|
Relative_Humidity_Variance |
float |
0 |
0.12 |
0.05 |
The standard deviation (in percentage, %) for normally distributed noise applied to the daily relative humidity values when Climate_Model is configured as CLIMATE_CONSTANT or CLIMATE_BY_DATA. Only used if the Enable_Climate_Stochasticity is set to 1. |
Input files¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Air_Migration_Filename |
string |
NA |
NA |
Path of input file defining patterns of migration by airplane. |
||
Air_Temperature_Filename |
string |
NA |
NA |
air_temp.json |
Path of input file defining air temperature data measured 2 meters above ground. Relevant only if Climate_Model is set to CLIMATE_BY_DATA. |
|
Campaign_Filename |
string |
NA |
NA |
Path of the simulation campaign file. This configuration file defines campaign related settings and thus, is an optional file, only required when interventions are part of the simulation. |
||
Demographics_Filenames |
Vector String |
NA |
NA |
Array of demographics files containing information on the identity and demographics of the region to simulate. |
||
Koppen_Filename |
string |
NA |
NA |
UNINITIALIZED STRING |
Path to input file used to specify Koppen climate classifications. This is only used or needed when Climate_Model is set to CLIMATE_KOPPEN. |
|
Land_Temperature_Filename |
string |
NA |
NA |
land_temp.json |
Path of input file defining temperature data measured at land surface. Relevant only if Climate_Model is set to CLIMATE_BY_DATA. |
|
Local_Migration_Filename |
string |
NA |
NA |
Path of input file defining patterns of migration to adjacent nodes by foot travel. |
||
Rainfall_Filename |
string |
NA |
NA |
rainfall.json |
Path of input file defining rainfall data. Relevant only if Climate_Model is set to CLIMATE_BY_DATA. |
|
Regional_Migration_Filename |
string |
NA |
NA |
Path of input file defining patterns of migration by vehicle via road or rail network. If the node is not on a road or rail network, regional migration focuses on the closest hub city in the network. |
||
Relative_Humidity_Filename |
string |
NA |
NA |
rel_hum.json |
Path of input file defining relative humidity data measured 2 meters above ground. Relevant only if Climate_Model is set to CLIMATE_BY_DATA. |
|
Sea_Migration_Filename |
string |
NA |
NA |
Path of input file defining patterns of migration by ship. |
Migration¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Air_Migration_Roundtrip_Duration |
float |
0 |
10000 |
1 |
The average time spent at the destination node during a round-trip migration by airplane. |
|
Air_Migration_Roundtrip_Probability |
float |
0 |
1 |
0.8 |
Likelihood that an individual who flies to another cell will return to the cell of origin during the next migration. Relevant only when Enable_Air_Migration is selected. |
|
Enable_Air_Migration |
boolean |
0 |
1 |
0 |
Set to 1 to account for migration by airplane in and out of cities with airports. Set to 0 to assume by default that no migration occurs by air travel. |
|
Enable_Local_Migration |
boolean |
0 |
1 |
0 |
Set to 1 to enable local migration, the diffusion of people in and out of nearby nodes by foot travel. Set to 0 to disable local migration. |
|
Enable_Migration_Heterogeneity |
boolean |
0 |
1 |
1 |
Set to 1 to use migration rate distribution in the demographics file. Set to 0 to assume by default that the same migration rate applies for all individuals. |
|
Enable_Regional_Migration |
boolean |
0 |
1 |
0 |
Set to 1 to account for migration by road vehicle in and out of nodal cities in the road network. Set to 0 to assume by default that no migration occurs by road travel. |
|
Enable_Sea_Migration |
boolean |
0 |
1 |
0 |
Set to 1 to account for migration on ships in and out of coastal cities with seaports. Set to 0 to assume by default that no migration occurs by sea travel. |
|
Local_Migration_Roundtrip_Duration |
float |
0 |
10000 |
1 |
The average time spent at the destination node during a round-trip migration by foot travel. |
|
Local_Migration_Roundtrip_Probability |
float |
0 |
1 |
0.95 |
Likelihood that an individual who walks into a neighboring cell will return to the cell of origin during the next migration. Relevant only when Enable_Local_Migration is selected. |
|
Migration_Model |
enum |
NA |
NA |
NO_MIGRATION |
Model to use for migration. Possible values are: NO_MIGRATION, FIXED_RATE_MIGRATION, VARIABLE_RATE_MIGRATION and LEVY_FLIGHTS. Note: VARIABLE_RATE_MIGRATION and LEVY FLIGHTS are currently not supported. |
|
Migration_Pattern |
enum |
NA |
NA |
RANDOM_WALK_DIFFUSION |
The type of roundtrip. For example, a single roundtrip. Possible values are: RANDOM_WALK_DIFFUSION, SINGLE_ROUND_TRIPS and WAYPOINTS_HOME. |
|
Regional_Migration_Roundtrip_Duration |
float |
0 |
10000 |
1 |
The average time spent at the destination node during a round-trip migration by road network. |
|
Regional_Migration_Roundtrip_Probability |
float |
0 |
1 |
0.1 |
Likelihood that an individual who travels by vehicle to another cell will return to the cell of origin during the next migration. Relevant only when Enable_Regional_Migration is checked. |
|
Roundtrip_Waypoints |
integer |
0 |
1000 |
10 |
The maximum number of points reached during a trip before steps are retraced on the return trip home. |
|
Sea_Migration_Roundtrip_Duration |
float |
0 |
10000 |
1 |
The average time spent at the destination node during a round-trip migration by ship. |
|
Sea_Migration_Roundtrip_Probability |
float |
0 |
1 |
0.25 |
Likelihood that an individual who travels by ship into a neighboring cell will return to the cell of origin during the next migration. Relevant only when Enable_Sea_Migration is checked. |
Output options¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Enable_Default_Reporting |
boolean |
0 |
1 |
1 |
Enables and disables the default InsetChart.json report. |
|
Enable_Demographics_Reporting |
boolean |
0 |
1 |
1 |
Outputs demographic summary data and age-binned reports to file. |
|
Enable_Property_Output |
boolean |
0 |
1 |
0 |
Use value 0 to disable Individual_Property reports (separate file). Use value 1 to enable. |
|
Enable_Spatial_Output |
boolean |
0 |
1 |
0 |
Use value 0 to disable all spatial output channels. Use value 1 to enable spatial output of all channels listed in the array parameter: Spatial_Output_Channels. For full documentation of spatial output channels, please see the online documentation. |
|
Report_Event_Recorder |
boolean |
0 |
1 |
1 |
Enables or disables the ReportEventRecorder.csv report. |
Sampling¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Base_Individual_Sample_Rate |
float |
0 |
1 |
1 |
Base rate of sampling for individuals. This rate equals the fraction of individuals in each node being sampled. |
|
Individual_Sampling_Type |
enum |
NA |
NA |
TRACK_ALL |
Type of individual human sampling. Possible values are: TRACK_ALL, FIXED_SAMPLING, ADAPTED_SAMPLING_BY_POPULATION_SIZE, ADAPTED_SAMPLING_BY_AGE_GROUP, and ADAPTED_SAMPLING_BY_AGE_GROUP_AND_POP_SIZE. |
|
Max_Node_Population_Samples |
float |
1 |
3.40E+38 |
30 |
Number of individuals when the sampling rate starts dropping to the rate of adapted sampling by population size. |
Scaling factors¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
x_Air_Migration |
float |
0 |
3.40E+38 |
1 |
Multiplier for rate of migration by air. |
|
x_Birth |
float |
0 |
3.40E+38 |
1 |
Multiplier of birth rate from input demographics file. |
|
x_Local_Migration |
float |
0 |
3.40E+38 |
1 |
Multiplier for rate of migration by foot travel. |
|
x_Other_Mortality |
float |
0 |
3.40E+38 |
1 |
Multiplier for scaling mortality from causes other than disease being simulated. |
|
x_Regional_Migration |
float |
0 |
3.40E+38 |
1 |
Multiplier for rate of migration by road vehicle. |
|
x_Sea_Migration |
float |
0 |
3.40E+38 |
1 |
Multiplier for rate of migration by sea. |
|
x_Temporary_Larval_Habitat |
double |
NA |
NA |
1 |
Scales the habitat size for all mosquito populations. |
Simulation setup¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Config_Name |
string |
NA |
NA |
UNINITIALIZED STRING |
User-supplied title naming a configuration. |
|
Enable_Interventions |
boolean |
0 |
1 |
0 |
Set to 1 to load campaign interventions from file. Set to 0 to run a baseline simulation without campaigns. |
|
Run_Number |
integer |
0 |
2147480000 |
1 |
Sets the random number seed through a bit manipulation process for USE_PSEUDO_DES. When running a multi-core simulation, combines with processor rank to produce independent random number streams for each process. |
|
Simulation_Duration |
float |
0 |
1000000 |
1 |
Elapsed time noted in days from the start to the end of a simulation. |
|
Simulation_Timestep |
float |
0 |
1000000 |
1 |
Value indicating simulation time step in days. |
|
Simulation_Type |
enum |
NA |
NA |
GENERIC_SIM |
Type of disease being simulated. Supported values include GENERIC_SIM, VECTOR_SIM, MALARIA_SIM, TB_SIM, STI_SIM, HIV_SIM, and PY_SIM. To query the values supported for your specific build, use the –version option. |
|
Start_Time |
float |
0 |
1000000 |
1 |
Time noted in days when the simulation begins. This time influences the point in the temporal input data, such as where in the climate input the DTK starts running the simulation. Note: The Start_Day of campaign events is in absolute time. So, time relative to the beginning of the simulation depends on this parameter. |
Spatial output channels¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Spatial_Output_Channels |
Fixed String Set |
NA |
NA |
[] |
An array of channel names for spatial output by Node and time step. The data from each channel will be written to a separate binary file. Channel names include Air_Temperature, Births, Campaign_Cost, Disease_Deaths, Human_Infectious_Reservoir, Infection_Rate, Land_Temperature, New_Infections, New_Reported_Infections, Population, Rainfall and Relative_Humidity. |
Campaign parameters¶
The parameters described in this reference section determine the interventions used as part of a campaign to control the spread of a disease and the outbreak of the disease itself. Interventions are configured in the campaign file. They are enabled in the configuration file by setting the parameter, Enable_Interventions, to 1. The configuration file also indicates the name of the campaign file.
Warning
The Outbreak must be the last event in the campaign file or none of the interventions will take place.
EMOD supports a variety of supported campaign interventions. It is worth noting that each intervention contains multiple parameters used to configure that specific event. For example, the distribution of bednets behaves differently in the model than does the use of larvicides. It is therefore important to ensure that interventions are configured correctly and applied to the appropriate level target (individual versus node).
This framework enables rigorous testing of possible control strategies to determine which events or combination of events will best aid in the elimination of disease for specific geographic locations.
Like the configuration file, the campaign file is a JavaScript Object Notation (JSON) formatted file. For information on JSON, see EMOD parameter reference. However, the configuration file is mostly a flat list of JSON key-value pairs while the campaign file is structured as an array of campaign events that contain many nested JSON objects. For more information on how to set up the elements in a campaign file, see Create a campaign file.
Warning
Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false.
The tables below contain only parameters available when using the tuberculosis simulation type.
Events array¶
The campaign file contains an Events array with one or more CampaignEvent elements and a Use_Defaults parameter. If Use_Defaults is set to 1, the simulation will use the default values for required parameters that are not configured in the campaign file. If it is set to 0, you must configure all required parameters.
{
"Events": [{
"Event_Name": "Campaign Event 1",
"class": "CampaignEvent"
}, {
"Event_Name": "Campaign Event 2",
"class": "CampaignEvent"
}],
"Use_Defaults": 1
}
Campaign event¶
To distribute an intervention, you must configure a campaign event, an event coordinator, and the intervention. The campaign event configures when the event occurs (Start_Day) and where it is distributed (Nodeset_Config). The event coordinator is a nested JSON object in Event_Coordinator_Config. For more information on how to structure this file, see Create a campaign file.
{
"Event_Name": "Campaign Event Example",
"class": "CampaignEvent",
"Start_Day": 1,
"Nodeset_Config": {
},
"Event_Coordinator_Config": {
}
}
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Event_Coordinator_Config |
EventCoordinator |
0 |
3.40E+38 |
1 |
The configuration of the EventCoordinator to be instantiated. |
|
Nodeset_Config |
NodeSet |
0 |
3.40E+38 |
1 |
The NodeSet describing the nodes covered by the event. |
|
Start_Day |
float |
0 |
3.40E+38 |
1 |
Day of the simulation to activate the event’s event coordinator. |
The Event_Coordinator_Config configures who can receive the intervention (for example, Target_Demographic and Demographic_Coverage) and which intervention is distributed. The intervention is a nested JSON object in Intervention_Config.
{
"Event_Coordinator_Config": {
"class": "The event coordinator that will be used.",
"Target_Demographic": "Everyone",
"Demographic_Coverage": 0.0005,
"Intervention_Config": {}
}
}
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Demographic_Coverage |
float |
0 |
1 |
1 |
Fraction of individuals in the target demographic that will receive this intervention. |
|
Intervention_Config |
Intervention |
0 |
3.40E+38 |
3.40E+38 |
The nested json of the actual intervention to be distributed by this event coordinator. |
|
Number_Repetitions |
integer |
-1 |
1000 |
-1 |
Number of times intervention given, used with tsteps_between_reps. |
|
Property_Restrictions |
Dynamic String Set |
NA |
NA |
[] |
Fraction of individuals in the target demographic that will receive this intervention. |
|
Property_Restrictions_Within_Node |
PropertyRestrictions |
NA |
NA |
Everyone |
Fraction of individuals in the target demographic that will receive this intervention. |
|
Target_Age_Max |
float |
0 |
3.40E+38 |
3.40E+38 |
Upper end of age targeted for intervention, in years. |
|
Target_Age_Min |
float |
0 |
3.40E+38 |
0 |
Lower end of age targeted for intervention, in years. |
|
Target_Demographic |
enum |
NA |
NA |
Everyone |
The demographic group (from a list of possibles) targeted by this intervention (e.g., Infants). |
|
Target_Gender |
enum |
NA |
NA |
All |
Specify the gender restriction for the intervention. Defaults to All. |
|
Target_Residents_Only |
boolean |
0 |
1 |
0 |
If true, only distribute the intervention to those that claim the node as their residence - i.e. started in the node |
|
Timesteps_Between_Repetitions |
integer |
-1 |
10000 |
-1 |
Repetition interval. |
There are three configuration options: NodeSetAll, NodeSetNodeList and NodeSetPolygon.
If you are running a simulation that is in a single location (node) or you want the intervention to be distributed in all of the nodes, use NodeSetAll.
{
"Nodeset_Config": "NodeSetAll"
}
The intervention is distributed to nodes in the intervention list.
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Node_List |
NodeListConfig |
NA |
NA |
SHAPE |
Comma-separated list of node IDs. |
The intervention is distributed in nodes within the specified polygon.
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Polygon_Format |
enum |
NA |
NA |
SHAPE |
Right now just SHAPE. |
|
Vertices |
string |
NA |
NA |
SHAPE |
Comma-separated list of polygon points. |
Interventions¶
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Actual_IndividualIntervention_Config |
IndividualIntervention |
0 |
1 |
0 |
The configuration of the actual individual-based intervention sought. Selects a class for the intervention and configures the parameters specific for that intervention class. |
|
Demographic_Coverage |
float |
0 |
1 |
1 |
Fraction of individuals in the target demographic that will receive this intervention. |
|
Duration |
float |
-1 |
3.40E+38 |
-1 |
The number of days to continue this intervention. |
|
Intervention_Name |
string |
-1 |
1 |
0 |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
|
Property_Restrictions |
Dynamic String Set |
NA |
NA |
[] |
Fraction of individuals in the target demographic that will receive this intervention. |
|
Property_Restrictions_Within_Node |
PropertyRestrictions |
NA |
NA |
Everyone |
Fraction of individuals in the target demographic that will receive this intervention. |
|
Target_Age_Max |
float |
0 |
3.40E+38 |
3.40E+38 |
Upper end of age targeted for intervention, in years. |
|
Target_Age_Min |
float |
0 |
3.40E+38 |
0 |
Lower end of age targeted for intervention, in years. |
|
Target_Demographic |
enum |
NA |
NA |
Everyone |
The demographic group (from a list of possibles) targeted by this intervention (e.g., Infants). |
|
Target_Gender |
enum |
NA |
NA |
All |
Specify the gender restriction for the intervention. Defaults to All. |
|
Target_Residents_Only |
boolean |
0 |
1 |
0 |
If true, only distribute the intervention to those that claim the node as their residence - i.e. started in the node |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Broadcast_Event |
Constrained String |
0 |
1 |
0 |
The event that should occur at the end of the delay period. |
|
Dont_Allow_Duplicates |
boolean |
0 |
1 |
0 |
If an individual’s container has an intervention, set to 1 to prevent them from receiving another copy of the intervention. Supported by all intervention types. |
|
Intervention_Name |
string |
0 |
1 |
0 |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Actual_IndividualIntervention_Configs |
IndividualIntervention |
0 |
3.40E+38 |
6 |
Array of nested interventions to be distributed at end of delay period to covered fraction. |
|
Coverage |
float |
0 |
1 |
1 |
Fraction of individuals receiving delayed distribution of configured interventions. |
|
Delay_Distribution |
enum |
NA |
NA |
NOT_INITIALIZED |
Distribution of duration of delay period. Supported values are: FIXED_DURATION UNIFORM_DURATION GAUSSIAN_DURATION EXPONENTIAL_DURATION. |
|
Delay_Period |
float |
0 |
3.40E+38 |
6 |
If a FIXED_DURATION is specified as the Delay_Distribution, add this parameter Delay_Period to directly specify the time delay (in number of days). If EXPONENTIAL_DURATION is specified as the Delay_Distribution, Delay_Period, represents the exponential rate that describes the distribution of the time delay (in units of 1/days). |
|
Delay_Period_Max |
float |
0.6 |
3.40E+38 |
0 |
If a UNIFORM_DURATION is specified as the Delay_Distribution, add this parameter Delay_Period_Max to directly specify the maximum time delay (in number of days). |
|
Delay_Period_Mean |
float |
0 |
3.40E+38 |
6 |
If a GAUSSIAN_DURATION is specified as the Delay_Distribution, add this parameter Delay_Period_Mean to directly specify the mean time delay (in number of days). |
|
Delay_Period_Min |
float |
0 |
3.40E+38 |
0 |
If a UNIFORM_DURATION is specified as the Delay_Distribution, add this parameter Delay_Period_Min to directly specify the minimum time delay (in number of days). |
|
Delay_Period_Std_Dev |
float |
0 |
3.40E+38 |
1 |
If a GAUSSIAN_DURATION is specified as the Delay_Distribution, add this parameter Delay_Period_Std_Dev to specify the standard deviation describing the Gaussian distribution (in number of days). |
|
Dont_Allow_Duplicates |
boolean |
0 |
1 |
0 |
If an individual’s container has an intervention, set to 1 to prevent them from receiving another copy of the intervention. Supported by all intervention types. |
|
Intervention_Name |
string |
0 |
1 |
0 |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Actual_IndividualIntervention_Config |
IndividualIntervention |
0 |
1 |
1 |
The configuration of an actual intervention sought. Selects a class for the intervention and configures the parameters specific for that intervention class. |
|
Actual_IndividualIntervention_Event |
Constrained String |
1900 |
2200 |
2000 |
The event of an actual intervention sought. Selects a class for the intervention and configures the parameters specific for that intervention class. |
|
Dont_Allow_Duplicates |
boolean |
0 |
1 |
0 |
If an individual’s container has an intervention, set to 1 to prevent them from receiving another copy of the intervention. Supported by all intervention types. |
|
Event_Or_Config |
enum |
NA |
NA |
Config |
Specifies whether the current intervention distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). See event list. |
|
Intervention_Name |
string |
1900 |
2200 |
2000 |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
|
Single_Use |
boolean |
0 |
1 |
1 |
One-time, or persistent? |
|
Tendency |
float |
0 |
1 |
1 |
The probability of seeking healthcare. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Actual_IndividualIntervention_Configs |
IndividualIntervention |
0 |
1 |
0 |
An array of interventions distributed as specified in the calendar. Selects a class for the intervention and configures the parameters specific for that intervention class. |
|
Calendar |
CalendarIV |
0 |
1 |
0 |
An array of ages days and probability of receiving an intervention. |
|
Dont_Allow_Duplicates |
boolean |
0 |
1 |
0 |
If an individual’s container has an intervention, set to 1 to prevent them from receiving another copy of the intervention. Supported by all intervention types. |
|
Dropout |
boolean |
0 |
1 |
0 |
If an intervention in the series is missed, all subsequent interventions are also missed. If false (0), all calendar dates/doses are applied independently of each other. If true (1), a missed dose (by applying the probability) will result in no further doses, that is, a miss means you have dropped out altogether. |
|
Intervention_Name |
string |
0 |
1 |
0 |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Dont_Allow_Duplicates |
boolean |
0 |
1 |
0 |
If an individual’s container has an intervention, set to 1 to prevent them from receiving another copy of the intervention. Supported by all intervention types. |
|
Intervention_List |
IndividualIntervention |
0 |
1 |
0 |
The array of nested JSON parameters for the interventions to be distributed by this intervention. |
|
Intervention_Name |
string |
0 |
1 |
0 |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Actual_IndividualIntervention_Config |
IndividualIntervention |
-1 |
3.40E+38 |
-1 |
The configuration of the actual individual-based intervention sought. Selects a class for the intervention and configures the parameters specific for that intervention class. |
|
Actual_NodeIntervention_Config |
NodeIntervention |
NA |
NA |
[] |
The configuration of the actual node-level intervention sought. Selects a class for the intervention and configures the parameters specific for that intervention class. |
|
Blackout_Event_Trigger |
Constrained String |
0 |
1 |
0 |
The event to broadcast if an intervention cannot be distributed due to the Blackout_Period. |
|
Blackout_Period |
float |
0 |
3.40E+38 |
0 |
After the initial intervention distribution, the time, in days, to wait before distributing the intervention again. If it cannot distribute due to the blackout period, it will broadcast the user-defined Blackout_Event_Trigger. |
|
Demographic_Coverage |
float |
0 |
1 |
1 |
Fraction of individuals in the target demographic that will receive this intervention. |
|
Duration |
float |
-1 |
3.40E+38 |
-1 |
The number of days to continue this intervention. |
|
Intervention_Name |
string |
0 |
1 |
0 |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
|
Property_Restrictions |
Dynamic String Set |
NA |
NA |
[] |
Fraction of individuals in the target demographic that will receive this intervention. |
|
Property_Restrictions_Within_Node |
PropertyRestrictions |
0 |
3.40E+38 |
3.40E+38 |
Fraction of individuals in the target demographic that will receive this intervention. |
|
Target_Age_Max |
float |
0 |
3.40E+38 |
3.40E+38 |
Upper end of age targeted for intervention, in years. |
|
Target_Age_Min |
float |
0 |
3.40E+38 |
0 |
Lower end of age targeted for intervention, in years. |
|
Target_Demographic |
enum |
NA |
NA |
Everyone |
The demographic group (from a list of possibles) targeted by this intervention (e.g., Infants). |
|
Target_Gender |
enum |
NA |
NA |
All |
Specify the gender restriction for the intervention. Defaults to All. |
|
Target_Residents_Only |
boolean |
0 |
1 |
0 |
If true, only distribute the intervention to those that claim the node as their residence - i.e. started in the node |
|
Trigger_Condition |
Constrained String |
NA |
NA |
[] |
The condition for triggering a health seeking intervention. |
|
Trigger_Condition_List |
Vector String |
NA |
NA |
[] |
Included if Trigger_Condition is set to ‘TriggerList’. A list (JSON array) of triggers (strings) drawn from config.json ‘Listed_Events’ or from built-in events. |
|
Trigger_Condition_String |
Constrained String |
0 |
1 |
0 |
Included if Trigger_Condition is set to ‘TriggerString’. Normally Trigger_Condition must specify an event from the built-in list of pre-defined events or triggers from the IndividualEventTriggerType enum. Trigger_Condition_String can be any string provided it is listed in the config.json’s Listed_Events array. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Antigen |
integer |
0 |
10 |
0 |
The antigenic ID of the outbreak infection. |
|
Genome |
integer |
-1 |
16777200 |
0 |
The genetic ID of the outbreak infection. |
|
Import_Age |
float |
0 |
43800 |
365 |
Age (in days) of infected import cases |
|
Incubation_Period_Override |
boolean |
0 |
1 |
0 |
0 = outbreak will bypass incubation, 1 = outbreak infection will start from beginning. |
|
Intervention_Name |
string |
0 |
1 |
0 |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
|
Number_Cases_Per_Node |
integer |
0 |
2147480000 |
1 |
Number of new cases of Outbreak to import (per node). This will increase population. There is no control over demographics of these individuals. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Antigen |
integer |
0 |
10 |
0 |
The antigenic ID of the outbreak infection. |
|
Dont_Allow_Duplicates |
boolean |
0 |
1 |
0 |
If an individual’s container has an intervention, set to 1 to prevent them from receiving another copy of the intervention. Supported by all intervention types. |
|
Genome |
integer |
-1 |
16777200 |
0 |
The genetic ID of the outbreak infection. |
|
Incubation_Period_Override |
boolean |
0 |
1 |
0 |
0 = outbreak will bypass incubation, 1 = outbreak infection will start from beginning. |
|
Intervention_Name |
string |
NA |
NA |
OFF |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Dont_Allow_Duplicates |
boolean |
0 |
1 |
0 |
If an individual’s container has an intervention, set to 1 to prevent them from receiving another copy of the intervention. Supported by all intervention types. |
|
Efficacy |
float |
0 |
1 |
0.5 |
Represents the efficacy of a PMTCT intervention, defined as the rate ratio of MTCT between women receiving the intervention and women not receiving the intervention. A setting of 1 is equivalent to 100% blocking efficacy, and 0 reverts to the default probability of transmission, configured through the config.json parameter Maternal_Transmission_Probability. |
|
Intervention_Name |
string |
0 |
3.40E+38 |
6 |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Daily_Probability |
float |
0 |
1 |
1 |
The probability per day that an individual will move to the Target_Property_Value. |
|
Dont_Allow_Duplicates |
boolean |
0 |
1 |
0 |
If an individual’s container has an intervention, set to 1 to prevent them from receiving another copy of the intervention. Supported by all intervention types. |
|
Intervention_Name |
string |
NA |
NA |
Config |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
|
Maximum_Duration |
float |
-1 |
3.40E+38 |
3.40E+38 |
Maximum duration of ‘delayed-release’ property change, in days. |
|
Revert |
float |
0 |
10000 |
0 |
Reversion rate, or the number of days until reversion, or a 2 if reversion is allowed. |
|
Target_Property_Key |
Constrained String |
0 |
10000 |
0 |
The name of the EMOD-defined property of the group. |
|
Target_Property_Value |
Constrained String |
0 |
10000 |
0 |
The value of the user-defined group where the individuals will be transitioned. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Base_Sensitivity |
float |
0 |
1 |
1 |
The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test. |
|
Base_Specificity |
float |
0 |
1 |
1 |
The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test. |
|
Cost_To_Consumer |
float |
0 |
3.40E+38 |
1 |
The unit ‘cost’ assigned to the intervention. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation. |
|
Days_To_Diagnosis |
float |
0 |
3.40E+38 |
0 |
The number of days from test until diagnosis. |
|
Dont_Allow_Duplicates |
boolean |
0 |
1 |
0 |
If an individual’s container has an intervention, set to 1 to prevent them from receiving another copy of the intervention. Supported by all intervention types. |
|
Event_Or_Config |
enum |
NA |
NA |
Config |
Specifies whether the current intervention distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). See event list. |
|
Intervention_Name |
string |
0 |
1 |
1 |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
|
Positive_Diagnosis_Config |
IndividualIntervention |
0 |
1 |
0 |
The intervention distributed to individuals if they test positive. This is only valid if Event_Or_Config is set to ‘Config’. |
|
Positive_Diagnosis_Event |
Constrained String |
0 |
3.40E+38 |
0 |
The next health care event that occurs for individuals who test negative. This is only valid if Event_Or_Config is set to ‘Event’. |
|
Treatment_Fraction |
float |
0 |
1 |
1 |
The fraction of positive diagnoses that are treated. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Actual_IndividualIntervention_Config |
IndividualIntervention |
0 |
1 |
1 |
The configuration of an actual intervention sought. Selects a class for the intervention and configures the parameters specific for that intervention class. |
|
Actual_IndividualIntervention_Event |
Constrained String |
0 |
999999 |
10 |
The event of an actual intervention sought. Selects a class for the intervention and configures the parameters specific for that intervention class. |
|
Dont_Allow_Duplicates |
boolean |
0 |
1 |
0 |
If an individual’s container has an intervention, set to 1 to prevent them from receiving another copy of the intervention. Supported by all intervention types. |
|
Event_Or_Config |
enum |
NA |
NA |
Config |
Specifies whether the current intervention distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). See event list. |
|
Intervention_Name |
string |
0 |
999999 |
10 |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
|
Single_Use |
boolean |
0 |
1 |
1 |
One-time, or persistent? |
|
Tendency |
float |
0 |
1 |
1 |
The probability of seeking healthcare. |
The following example provides the syntax for configuring a SimpleVaccine campaign.
{
"Events": [
{
"Event_Coordinator_Config": {
"Demographic_Coverage": 0.8,
"Intervention_Config": {
".Reduced_Acquire": 0.9,
"Vaccine_Take": 1,
"Vaccine_Type": "AcquisitionBlocking",
"Cost_To_Consumer": 10.0,
"class": "SimpleVaccine",
"Waning_Config": {
"Initial_Effect": 0.9,
"Box_Duration": 730,
"class": "WaningEffectBox"
}
},
"Target_Demographic": "Everyone",
"class": "StandardInterventionDistributionEventCoordinator"
},
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Start_Day": 1460,
"class": "CampaignEvent"
}
],
"Use_Defaults": 1
}
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Cost_To_Consumer |
float |
0 |
999999 |
10 |
Unit cost per vaccine (unamortized). The unit ‘cost’ assigned to the intervention. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation. |
|
Dont_Allow_Duplicates |
boolean |
0 |
1 |
0 |
If an individual’s container has an intervention, set to 1 to prevent them from receiving another copy of the intervention. Supported by all intervention types. |
|
Intervention_Name |
string |
0 |
1 |
0 |
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. |
|
Vaccine_Take |
float |
0 |
1 |
1 |
This specifies the rate at which delivered vaccines will successfully stimulate an immune response and achieve the desired efficacy. If vaccine_take is set to 0.9, then with a 90 percent chance, the vaccine will start with the specified efficacy, and with a 10 percent chance it will have no efficacy at all. |
|
Vaccine_Type |
enum |
NA |
NA |
Generic |
Type of vaccine to distribute in a vaccine intervention. Possible values are: - Generic - The vaccine can have all of reduced_transmit, reduced_acquire, and reduced_mortality fields and the vaccine will have both effects. - TransmissionBlocking - Specifies the fraction by which the infectivity of the infected and vaccinated Individual is reduced (reduced_transmit). - AcquisitionBlocking - Specifies the fraction by which the force of infection experienced by the vaccinated Individual is reduced (reduced_acqu |
|
Waning_Config |
WaningEffect |
0 |
1 |
1 |
The configuration of drug-killing efficacy and waning. |
Waning effect parameters are used with interventions such as vaccines, drugs, and bednets. It has six different classes. Each class specifies a different waning effect and uses a different combination of the waning effect parameters.
The waning effect parameters are a nested JSON object and can be configured using several different parameters such as Killing_Config, Waning_Config, Blocking_Config, and Mortality_Config. The following example uses Killing_Config. See the specific intervention sections for the supported parameters.
{
"Intervention_Config": {
"class": "Ivermectin",
"Cost_To_Consumer": 1,
"Killing_Config": {
"class": "WaningEffectBox",
"Box_Duration": 3,
"Initial_Effect": 1
}
}
}
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Box_Duration |
float |
0 |
100000 |
100 |
Box duration of effect in days. |
|
Initial_Effect |
float |
0 |
1 |
1 |
Initial strength of effect. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Box_Duration |
float |
0 |
100000 |
100 |
Box duration of effect in days. |
|
Decay_Time_Constant |
float |
0 |
100000 |
100 |
Exponential decay length in days. |
|
Initial_Effect |
float |
0 |
1 |
1 |
Initial strength of effect. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Initial_Effect |
float |
0 |
1 |
1 |
Initial strength of effect. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Decay_Time_Constant |
float |
0 |
100000 |
100 |
Exponential decay length in days. |
|
Initial_Effect |
float |
0 |
1 |
1 |
Initial strength of effect. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Expire_At_Durability_Map_End |
boolean |
0 |
1 |
0 |
Set to 1 to let the intervention expire when the end of the map is reached. |
|
Initial_Effect |
float |
0 |
1 |
1 |
Initial strength of effect. |
Parameter |
Data type |
Minimum |
Maximum |
Default |
Description |
Example |
|---|---|---|---|---|---|---|
Expire_At_Durability_Map_End |
boolean |
0 |
1 |
0 |
Set to 1 to let the intervention expire when the end of the map is reached. |
|
Initial_Effect |
float |
0 |
1 |
1 |
Initial strength of effect. |
Input and output file structure¶
The section describes the file structure used for input data files, each of the built-in output report types, and error logs to help debug issues you may encounter.
Input data file structure¶
The input data files described in this section determine the demographics, migration, climate, and other relatively fixed information about the population within each geographic node. These files are in contrast to the demographic, geographic, and migration parameters in the configuration file that control simulation-wide qualities, such as enabling air migration across all nodes in the simulation.
Generally, you will download and use input data files without modification. For instructions, see Use input data files. However, demographics files can include many user-defined parameter values and will likely require modification. Only the demographics file is required for a simulation.
Each type of input data generally requires both a metadata file that contains provenance information and a binary file that contains the actual data for each node. Some input files included with EMOD were prepared using CIESIN Gridded Population of the World (GPW) population distribution and a corresponding spatial resolution grid (for example, 2.5 arc minutes) to define the initial population and extent of the nodes for country-wide input files. Therefore, the naming convention for this files usually leads with the geographic location, followed by the spatial resolution, and input file type.
IdReference types and NodeID generation¶
All input files include the parameter IdReference in the metadata, which is used to generate the NodeID associated with each node in a simulation. There are currently four IdReference values that indicate the associated algorithm used for generating the NodeID for each node in a simulation. EMOD uses these values to compare different input data files in a simulation in order to match NodeID values. However, there is no reason you cannot assign any string you want to IdReference, provided all the input data files used in a simulation, such as demographics, climate, or migration, have the same IDReference value.
Generally, nodes are defined using a geographic grid laid over the world, forming approximately square nodes of a certain size. The NodeID is then calculated based on latitude and longitude of the node, where the location of the node is considered the upper left corner of the square it represents. NodeID values are numbered from south to north for latitude and west to east for longitude, with 0,0 being the intersection of the International Date Line and the South Pole. Note that NodeID values are <longitude><latitude> values (not <latitude><longitude> values as normally provided).
The three possible values for IdReference that use a grid to define and identify nodes differ based on grid resolution. EMOD is limited to a minimum node size of 30 arc-seconds (approximately 1 km at the equator). The three gridded values are:
Gridded world grump30arcsec
Gridded world grump2.5arcmin
Gridded world grump1degree
The algorithm for encoding latitude and longitude into a NodeID is as follows:
unsigned int xpix = math.floor((lon + 180.0) / resolution)
unsigned int ypix = math.floor((lat + 90.0) / resolution)
unsigned int **NodeID** = (xpix << 16) + ypix + 1
This generates a NodeID that is a 4-byte unsigned integer (like all NodeID values); the first two bytes represent the longitude of the node and the second two bytes represent the latitude. Note that as part of the final calculation, we add one to the NodeID. This is to reserve the NodeID of zero, since that is used as a null-value in a number of places (for example, in the migration files to signal that no migration value is present).
In addition to these gridded values, you can assign a value of “Legacy” to indicate that NodeID values are defined in and copied directly from the demographics files. This is used when the nodes are not demarcated by a grid, but rather by some social construct, such as voting precincts or other administrative boundary, that don’t necessarily have an obvious heuristic for enumeration. Some types of data may only be available or easier to obtain when in such a form. The name “Legacy” does not imply anything derogatory or time-related. It is simply a term that was chosen to represent data that isn’t related to the gridded information.
When using nodes that are not using the gridded format, you cannot assume or easily determine resolution, shape, or actual location of the node point within/along that shape. In other words, the format of such files depends on the creator of the file and you should refer to any information provided in the metadata of the file or by the creator when parsing the file.
Climate file structure¶
There are two general types of climate files usable by EMOD, namely, climate files generated through actual data, referred to as “climate by data,” and climate files generated from the Koppen classification system, referred to as “climate by Koppen”. Climate data (both types) is contained in a set of two files, a metadata file with header information (<name>.bin.json) and a binary data file (<name>.bin). Both files are required.
The metadata file is a JSON-formatted file that includes a metadata section and a node offsets section. The Metadata parameter contains a JSON object with parameters, some of which are strictly informational and some of which are used by Eradication.exe. However, the informational ones may still be important to understand the provenance and meaning of the data.
In a second section, the NodeOffsets parameter contains a list of hex-encoded 16-byte values used to find the data for each given node (the NodeID).They are not 16-byte offsets, but instead, two 8-byte hex-encoded character strings. This encoding includes the source NodeID. You can map the binary data to its corresponding source NodeID by using the NodeOffset information.
The binary file contains the climate data in a sequential stream. In other words, it presents all the data for the first node, then all the data for the second node, all the way through to the last node.
To use the climate files, you must set Climate_Model to either “CLIMATE_BY_DATA” or “CLIMATE_BY_KOPPEN”, as appropriate, in the configuration file. There are also additional parameters in the configuration file you can use to scale or otherwise modify the data included in the climate files.
At this time, the EMOD executable (Eradication.exe) reads land temperature data, but does not use the data in any calculations. IDM clones the air temperature and uses that as the land temperature in the climate data files. If you are going to be constructing your own climate files, we advise you to do the same.
The following parameters in the metadata section are informational:
Parameter |
Data type |
Description |
|---|---|---|
DateCreated |
string |
The day the file was created. |
Author |
string |
The author of the file. |
OriginalDataYears |
string |
The years from which the original data was derived. |
StartDayOfYear |
string |
The day of the year representing the first day in the climate file. |
DataProvenance |
string |
The source of the data. |
The following parameters in the metadata section are used by Eradication.exe:
Parameter |
Data type |
Description |
|---|---|---|
IdReference |
string |
A unique, user-selected string that indicates the method used for generating NodeID values in the input file. For more information, see Input data file structure. |
NodeCount |
integer |
The number of nodes to expect in this file. |
DatavalueCount |
integer |
The number of data values per node. The number must be the same across every node in the binary file. |
UpdateResolution |
enum |
The time resolution of the climate file. Available values are:
|
An example of climate by data metadata is as follows:
{
"Metadata": {
"DateCreated": "Sun Sep 25 19:02:09 2011",
"Tool": "createclimateheader.py",
"Author": "authorName",
"IdReference": "Gridded world grump2.5arcmin",
"NodeCount": 1,
"DatavalueCount": 3650,
"UpdateResolution": "CLIMATE_UPDATE_DAY",
"OriginalDataYears": "1990-1993",
"StartDayOfYear": "January 1",
"DataProvenance": "47 consecutive months of data were used to generate one average year of data that is repeated for 10 years"
},
"NodeOffsets": "144B07A400000000"
}
The binary file is a stream of 4-byte floating point values that contain the data value at the data count position for a given node, running from 1 to the maximum data count value.
The binary format is as follows:
The Koppen classification system is one of the most widely used climate classification systems. The Koppen classification system makes the assumption that native vegetation is the best expression of climate.
The following parameters in the metadata section are informational:
Parameter |
Data type |
Description |
|---|---|---|
DateCreated |
string |
The day the file was created. |
Author |
string |
The author of the file. |
DataProvenance |
string |
The source of the data. |
Tool |
string |
The script used to create the file. |
The following parameters in the metadata section are used by Eradication.exe:
Parameter |
Data type |
Description |
|---|---|---|
IdReference |
string |
A unique, user-selected string that indicates the method used for generating NodeID values in the input file. For more information, see Input data file structure. |
NodeCount |
integer |
The number of nodes to expect in this file. |
An example of climate by Koppen metadata is as follows:
{
"Metadata": {
"DateCreated": "Sun Sep 25 19:08:52 2011",
"Tool": "createclimateheader.py",
"Author": "authorName",
"IdReference": "Gridded world grump2.5arcmin",
"NodeCount": 2,
"DataProvenance": "Köppen-Geiger Classification System from http://koeppen-geiger.vu-wien.ac.at/"
},
"NodeOffsets": "157D075200000000157E07520000000"
}
The binary file parameters use the naming convention below to store the data.
Parameter |
Data type |
Description |
|---|---|---|
KoppenIndexX |
integer, 4 bytes |
The Koppen Index value, with X running from 1 to the maximum number of nodes. |
The binary format is as follows:
Migration file structure¶
There are four types of migration files that can be used by EMOD, namely, local migration, regional migration, air migration and sea migration. For all types, migration data is contained in a set of two files, a metadata file with header information and a binary data file. Both files are required. The structure of each of these files is nearly the same for all migration types, with the only exception being the number of columns in the binary file.
The metadata file is a JSON-formatted file that includes a metadata section and a node offsets section. The Metadata parameter contains a JSON object with parameters, some of which are strictly informational and some of which are used by Eradication.exe. However, the informational ones may still be important to understand the provenance and meaning of the data.
The following parameters in the metadata section are informational:
Parameter |
Data type |
Description |
|---|---|---|
DateCreated |
string |
The day the file was created. |
Author |
string |
The author of the file. |
Tool |
string |
The script used to create the file. |
The following parameters in the metadata section are used by Eradication.exe:
Parameter |
Data type |
Description |
|---|---|---|
IdReference |
string |
A unique, user-selected string that indicates the method used for generating NodeID values in the input file. For more information, see Input data file structure. |
NodeCount |
integer |
The number of nodes to expect in this file. |
DatavalueCount |
integer |
The number of data values per node. The number must be the same across every node in the binary file. |
In a second section, the NodeOffsets parameter contains a list of hex-encoded 16-byte values used to find the data for each given node (the NodeID).They are not 16-byte offsets, but instead, two 8-byte hex-encoded character strings. This encoding includes the source NodeID. You can map the binary data to its corresponding source NodeID by using the NodeOffset information.
The binary file contains the migration rate data in a sequential stream. In other words, it presents all the data for the first node, then all the data for the second node, all the way through to the last node. The data is laid out in rows and columns, with each row corresponding to a node and the number of columns varying based on the migration type.
The following diagram shows how migration data is laid out in rows, with each row corresponding to a source node and each column corresponding to the destination node.
Migration rate is that fraction of the node’s population that is migrating per day. Units are per person per day, meaning the number of people migrating per day divided by the total population of the node. For example, if a node had 1,000 people and a migration rate of .01, there would be .01 * 1,000 = 10 people migrating per day, but if the node had 10,000 people in the node and a migration rate of .01, it would .01 * 10,000 = 100 people migrating per day. You can adjust this rate using configuration parameters for scaling (these begin with x).
The binary file contains a stream of 4-byte unsigned integers that identify the destination node, followed by a stream of 8-byte double floating point values that contain the rate associated with the destination node (per person per day), running from 1 to the total number of nodes.
To use the migration files, you must set Migration_Model in the configuration file to a valid migration type except “NO_MIGRATION”. Each migration types also requires you to set another parameter to enable the particular type of migration selected. There are also additional parameters in the configuration file you can use to scale or otherwise modify the data included in the climate files.
Local migration describes the foot travel movement of people into and out of adjacent nodes. A local migration file is required for simulations that support more than one node. You must also set the Enable_Local_Migration parameter in the configuration file to 1. For each location, the local migration file represents up to eight adjacent destination nodes, with 0 used as the value for unused nodes.
The following diagram shows the format for the local migration binary file data:
Regional migration describes migration that occurs on a road or rail network for a simulation. If a node is not part of the network, the regional migration of individuals to and from that node considers the closest road hub city. A Voronoi tiling based on road hubs is constructed of the region, with each non-hub connected to the hub of its tile. These connections are created when the migration file is constructed. They are not performed at runtime.
A regional migration file is required for simulations that cover a geography that is large enough that road/rail migration is relevant. You must also set the Enable_Regional_Migration parameter in the configuration file to 1. For each location, the regional migration file represents up to 30 adjacent destination nodes, with 0 used as the value for unused nodes.
The following diagram shows the format for the regional migration binary file data:
Air migration describes migration that occurs by airplane travel. An air migration file is usually required for simulations of an entire country or larger geographies. You must also set the Enable_Air_Migration parameter in the configuration file to 1. For each location, the air migration file represents up to 60 adjacent destination nodes, with 0 used as the value for unused nodes.
The following diagram shows the format for the air migration binary file data:
Sea migration describes migration that occurs by ship travel. Unlike the other migration files, the sea migration file only contains information for the nodes that are seaports. A sea migration file does not contain every node like local, regional or air migration files do. You must also set the Enable_Sea_Migration parameter in the configuration file to 1. For each location, the sea migration file represents up to five adjacent destination nodes, with 0 used as the value for unused nodes.
The following diagram shows the format for the sea migration binary file data:
Load-balancing file structure¶
If you are running a large simulation with multiple nodes, you may want to use a load balancing file to distribute the computing load among multiple cores. This can be especially helpful if the nodes vary considerably in size and, therefore, processing time. If no load balancing file is submitted, the Eradication.exe allocates simulation nodes to cores according to a checkerboard pattern.
For each simulation, the load balancing file contains information about the relative level of processing time required for each geographical node. The Eradication.exe can then allocate nodes to processors in such a way that the total processing required is evenly distributed across all processors.
To use a load balancing file, you must set Load_Balance_Filename to the path to the load balancing file, relative to the input file directory. Load-balancing files can be JavaScript Object Notation (JSON) files, which are preferred, or binary files.
A JSON load-balancing file contains the Load_Balance_Scheme_Nodes_On_Core_Matrix parameter, assigned an array of arrays, each of which represents a core and lists the NodeID of each node to be processed on that core. If any node contained in the demographics file is not listed in the load-balancing file, it will be processed on the first core.
For example, the load-balancing file shown below distributes the processing for 100 nodes across 4 cores, assigning more nodes to particular cores when those nodes require less processing time.
{
"Load_Balance_Scheme_Nodes_On_Core_Matrix": [
[1, 2, 3, 4, 5, 11, 12, 13, 14, 15, 21, 22, 23, 24, 25, 31, 32, 33, 34, 35, 45],
[6, 7, 8, 9, 10, 16, 17, 18, 19, 20, 26, 27, 28, 29, 30, 36, 37, 38, 39, 40, 46, 47, 48, 49, 50, 56, 57, 58, 59, 60, 67, 68, 69, 70],
[61, 62, 63, 64, 65, 66, 71, 72, 73, 74, 75, 76, 77, 81, 82, 83, 84, 85, 86, 87, 91, 92, 93, 94, 95, 96, 97],
[41, 42, 43, 44, 51, 52, 53, 54, 55, 78, 79, 80, 88, 89, 90, 98, 99, 100]
]
}
A binary load-balancing file starts with an initial unsigned 4-byte integer that indicates the number of nodes. Following that value is a series of 4-byte unsigned integers representing the NodeID values. The number of values will be equal to the previously read number of nodes. Following that, another series of 4-byte floating point values, with each value representing the relative processing time required for each geographic node. Again, the number of values will be equal to the previously read number of nodes. The series of values are set up such that the \(i^{th}\) entry in the series is equal to the cumulative proportion of the processing load for all the previous nodes 0 through \(i\).
The cumulative nature of each node’s value does not mean each node is assigned that amount for its processing load. Rather, it is a way to make the internal calculations more efficient. For example, if you had ten nodes and each node was assigned 10% of the load, the values assigned from node0 to node9 would be the following: 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9 and 1.0.
The following diagram shows the format for the binary load-balancing file data:
Output report structure¶
This topic defines various data output reports that the EMOD executable (Eradication.exe) can produce. These reports are built in to the Eradication.exe and are either always output with each simulation, such as inset chart, or reports that you can configure to be included with the output. All output reports can be found in the output directory of the working directory, for example, 1_Generic_Seattle_MultiNodeoutput.
If the available output reports do not meet your needs, you can use custom reporters that are EMODules separate from the Eradication.exe code. There are several provided in the EMOD GitHub repository or you can even write your own custom reporter to post- process and format data as you desire into a new output report. For more information, see Custom reporters.
Inset chart output report¶
The inset chart output report is output with every simulation. It is a JSON-formatted file with the channel output results of the simulation, consisting of simulation-wide averages by time step. The channels in an inset chart are fully specified by the simulation type and cannot be altered without making changes to the EMOD source code. The file name is InsetChart.json. You can use the information contained in the file to create a chart, but EMOD does not automatically output a chart.
The file contains a header and a channels section.
Header¶
The header section contains the following parameters.
Parameter |
Data type |
Description |
|---|---|---|
DateTime |
string |
The time stamp indicating when the report was generated. |
DTK_Version |
string |
The version of EMOD used. |
Report_Type |
string |
The type of output report. |
Report_Version |
string |
The format version of the report. |
Start_Time |
integer |
The time noted in days when the simulation begins. |
Simulation_Timestep |
integer |
The number of days in each time step. |
Timesteps |
integer |
The number of time steps in this simulation. |
Channels |
integer |
The number of channels in the simulation. |
Channels¶
The channels section contains the following parameters.
Parameter |
Data type |
Description |
|---|---|---|
<Channel_Title> |
string |
The title of the particular channel. |
Units |
string |
The units used for this channel. |
Data |
array |
A list of the channel data at each time step. |
Example¶
The following is a sample of an InsetChart.json file.
{
"Header": {
"DateTime": "Thu Dec 03 11:28:34 2015",
"DTK_Version": "5738 HIV-Ongoing 2015/11/18 13:00:39",
"Report_Type": "InsetChart",
"Report_Version": "3.2",
"Start_Time": 0,
"Simulation_Timestep": 1,
"Timesteps": 5,
"Channels": 17
},
"Channels": {
"Births": {
"Units": "Births",
"Data": [
0,
0,
0,
0,
0
]
},
"Campaign Cost": {
"Units": "USD",
"Data": [
0,
0,
0,
0,
0
]
},
"Cumulative Infections": {
"Units": "",
"Data": [
0,
0,
0,
0,
0
]
},
"Cumulative Reported Infections": {
"Units": "",
"Data": [
0,
0,
0,
0,
0
]
},
"Disease Deaths": {
"Units": "",
"Data": [
0,
0,
0,
0,
0
]
},
"Exposed Population": {
"Units": "Exposed Fraction",
"Data": [
0,
0,
0,
0,
0
]
},
"Human Infectious Reservoir": {
"Units": "Total Infectivity",
"Data": [
0,
0,
0,
0,
0
]
},
"Infected": {
"Units": "Infected Fraction",
"Data": [
0,
0,
0,
0,
0
]
},
"Infectious Population": {
"Units": "Infectious Fraction",
"Data": [
0,
0,
0,
0,
0
]
},
"Log Prevalence": {
"Units": "Log Prevalence",
"Data": [-10, -10, -10, -10, -10]
},
"New Infections": {
"Units": "",
"Data": [
0,
0,
0,
0,
0
]
},
"New Reported Infections": {
"Units": "",
"Data": [
0,
0,
0,
0,
0
]
},
"Daily (Human) Infection Rate": {
"Units": "Infection Rate",
"Data": [
0,
0,
0,
0,
0
]
},
"Recovered Population": {
"Units": "Recovered (Immune) Fraction",
"Data": [
0,
0,
0,
0,
0
]
},
"Statistical Population": {
"Units": "Population",
"Data": [
900,
900,
900,
900,
900
]
},
"Susceptible Population": {
"Units": "Susceptible Fraction",
"Data": [
1,
1,
1,
1,
1
]
},
"Waning Population": {
"Units": "Waning Immunity Fraction",
"Data": [
0,
0,
0,
0,
0
]
}
}
}
Binned output report¶
The binned output report is a JSON-formatted file where the channel data has been sorted into bins. It is very similar to an inset chart. However, with the binned report, channels are broken down into sub-channels (bins) based on various criteria. For example, instead of having a single prevalence channel, you might have prevalence in the “0-3 years old bin” and the “4-6 years old bin, and so forth. The file name is BinnedReport.json.
To generate the binned report, set the Enable_Demographics_Reporting configuration parameter to 1. The demographics summary output report will also be generated.
The file contains a header and a channels section.
Header¶
The header section contains the following parameters.
Parameter |
Data type |
Description |
|||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
DateTime |
string |
The time stamp indicating when the report was generated. |
|||||||||||||||
DTK_Version |
string |
The version of EMOD used. |
|||||||||||||||
Report_Type |
string |
The type of output report. |
|||||||||||||||
Report_Version |
string |
The format version of the report. |
|||||||||||||||
Timesteps |
integer |
The number of time steps in this simulation. |
|||||||||||||||
Channels |
integer |
The number of channels in the simulation. |
|||||||||||||||
Subchannel_Metadata |
nested JSON object |
Metadata that describes the bins and axis information. The metadata includes the following parameters:
|
Channels¶
The channels section contains the following parameters.
Parameter |
Data type |
Description |
|---|---|---|
<Channel_Title> |
string |
The title of the particular channel. |
Units |
string |
The units used for this channel. |
Data |
array |
A list of the channel data at each time step. |
Example¶
The following is a sample of an BinnedReport.json file.
{
"Header": {
"DateTime": "Wed Oct 01 14:49:22 2014",
"DTK_Version": "4284 trunk 2014/09/23 11:50:52",
"Report_Version": "2.1",
"Timesteps": 150,
"Subchannel_Metadata": {
"AxisLabels": [
["Age"]
],
"NumBinsPerAxis": [
[21]
],
"ValuesPerAxis": [
[
[1825, 3650, 5475, 7300, 9125, 10950, 12775, 14600, 16425, 18250, 20075, 21900, 23725, 25550, 27375, 29200, 31025, 32850, 34675, 36500, 999999]
]
],
"MeaningPerAxis": [
[
["<5", "5-9", "10-14", "15-19", "20-24", "25-29", "30-34", "35-39", "40-44", "45-49", "50-54", "55-59", "60-64", "65-69", "70-74", "75-79", "80-84", "85-89", "90-94", "95-99", ">100"]
]
]
},
"Channels": 4
},
"Channels": {
"Disease Deaths": {
"Units": "",
"Data": [
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
]
},
"Infected": {
"Units": "",
"Data": [
[0, 2, 1, 1, 1, 1, 2, 6, 7, 5, 3, 5, 4, 3, 2, 3, 5, 6, 14, 21, 22, 22, 31, 52, 63, 101, 108, 119, 121, 139, 132, 133, 130, 115, 97, 95, 93, 98, 102, 108, 105, 110, 98, 90, 93, 94, 92, 81, 62, 57, 63, 56, 58, 61, 67, 64, 52, 54, 45, 33, 34, 36, 27, 32, 29, 21, 17, 7, 13, 15, 17, 13, 14, 11, 14, 15, 11, 12, 7, 6, 6, 3, 3, 3, 4, 4, 3, 3, 2, 2, 3, 3, 4, 2, 2, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 3, 4, 2, 2, 2, 1, 5, 5, 7, 7, 6, 13, 14, 12, 8, 8, 15, 15, 23, 39, 43, 61, 82, 110, 133, 142, 133, 113, 105, 105, 100, 86, 81, 81, 75, 73, 68, 74, 74, 73, 70, 75, 67, 63, 72, 61, 63, 60, 55, 52, 47, 44, 36, 39, 36, 39, 36, 28, 27, 22, 20, 17, 20, 22, 17, 13, 13, 10, 10, 6, 7, 7, 3, 4, 5, 5, 4, 2, 1, 2, 2, 2, 3, 2, 2, 4, 2, 1, 2, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 1, 1, 2, 3, 3, 4, 3, 3, 3, 2, 2, 3, 5, 5, 7, 7, 12, 15, 21, 24, 22, 23, 33, 36, 42, 58, 93, 95, 104, 105, 102, 83, 75, 72, 67, 66, 63, 68, 61, 61, 63, 62, 60, 67, 67, 55, 52, 55, 42, 43, 40, 43, 36, 37, 30, 33, 33, 29, 23, 20, 15, 15, 17, 16, 14, 13, 13, 12, 15, 13, 11, 7, 13, 12, 11, 10, 9, 6, 5, 7, 4, 7, 4, 2, 2, 2, 1, 0, 0, 0, 1, 0, 1, 2, 2, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 1, 0, 0, 0, 0, 0, 1, 2, 3, 4, 2, 3, 2, 4, 6, 7, 10, 12, 13, 14, 16, 18, 27, 31, 50, 50, 48, 58, 68, 86, 81, 82, 76, 67, 58, 58, 59, 63, 57, 47, 40, 48, 43, 46, 45, 46, 46, 44, 40, 39, 40, 40, 37, 39, 36, 29, 26, 20, 22, 23, 20, 15, 13, 16, 16, 14, 12, 10, 7, 9, 8, 6, 6, 5, 3, 3, 3, 2, 1, 1, 1, 1, 1, 2, 3, 3, 2, 2, 1, 1, 0, 1, 2, 3, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 2, 1, 2, 2, 2, 2, 4, 5, 4, 5, 4, 2, 4, 9, 11, 12, 16, 15, 20, 22, 28, 40, 44, 44, 48, 54, 54, 50, 53, 52, 51, 48, 47, 43, 44, 40, 40, 43, 36, 34, 30, 34, 32, 29, 26, 27, 24, 16, 22, 21, 18, 18, 17, 17, 15, 12, 14, 9, 12, 5, 6, 3, 6, 7, 6, 8, 9, 8, 7, 7, 6, 5, 4, 3, 5, 5, 4, 3, 3, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 1, 1, 1, 2, 2, 2, 1, 1, 1, 0, 0, 1, 2, 3, 1, 2, 2, 7, 7, 9, 10, 10, 19, 22, 34, 44, 42, 45, 62, 63, 48, 48, 48, 46, 42, 37, 33, 33, 33, 35, 34, 37, 34, 33, 30, 28, 32, 33, 24, 27, 27, 23, 25, 18, 12, 13, 12, 12, 11, 9, 5, 6, 7, 8, 10, 7, 7, 5, 6, 5, 5, 5, 4, 6, 5, 2, 3, 5, 4, 4, 1, 1, 1, 2, 2, 2, 2, 2, 1, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 1, 2, 3, 2, 5, 11, 16, 20, 25, 25, 26, 36, 53, 49, 48, 51, 54, 47, 44, 35, 30, 21, 20, 22, 24, 26, 28, 22, 16, 19, 31, 26, 30, 25, 30, 26, 19, 22, 21, 18, 21, 23, 15, 11, 11, 11, 9, 6, 4, 2, 4, 4, 3, 2, 2, 4, 3, 3, 4, 3, 2, 1, 1, 0, 0, 3, 3, 2, 4, 3, 2, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 2, 1, 3, 2, 1, 1, 2, 3, 10, 13, 12, 12, 17, 26, 24, 23, 25, 30, 33, 28, 35, 34, 27, 22, 22, 21, 22, 19, 18, 16, 13, 17, 13, 14, 11, 14, 11, 11, 10, 12, 14, 13, 13, 15, 12, 9, 7, 6, 5, 5, 5, 6, 6, 7, 8, 6, 6, 5, 4, 4, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 2, 3, 3, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 2, 2, 1, 1, 2, 2, 0, 0, 0, 0, 2, 3, 5, 7, 5, 4, 10, 8, 10, 11, 18, 18, 21, 27, 27, 26, 24, 20, 24, 24, 21, 20, 21, 20, 19, 21, 18, 21, 13, 12, 14, 15, 13, 12, 14, 15, 13, 9, 8, 7, 6, 4, 8, 6, 4, 3, 4, 5, 5, 3, 1, 1, 1, 1, 0, 1, 1, 1, 3, 2, 3, 2, 1, 2, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 2, 2, 2, 3, 5, 7, 7, 9, 13, 13, 16, 20, 18, 22, 26, 26, 23, 23, 24, 20, 13, 7, 7, 11, 9, 12, 13, 16, 19, 20, 14, 11, 12, 11, 10, 11, 8, 6, 6, 4, 4, 2, 6, 6, 4, 4, 3, 3, 3, 6, 6, 6, 4, 4, 3, 4, 2, 3, 5, 3, 4, 2, 2, 4, 4, 5, 3, 3, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 1, 1, 0, 0, 1, 2, 0, 0, 0, 1, 1, 2, 2, 2, 2, 1, 0, 1, 2, 3, 3, 5, 5, 4, 6, 15, 16, 18, 22, 22, 22, 23, 12, 8, 5, 6, 4, 5, 6, 9, 10, 11, 13, 17, 14, 11, 13, 13, 9, 7, 6, 11, 9, 7, 4, 4, 3, 2, 2, 3, 1, 4, 3, 2, 1, 2, 4, 2, 2, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 1, 1, 1, 3, 2, 3, 2, 2, 4, 3, 8, 11, 10, 12, 10, 6, 6, 12, 9, 5, 6, 6, 9, 8, 6, 8, 7, 8, 12, 11, 11, 7, 14, 13, 12, 11, 12, 6, 8, 10, 12, 8, 4, 4, 2, 3, 3, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 2, 1, 0, 0, 0, 1, 2, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 0, 1, 3, 4, 6, 9, 9, 11, 12, 12, 11, 12, 12, 9, 9, 6, 7, 8, 10, 10, 11, 4, 8, 7, 10, 9, 9, 10, 8, 6, 4, 3, 2, 2, 3, 3, 5, 7, 4, 4, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 2, 2, 2, 4, 4, 4, 4, 6, 4, 8, 9, 7, 6, 7, 6, 6, 5, 5, 4, 2, 4, 4, 4, 4, 4, 6, 5, 3, 2, 3, 4, 2, 1, 2, 4, 6, 6, 6, 5, 2, 3, 4, 2, 1, 3, 3, 3, 3, 2, 2, 0, 0, 0, 0, 0, 1, 1, 2, 2, 2, 2, 1, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 2, 1, 2, 2, 4, 5, 10, 9, 10, 10, 10, 8, 10, 9, 9, 8, 7, 7, 4, 5, 5, 6, 4, 3, 4, 2, 4, 4, 4, 5, 4, 2, 3, 2, 4, 2, 2, 2, 0, 0, 1, 2, 1, 1, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 2, 2, 1, 2, 2, 1, 1, 2, 3, 4, 3, 4, 6, 6, 3, 4, 2, 1, 2, 3, 3, 4, 2, 2, 4, 6, 4, 3, 2, 2, 2, 3, 4, 5, 4, 5, 4, 4, 3, 5, 5, 4, 4, 3, 3, 3, 2, 3, 3, 3, 3, 3, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 1, 3, 6, 8, 8, 5, 5, 5, 6, 3, 4, 4, 5, 6, 6, 6, 4, 2, 2, 2, 2, 4, 2, 3, 3, 5, 6, 6, 6, 4, 3, 2, 2, 0, 2, 1, 1, 0, 0, 0, 0, 2, 2, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 4, 6, 7, 7, 7, 6, 5, 5, 4, 4, 4, 1, 1, 1, 1, 2, 1, 1, 0, 0, 1, 2, 1, 2, 3, 2, 1, 2, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 2, 1, 1, 1, 2, 5, 4, 5, 3, 3, 1, 1, 1, 1, 1, 0, 1, 1, 0, 0, 2, 2, 1, 2, 2, 2, 3, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 2, 2, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 3, 3, 4, 3, 4, 4, 5, 5, 3, 1, 1, 1, 1, 3, 2, 2, 2, 1, 1, 2, 2, 2, 2, 2, 2, 1, 2, 2, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 0, 1, 2, 2, 2, 3, 9, 9, 10, 15, 12, 8, 8, 11, 12, 12, 9, 6, 5, 9, 8, 10, 11, 11, 7, 5, 4, 5, 5, 5, 3, 0, 1, 3, 6, 7, 4, 4, 2, 1, 1, 2, 2, 2, 1, 1, 0, 1, 1, 1, 2, 2, 2, 2, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
]
},
"New Infections": {
"Units": "",
"Data": [
[0, 2, 0, 0, 0, 0, 1, 4, 1, 0, 0, 3, 1, 1, 1, 2, 3, 1, 11, 14, 5, 9, 15, 30, 28, 50, 34, 47, 42, 48, 46, 36, 37, 17, 25, 33, 22, 31, 33, 37, 28, 36, 21, 21, 27, 26, 28, 15, 14, 20, 21, 15, 17, 19, 23, 17, 7, 15, 10, 10, 7, 14, 2, 13, 10, 1, 2, 0, 8, 4, 6, 1, 4, 3, 4, 4, 1, 3, 2, 1, 3, 0, 1, 1, 1, 1, 0, 1, 1, 0, 2, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 3, 1, 0, 0, 1, 0, 5, 0, 3, 1, 2, 7, 6, 4, 3, 2, 11, 9, 15, 19, 16, 30, 34, 46, 51, 49, 39, 27, 32, 37, 22, 23, 19, 25, 17, 28, 15, 25, 28, 25, 22, 24, 17, 15, 25, 13, 24, 17, 14, 17, 12, 14, 11, 19, 9, 11, 10, 5, 8, 5, 6, 3, 6, 5, 4, 2, 6, 1, 2, 1, 2, 2, 0, 2, 2, 2, 1, 0, 1, 1, 0, 1, 1, 0, 1, 2, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 0, 3, 1, 5, 6, 8, 6, 9, 7, 19, 12, 19, 30, 46, 25, 35, 35, 33, 21, 23, 19, 20, 12, 21, 19, 15, 19, 16, 14, 20, 17, 17, 6, 15, 14, 14, 14, 12, 11, 7, 10, 6, 9, 8, 7, 3, 4, 3, 5, 5, 4, 6, 7, 3, 3, 6, 2, 2, 2, 7, 0, 2, 2, 2, 2, 1, 2, 0, 4, 0, 0, 2, 0, 0, 0, 0, 0, 1, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 1, 0, 0, 0, 0, 0, 1, 1, 2, 1, 0, 1, 1, 2, 2, 2, 4, 3, 5, 4, 5, 8, 13, 10, 23, 18, 19, 23, 26, 32, 26, 21, 15, 9, 16, 17, 17, 16, 17, 13, 9, 19, 10, 15, 11, 15, 12, 13, 10, 16, 13, 9, 13, 13, 4, 6, 7, 6, 8, 2, 4, 2, 5, 5, 4, 3, 5, 3, 1, 5, 0, 0, 2, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 1, 2, 1, 0, 1, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 2, 0, 1, 1, 0, 0, 2, 1, 1, 2, 0, 0, 2, 6, 2, 4, 6, 6, 6, 10, 12, 20, 16, 15, 20, 16, 18, 14, 15, 14, 12, 13, 12, 9, 13, 10, 13, 11, 9, 9, 6, 15, 9, 9, 7, 8, 7, 6, 8, 6, 6, 3, 5, 5, 4, 4, 4, 0, 4, 0, 3, 0, 3, 2, 1, 3, 4, 0, 0, 3, 1, 2, 1, 1, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 0, 1, 1, 5, 2, 2, 3, 5, 10, 9, 17, 15, 14, 14, 26, 20, 11, 14, 10, 14, 10, 8, 11, 9, 12, 13, 7, 12, 11, 9, 11, 8, 12, 7, 7, 9, 6, 6, 5, 2, 4, 3, 3, 7, 2, 0, 2, 2, 3, 4, 3, 0, 1, 0, 1, 1, 2, 2, 0, 3, 1, 1, 1, 2, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 1, 1, 3, 6, 6, 6, 6, 9, 12, 17, 25, 14, 14, 17, 12, 8, 12, 10, 9, 2, 8, 5, 11, 9, 7, 4, 2, 11, 15, 4, 11, 4, 9, 6, 3, 12, 4, 2, 6, 6, 3, 2, 4, 2, 1, 1, 0, 0, 3, 0, 0, 0, 0, 2, 1, 1, 1, 0, 0, 1, 0, 0, 0, 3, 0, 0, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 2, 0, 0, 0, 1, 1, 8, 3, 2, 5, 7, 13, 6, 9, 8, 10, 10, 4, 13, 8, 8, 5, 6, 9, 6, 5, 5, 4, 5, 7, 2, 6, 3, 7, 2, 5, 2, 5, 5, 5, 4, 5, 2, 1, 2, 1, 2, 1, 1, 1, 1, 2, 3, 0, 1, 2, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 2, 0, 0, 0, 1, 0, 0, 0, 0, 0, 2, 2, 2, 2, 1, 1, 7, 0, 5, 3, 10, 6, 8, 12, 3, 10, 5, 6, 10, 8, 4, 4, 5, 6, 2, 4, 3, 7, 2, 1, 6, 5, 5, 4, 6, 3, 3, 3, 3, 1, 1, 1, 4, 1, 1, 1, 2, 1, 0, 0, 0, 1, 0, 0, 0, 1, 1, 0, 2, 0, 2, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 1, 1, 2, 3, 3, 2, 4, 4, 6, 7, 8, 10, 8, 6, 7, 4, 4, 1, 3, 0, 7, 4, 5, 6, 5, 4, 6, 7, 3, 4, 4, 2, 2, 3, 0, 1, 1, 0, 2, 0, 4, 2, 1, 0, 1, 1, 1, 3, 0, 1, 1, 0, 1, 1, 0, 1, 2, 0, 2, 0, 1, 2, 1, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 1, 0, 0, 0, 1, 1, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 0, 1, 1, 2, 1, 2, 1, 3, 4, 9, 5, 7, 7, 3, 6, 5, 1, 1, 2, 2, 2, 2, 2, 3, 3, 4, 5, 7, 0, 2, 4, 2, 0, 1, 1, 7, 1, 1, 1, 2, 0, 0, 1, 1, 0, 3, 0, 0, 0, 1, 2, 1, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 1, 0, 1, 2, 0, 1, 1, 0, 3, 2, 5, 4, 3, 5, 2, 2, 4, 6, 1, 1, 1, 2, 3, 3, 1, 3, 1, 3, 5, 4, 3, 1, 8, 1, 4, 1, 3, 0, 4, 3, 3, 3, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 2, 1, 2, 5, 3, 6, 3, 4, 4, 5, 3, 2, 2, 1, 2, 2, 4, 2, 4, 0, 5, 4, 4, 1, 3, 4, 1, 1, 0, 0, 0, 1, 2, 1, 2, 3, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 1, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 3, 0, 2, 0, 4, 1, 6, 1, 1, 1, 3, 1, 1, 2, 2, 2, 0, 2, 1, 1, 1, 1, 2, 0, 0, 1, 1, 2, 0, 0, 1, 2, 2, 1, 1, 1, 0, 1, 1, 0, 0, 2, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 7, 2, 2, 3, 3, 1, 2, 3, 2, 3, 0, 2, 1, 1, 2, 1, 1, 1, 2, 0, 2, 0, 1, 2, 0, 0, 2, 0, 2, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 1, 0, 1, 0, 0, 1, 1, 2, 1, 1, 3, 2, 2, 0, 2, 0, 0, 2, 1, 1, 2, 0, 0, 3, 2, 0, 1, 0, 1, 1, 1, 2, 1, 1, 1, 0, 1, 0, 2, 1, 1, 0, 0, 1, 0, 1, 1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 2, 3, 2, 2, 0, 2, 0, 2, 0, 1, 0, 2, 1, 0, 2, 0, 0, 1, 0, 0, 4, 0, 1, 1, 2, 3, 2, 1, 2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 1, 2, 2, 2, 1, 1, 0, 2, 0, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 0, 1, 2, 0, 1, 2, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 1, 1, 3, 0, 1, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 2, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 3, 0, 1, 1, 1, 1, 2, 0, 0, 1, 0, 0, 1, 2, 0, 0, 1, 0, 0, 1, 0, 1, 0, 0, 1, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 1, 0, 1, 2, 6, 3, 3, 8, 3, 0, 3, 4, 3, 4, 0, 2, 0, 4, 1, 3, 1, 3, 1, 0, 1, 1, 1, 1, 0, 0, 1, 2, 3, 1, 1, 1, 0, 0, 0, 1, 1, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
]
},
"Population": {
"Units": "",
"Data": [
[1908, 1908, 1905, 1905, 1904, 1900, 1899, 1897, 1896, 1895, 1894, 1894, 1893, 1892, 1892, 1891, 1890, 1890, 1888, 1888, 1886, 1886, 1886, 1885, 1884, 1884, 1884, 1883, 1881, 1881, 1881, 1881, 1881, 1881, 1881, 1880, 1878, 1877, 1876, 1876, 1875, 1874, 1871, 1870, 1867, 1866, 1865, 1864, 1863, 1863, 1863, 1861, 1861, 1861, 1861, 1861, 1859, 1859, 1859, 1859, 1859, 1858, 1857, 1855, 1855, 1853, 1852, 1852, 1852, 1851, 1851, 1850, 1849, 1849, 1848, 1848, 1847, 1846, 1846, 1846, 1846, 1845, 1844, 1842, 1842, 1841, 1840, 1838, 1836, 1835, 1832, 1830, 1827, 1826, 1826, 1826, 1825, 1825, 1823, 1821, 1821, 1820, 1820, 1819, 1819, 1818, 1818, 1818, 1817, 1816, 1816, 1815, 1815, 1813, 1811, 1811, 1811, 1811, 1810, 1810, 1809, 1807, 1805, 1803, 1803, 1803, 1799, 1797, 1794, 1794, 1792, 1792, 1792, 1791, 1790, 1789, 1787, 1787, 1786, 1786, 1786, 1785, 1784, 1783, 1782, 1779, 1777, 1776, 1775, 1774],
[1592, 1591, 1592, 1592, 1592, 1596, 1596, 1597, 1597, 1598, 1599, 1597, 1598, 1598, 1597, 1598, 1599, 1599, 1601, 1600, 1601, 1600, 1599, 1599, 1600, 1600, 1599, 1600, 1602, 1602, 1602, 1602, 1601, 1599, 1599, 1599, 1601, 1601, 1601, 1600, 1601, 1602, 1604, 1604, 1607, 1607, 1608, 1607, 1606, 1606, 1605, 1607, 1607, 1605, 1605, 1605, 1605, 1604, 1604, 1602, 1599, 1599, 1599, 1601, 1600, 1600, 1601, 1600, 1598, 1598, 1597, 1597, 1597, 1596, 1595, 1593, 1592, 1593, 1592, 1591, 1591, 1590, 1591, 1592, 1592, 1592, 1593, 1594, 1596, 1597, 1598, 1598, 1601, 1602, 1602, 1601, 1602, 1601, 1602, 1604, 1603, 1604, 1603, 1603, 1603, 1602, 1601, 1600, 1600, 1600, 1597, 1598, 1597, 1598, 1599, 1598, 1598, 1598, 1598, 1597, 1598, 1599, 1599, 1600, 1599, 1595, 1599, 1601, 1604, 1602, 1604, 1604, 1602, 1602, 1602, 1602, 1603, 1601, 1602, 1602, 1602, 1602, 1602, 1602, 1602, 1605, 1606, 1606, 1605, 1605],
[1252, 1252, 1254, 1252, 1252, 1252, 1253, 1253, 1254, 1254, 1253, 1255, 1253, 1253, 1253, 1253, 1253, 1253, 1252, 1251, 1252, 1252, 1253, 1252, 1252, 1252, 1253, 1253, 1253, 1253, 1252, 1252, 1253, 1254, 1253, 1253, 1251, 1250, 1251, 1252, 1250, 1248, 1248, 1247, 1247, 1248, 1247, 1247, 1247, 1247, 1248, 1247, 1246, 1248, 1248, 1248, 1249, 1250, 1250, 1252, 1254, 1253, 1254, 1254, 1255, 1256, 1255, 1256, 1258, 1259, 1260, 1261, 1262, 1262, 1264, 1266, 1268, 1268, 1269, 1269, 1269, 1271, 1269, 1269, 1269, 1270, 1270, 1270, 1269, 1268, 1270, 1272, 1272, 1272, 1272, 1273, 1273, 1272, 1273, 1271, 1271, 1271, 1272, 1272, 1272, 1273, 1271, 1270, 1271, 1272, 1275, 1275, 1274, 1274, 1274, 1272, 1271, 1271, 1271, 1271, 1271, 1271, 1271, 1272, 1273, 1277, 1276, 1276, 1274, 1276, 1275, 1275, 1277, 1278, 1279, 1279, 1278, 1280, 1278, 1277, 1276, 1277, 1278, 1279, 1280, 1279, 1280, 1280, 1282, 1282],
[1034, 1035, 1034, 1036, 1035, 1034, 1034, 1033, 1033, 1031, 1032, 1032, 1034, 1033, 1034, 1034, 1034, 1033, 1033, 1035, 1035, 1035, 1034, 1035, 1035, 1035, 1034, 1033, 1031, 1031, 1032, 1032, 1031, 1032, 1033, 1034, 1036, 1038, 1036, 1035, 1037, 1039, 1039, 1041, 1041, 1041, 1042, 1044, 1046, 1046, 1046, 1047, 1048, 1048, 1048, 1046, 1046, 1046, 1046, 1046, 1047, 1049, 1049, 1049, 1049, 1049, 1050, 1050, 1050, 1050, 1049, 1048, 1048, 1049, 1049, 1049, 1047, 1047, 1047, 1047, 1045, 1045, 1047, 1048, 1048, 1047, 1047, 1046, 1047, 1047, 1047, 1046, 1045, 1045, 1044, 1044, 1044, 1046, 1045, 1047, 1048, 1048, 1048, 1049, 1049, 1049, 1052, 1053, 1053, 1053, 1053, 1052, 1052, 1051, 1051, 1054, 1054, 1054, 1054, 1055, 1054, 1055, 1056, 1056, 1054, 1053, 1052, 1052, 1054, 1054, 1052, 1050, 1049, 1048, 1048, 1049, 1051, 1051, 1053, 1053, 1054, 1053, 1053, 1051, 1050, 1051, 1051, 1051, 1050, 1051],
[793, 793, 794, 794, 796, 796, 796, 798, 798, 800, 799, 797, 797, 798, 798, 798, 798, 799, 800, 800, 800, 800, 801, 801, 801, 800, 801, 802, 804, 803, 802, 801, 802, 802, 802, 802, 801, 800, 802, 802, 802, 802, 800, 800, 800, 799, 799, 799, 799, 799, 798, 798, 797, 796, 796, 798, 799, 799, 798, 798, 798, 798, 797, 797, 797, 798, 797, 797, 797, 797, 798, 799, 799, 798, 798, 797, 798, 798, 797, 798, 800, 800, 800, 800, 800, 799, 799, 801, 801, 800, 800, 801, 801, 801, 802, 802, 801, 800, 801, 801, 799, 799, 798, 798, 797, 798, 797, 798, 798, 798, 797, 798, 800, 802, 803, 803, 803, 803, 804, 804, 805, 805, 805, 805, 806, 807, 807, 807, 807, 807, 810, 812, 813, 813, 813, 813, 813, 812, 812, 813, 813, 814, 813, 815, 815, 815, 815, 816, 817, 817],
[665, 665, 665, 665, 662, 663, 663, 663, 663, 662, 663, 664, 664, 664, 664, 664, 664, 662, 662, 662, 662, 662, 661, 661, 660, 661, 661, 661, 660, 661, 661, 661, 661, 661, 661, 661, 661, 661, 661, 662, 661, 661, 664, 664, 664, 665, 665, 665, 664, 663, 664, 664, 665, 666, 666, 666, 666, 666, 667, 667, 666, 666, 666, 666, 666, 666, 666, 665, 665, 665, 665, 665, 665, 665, 665, 666, 667, 667, 667, 667, 667, 667, 667, 667, 667, 669, 669, 668, 668, 670, 670, 669, 669, 668, 668, 667, 668, 667, 666, 666, 668, 668, 669, 669, 670, 670, 671, 670, 669, 669, 669, 669, 669, 669, 669, 668, 667, 666, 666, 664, 664, 662, 663, 662, 663, 661, 662, 661, 661, 661, 661, 661, 661, 662, 662, 662, 662, 662, 662, 662, 662, 662, 663, 663, 663, 663, 663, 663, 662, 662],
[567, 567, 565, 565, 568, 567, 567, 567, 567, 567, 566, 565, 565, 566, 565, 565, 565, 566, 566, 566, 566, 567, 568, 568, 569, 567, 566, 566, 567, 567, 568, 569, 569, 569, 569, 569, 570, 571, 571, 571, 572, 572, 572, 572, 572, 570, 570, 570, 571, 572, 572, 571, 571, 570, 570, 570, 570, 569, 568, 568, 569, 569, 569, 569, 569, 569, 569, 569, 568, 568, 568, 568, 568, 569, 569, 569, 568, 567, 568, 568, 567, 567, 567, 566, 566, 565, 565, 564, 564, 564, 564, 564, 565, 566, 566, 567, 567, 569, 570, 570, 569, 569, 568, 568, 567, 567, 566, 567, 567, 567, 567, 567, 567, 567, 567, 568, 570, 571, 571, 573, 573, 575, 575, 576, 576, 578, 578, 579, 577, 577, 577, 577, 577, 576, 574, 573, 573, 574, 573, 573, 573, 573, 573, 573, 574, 574, 573, 573, 574, 574],
[398, 398, 400, 399, 399, 399, 399, 399, 399, 400, 401, 402, 402, 402, 403, 402, 402, 403, 403, 403, 403, 403, 403, 404, 404, 406, 407, 407, 407, 407, 407, 407, 407, 407, 407, 406, 406, 406, 406, 406, 406, 405, 403, 403, 403, 405, 404, 404, 403, 403, 403, 404, 403, 404, 404, 404, 403, 403, 404, 404, 404, 404, 405, 405, 405, 405, 405, 406, 407, 406, 405, 405, 405, 405, 405, 404, 405, 406, 406, 406, 407, 407, 407, 408, 408, 409, 409, 411, 411, 411, 411, 411, 411, 410, 410, 410, 409, 409, 409, 408, 409, 409, 410, 410, 411, 411, 412, 412, 413, 413, 414, 413, 413, 413, 413, 413, 413, 412, 412, 412, 411, 410, 410, 410, 410, 408, 409, 409, 411, 411, 410, 410, 410, 410, 412, 412, 411, 411, 411, 411, 411, 411, 411, 411, 411, 411, 412, 412, 412, 412],
[349, 349, 349, 350, 350, 351, 351, 351, 350, 350, 350, 351, 351, 350, 350, 351, 351, 351, 351, 351, 350, 350, 350, 350, 350, 349, 349, 349, 349, 349, 349, 349, 349, 349, 349, 350, 350, 350, 349, 349, 349, 350, 351, 351, 351, 350, 351, 351, 352, 352, 352, 351, 352, 352, 352, 351, 352, 353, 352, 352, 352, 352, 352, 352, 352, 352, 353, 353, 353, 354, 355, 355, 354, 354, 354, 355, 355, 355, 355, 355, 355, 355, 355, 355, 354, 354, 353, 353, 353, 353, 353, 353, 353, 354, 354, 354, 355, 355, 355, 356, 356, 356, 356, 356, 356, 356, 355, 355, 354, 354, 354, 355, 355, 355, 355, 354, 354, 355, 355, 355, 356, 357, 357, 357, 357, 359, 359, 359, 359, 358, 359, 359, 359, 360, 360, 361, 362, 362, 363, 363, 363, 361, 361, 360, 359, 359, 359, 359, 359, 359],
[281, 281, 281, 281, 281, 281, 280, 280, 281, 281, 281, 281, 281, 282, 282, 282, 282, 282, 282, 282, 283, 283, 282, 282, 282, 283, 283, 283, 283, 283, 283, 283, 283, 283, 283, 282, 281, 281, 282, 282, 281, 281, 282, 282, 282, 283, 283, 283, 283, 283, 283, 284, 284, 284, 284, 285, 285, 285, 286, 286, 286, 286, 286, 286, 286, 286, 286, 286, 286, 286, 286, 286, 287, 287, 287, 287, 286, 286, 286, 286, 285, 285, 285, 285, 285, 285, 286, 286, 286, 286, 286, 287, 287, 287, 287, 287, 287, 287, 287, 287, 286, 286, 286, 285, 285, 285, 285, 285, 286, 284, 284, 284, 284, 283, 282, 283, 283, 283, 283, 283, 283, 282, 282, 282, 282, 282, 282, 282, 281, 282, 282, 282, 282, 282, 282, 281, 281, 281, 281, 281, 281, 283, 283, 283, 284, 283, 283, 282, 282, 282],
[218, 218, 218, 218, 218, 218, 219, 219, 218, 218, 218, 218, 218, 218, 218, 218, 218, 218, 218, 218, 218, 218, 219, 219, 219, 219, 219, 219, 219, 219, 218, 216, 216, 215, 215, 215, 215, 214, 214, 214, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 214, 214, 214, 214, 214, 214, 214, 214, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 214, 214, 214, 214, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 216, 216, 216, 217, 217, 216, 218, 218, 218, 218, 219, 220, 220, 220, 220, 220, 220, 220, 221, 221, 221, 221, 221, 220, 220, 221, 221, 220, 220, 220, 220, 220, 221, 221, 221, 221, 221, 221, 221, 221, 222, 222, 223, 223, 224, 224, 224],
[188, 188, 188, 188, 188, 188, 188, 188, 189, 189, 188, 188, 188, 188, 188, 187, 187, 187, 187, 186, 186, 184, 182, 182, 182, 182, 182, 182, 181, 181, 182, 184, 184, 185, 185, 186, 187, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 189, 189, 189, 188, 188, 188, 188, 187, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 187, 187, 187, 187, 187, 187, 187, 187, 187, 187, 186, 186, 186, 187, 186, 186, 186, 186, 186, 185, 184, 184, 184, 184, 184, 184, 184, 183, 183, 184, 184, 184, 184, 184, 184, 184, 184, 185, 185, 185, 185, 185, 185, 185, 185, 184, 184, 184, 184, 184, 184, 184, 184, 184, 184, 185, 185, 185, 185, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186],
[158, 158, 158, 158, 158, 158, 158, 158, 158, 158, 159, 159, 159, 159, 159, 160, 160, 160, 160, 161, 161, 163, 165, 165, 165, 165, 165, 165, 166, 166, 166, 166, 166, 166, 166, 166, 166, 166, 165, 165, 165, 165, 165, 165, 165, 165, 165, 165, 165, 165, 165, 165, 165, 164, 164, 165, 165, 165, 165, 166, 166, 166, 166, 166, 166, 166, 166, 166, 166, 166, 166, 167, 167, 167, 167, 167, 167, 167, 167, 167, 167, 168, 168, 168, 168, 169, 169, 169, 169, 169, 170, 171, 171, 171, 171, 171, 171, 171, 170, 170, 170, 170, 168, 168, 168, 168, 168, 168, 168, 167, 166, 166, 165, 165, 165, 165, 166, 166, 166, 166, 166, 166, 166, 166, 166, 166, 165, 165, 165, 165, 165, 164, 164, 164, 164, 164, 164, 164, 164, 164, 164, 164, 164, 163, 163, 163, 163, 163, 163, 163],
[115, 115, 115, 114, 114, 114, 114, 114, 114, 114, 114, 114, 113, 113, 113, 113, 112, 112, 112, 111, 111, 111, 111, 111, 111, 111, 110, 110, 109, 109, 109, 109, 109, 109, 109, 109, 109, 109, 110, 110, 110, 110, 109, 109, 109, 109, 109, 109, 109, 109, 109, 109, 109, 110, 110, 110, 110, 110, 110, 110, 110, 110, 110, 110, 110, 109, 109, 109, 109, 109, 109, 108, 108, 108, 108, 108, 108, 108, 108, 108, 108, 108, 108, 108, 107, 107, 107, 107, 107, 107, 107, 107, 107, 107, 106, 106, 106, 106, 108, 108, 108, 108, 110, 109, 109, 109, 109, 109, 109, 110, 111, 111, 112, 112, 112, 112, 112, 112, 112, 112, 112, 112, 112, 112, 112, 112, 113, 113, 113, 113, 113, 114, 113, 113, 113, 113, 113, 113, 113, 113, 113, 113, 113, 114, 114, 114, 114, 114, 114, 114],
[95, 95, 95, 96, 96, 96, 96, 96, 96, 96, 96, 96, 97, 97, 97, 97, 98, 98, 98, 99, 99, 99, 99, 99, 99, 99, 100, 100, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 103, 103, 103, 103, 103, 103, 104, 104, 104, 104, 104, 104, 103, 103, 103, 103, 103, 103, 103, 104, 104, 104, 103, 103, 103, 103, 103, 103, 103, 104, 104, 104, 104, 104, 104, 104, 104, 104, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105],
[78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 77, 77, 77, 77, 77, 77, 77, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 75, 75, 75, 75, 75, 75, 75, 75, 75, 76, 76, 75, 75, 75, 75, 75, 75, 75, 75, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 74, 75, 75, 75, 75, 75, 75, 75, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74],
[72, 72, 72, 72, 72, 72, 72, 72, 72, 72, 72, 72, 71, 71, 71, 71, 71, 71, 71, 72, 72, 72, 72, 72, 72, 72, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 72, 72, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 74, 74, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74],
[49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 50, 50, 51, 51, 51, 52, 52, 52, 52, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50],
[39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 43, 43, 43, 43, 43, 43, 43, 43, 43, 42, 42, 42, 42, 42],
[30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 29, 29, 29, 29, 29],
[119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121]
]
}
}
}
Demographic summary output report¶
The demographic summary output report is a JSON-formatted file with the demographic channel output results of the simulation, consisting of simulation-wide averages by time step. The format is identical to the inset chart output report, except the channels reflect demographic categories, such as gender ratio. The file name is DemographicsSummary.json.
To generate the demographics summary report, set the Enable_Demographics_Reporting configuration parameter to 1. The binned output report will also be generated.
The file contains a header and a channels section.
Header¶
The header section contains the following parameters.
Parameter |
Data type |
Description |
|---|---|---|
DateTime |
string |
The time stamp indicating when the report was generated. |
DTK_Version |
string |
The version of EMOD used. |
Report_Type |
string |
The type of output report. |
Report_Version |
string |
The format version of the report. |
Start_Time |
integer |
The time noted in days when the simulation begins. |
Simulation_Timestep |
integer |
The number of days in each time step. |
Timesteps |
integer |
The number of time steps in this simulation. |
Channels |
integer |
The number of channels in the simulation. |
Channels¶
The channels section contains the following parameters.
Parameter |
Data type |
Description |
|---|---|---|
<Channel_Title> |
string |
The title of the particular demographic channel. |
Units |
string |
The units used for this channel. |
Data |
array |
A list of the channel data at each time step. |
Example¶
The following is a sample of a DemographicsSummary.json file.
{
"Header": {
"DateTime": "Mon Mar 16 07:45:10 2015",
"DTK_Version": "4777 v2.0-HIV 2015/02/26 10:51:25",
"Report_Type": "InsetChart",
"Report_Version": "3.2",
"Start_Time": 0,
"Simulation_Timestep": 1,
"Timesteps": 5,
"Channels": 28
},
"Channels": {
"Average Age": {
"Units": "",
"Data": [
8592.415039063,
8593.427734375,
8594.439453125,
8595.41796875,
8596.412109375
]
},
"Gender Ratio (fraction male)": {
"Units": "",
"Data": [
0.5350999832153,
0.5350999832153,
0.5350999832153,
0.5350999832153,
0.5350999832153
]
},
"New Births": {
"Units": "",
"Data": [
0,
0,
0,
0,
0
]
},
"New Natural Deaths": {
"Units": "",
"Data": [
0,
0,
0,
0,
0
]
},
"Population Age 10-14": {
"Units": "",
"Data": [
1203,
1204,
1202,
1203,
1203
]
},
"Population Age 15-19": {
"Units": "",
"Data": [
1056,
1057,
1059,
1059,
1059
]
},
"Population Age 20-24": {
"Units": "",
"Data": [
810,
810,
810,
809,
809
]
},
"Population Age 25-29": {
"Units": "",
"Data": [
732,
732,
732,
732,
732
]
},
"Population Age 30-34": {
"Units": "",
"Data": [
540,
539,
539,
539,
539
]
},
"Population Age 35-39": {
"Units": "",
"Data": [
410,
411,
411,
411,
411
]
},
"Population Age 40-44": {
"Units": "",
"Data": [
351,
351,
351,
352,
352
]
},
"Population Age 45-49": {
"Units": "",
"Data": [
294,
294,
294,
294,
294
]
},
"Population Age 5-9": {
"Units": "",
"Data": [
1599,
1597,
1598,
1597,
1599
]
},
"Population Age 50-54": {
"Units": "",
"Data": [
201,
201,
201,
201,
201
]
},
"Population Age 55-59": {
"Units": "",
"Data": [
194,
194,
194,
193,
193
]
},
"Population Age 60-64": {
"Units": "",
"Data": [
163,
163,
163,
164,
164
]
},
"Population Age 65-69": {
"Units": "",
"Data": [
111,
111,
111,
111,
111
]
},
"Population Age 70-74": {
"Units": "",
"Data": [
104,
104,
104,
103,
103
]
},
"Population Age 75-79": {
"Units": "",
"Data": [
86,
86,
86,
87,
87
]
},
"Population Age 80-84": {
"Units": "",
"Data": [
55,
55,
55,
55,
55
]
},
"Population Age 85-89": {
"Units": "",
"Data": [
61,
61,
61,
61,
61
]
},
"Population Age 90-94": {
"Units": "",
"Data": [
49,
49,
49,
49,
49
]
},
"Population Age 95-99": {
"Units": "",
"Data": [
30,
30,
30,
30,
30
]
},
"Population Age <5": {
"Units": "",
"Data": [
1829,
1829,
1828,
1828,
1826
]
},
"Population Age >100": {
"Units": "",
"Data": [
122,
122,
122,
122,
122
]
},
"Possible Mothers": {
"Units": "",
"Data": [
1912,
1912,
1912,
1913,
1913
]
},
"Pseudo-Population": {
"Units": "",
"Data": [
10000,
10000,
10000,
10000,
10000
]
},
"Statistical Population": {
"Units": "",
"Data": [
10000,
10000,
10000,
10000,
10000
]
}
}
}
Property output report¶
The property output report is a JSON-formatted file with the channel output results of the simulation, defined by the groups set up using IndividualProperties in the demographics file. See Configure heterogeneous populations. For example, it allows you to compare disease deaths for people in the high risk group versus the low risk group. If you want to aggregate the data, you must create a script for aggregating information. The file name is PropertyReport.json.
To generate the property report, set the Enable_Property_Output configuration parameter to 1.
The file contains a header and a channels section.
Header¶
The header section contains the following parameters.
Parameter |
Data type |
Description |
|---|---|---|
DateTime |
string |
The time stamp indicating when the report was generated. |
DTK_Version |
string |
The version of EMOD used. |
Report_Type |
string |
The type of output report. |
Report_Version |
string |
The format version of the report. |
Start_Time |
integer |
The time noted in days when the simulation begins. |
Simulation_Timestep |
integer |
The number of days in each time step. |
Timesteps |
integer |
The number of time steps in this simulation. |
Channels |
integer |
The number of channels in the simulation. |
Channels¶
The channels section contains the following parameters.
Parameter |
Data type |
Description |
|---|---|---|
<Channel_Title> |
string |
The title of the particular property channel. The channel titles use the following conventions: for a single property, <channel type>:<property>:<value>, and for multiple properties, <channel type>:<property 1>:<value>,<property 2>:<value>. For example, Infected:Accessibility:Easy or New Infections:Accessibility:Difficult,Risk:High. |
Units |
string |
The units used for this channel. |
Data |
array |
A list of the channel data at each time step. |
Example¶
The following is a sample of a PropertyReport.json file.
{
"Header": {
"DateTime": "Mon Feb 15 21:49:24 2016",
"DTK_Version": "5538 trunk 2015/08/07 14:40:43",
"Report_Type": "InsetChart",
"Report_Version": "3.2",
"Start_Time": 0,
"Simulation_Timestep": 1,
"Timesteps": 10,
"Channels": 8
},
"Channels": {
"Disease Deaths:Accessibility:Easy": {
"Units": "",
"Data": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
},
"Disease Deaths:Accessibility:Hard": {
"Units": "",
"Data": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
},
"Infected:Accessibility:Easy": {
"Units": "",
"Data": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
},
"Infected:Accessibility:Hard": {
"Units": "",
"Data": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
},
"New Infections:Accessibility:Easy": {
"Units": "",
"Data": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
},
"New Infections:Accessibility:Hard": {
"Units": "",
"Data": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
},
"Statistical Population:Accessibility:Easy": {
"Units": "",
"Data": [
6946,
6946,
6946,
6946,
6946,
6946,
6946,
6946,
6946,
6946
]
},
"Statistical Population:Accessibility:Hard": {
"Units": "",
"Data": [
3054,
3054,
3054,
3054,
3054,
3054,
3054,
3054,
3054,
3054
]
}
}
}
Spatial output report¶
The spatial output report breaks the channel data down per node, rather than across the entire simulation. It is a set of binary files, consisting of one file per channel. For each value set in the Spatial_Output_Channels configuration parameter array, a binary file with the name convention SpatialReport_<channel>.bin is generated. In addition, Enable_Spatial_Output must be set to 1.
The binary format of the file consists of a stream of 4-byte integers followed by a stream of 4-byte floating point values. The first value is a 4-byte integer representing the number of nodes in the file and the second is a 4-byte integer that contains the number of time steps in the file. Following these two values is a stream of 4-byte integers that contain the node ID values in the order they will appear in the rest of the file. Following the node IDs is an array of 4-byte floating point values that represent the output values at the first time step for each node. The next array contains the values at the second time step, and so on.
The following diagram shows the format for data in the spatial output report file:
Error and logging files¶
When you run a simulation, EMOD will output basic error and logging information to help track the progress and help debug any issues that may occur. If you run the simulation on an HPC cluster, the cluster will generate additional logging and error files. See Troubleshooting EMOD simulations if you need help resolving an error.
Status¶
A status.txt file will be saved to the working directory that provides one output line per time step and includes the total run time of the simulation. A simulation with 50 time steps will look something like this:
Beginning Simulation...
1 of 50 steps complete.
2 of 50 steps complete.
3 of 50 steps complete.
4 of 50 steps complete.
5 of 50 steps complete.
6 of 50 steps complete.
7 of 50 steps complete.
8 of 50 steps complete.
9 of 50 steps complete.
10 of 50 steps complete.
11 of 50 steps complete.
12 of 50 steps complete.
13 of 50 steps complete.
14 of 50 steps complete.
15 of 50 steps complete.
16 of 50 steps complete.
17 of 50 steps complete.
18 of 50 steps complete.
19 of 50 steps complete.
20 of 50 steps complete.
21 of 50 steps complete.
22 of 50 steps complete.
23 of 50 steps complete.
24 of 50 steps complete.
25 of 50 steps complete.
26 of 50 steps complete.
27 of 50 steps complete.
28 of 50 steps complete.
29 of 50 steps complete.
30 of 50 steps complete.
31 of 50 steps complete.
32 of 50 steps complete.
33 of 50 steps complete.
34 of 50 steps complete.
35 of 50 steps complete.
36 of 50 steps complete.
37 of 50 steps complete.
38 of 50 steps complete.
39 of 50 steps complete.
40 of 50 steps complete.
41 of 50 steps complete.
42 of 50 steps complete.
43 of 50 steps complete.
44 of 50 steps complete.
45 of 50 steps complete.
46 of 50 steps complete.
47 of 50 steps complete.
48 of 50 steps complete.
49 of 50 steps complete.
50 of 50 steps complete.
Done - 0:00:02
Standard output¶
When you run a simulation on an HPC cluster, it will generate a standard output logging file
(StdOut.txt) in the working directory that captures all standard output messages. When you run a
simulation locally, the Command Prompt window will display the same information. If you want to save
this information to a text file instead, you can append > stdout.txt to the command used to
run the local EMOD simulation to redirect the console output to the file specified.
The file contains information about a particular simulation, such as the EMOD version used and the files in use, as well as other initialization information, including the default logging level and the logging levels set for particular modules. The file follows that information with log output using the following format: <timestep><HPC rank><log level><module><message>.
By default, the logging level is set to “INFO”. If you want to change the logging level, see Set log levels.
For example:
C:\EMOD\CampaignTesting\00_DefaultDemographics>..\Eradication.exe -C config.json -I ../input
Intellectual Ventures(R)/EMOD Disease Transmission Kernel 2.8.1331.0
Built on Sep 30 2016 08:39:43 by cwiswell from master (482fdae) checked in on 2016-09-28 14:47:20 -0700
Supports sim_types: GENERIC, VECTOR, MALARIA, AIRBORNE, POLIO, TB, TBHIV, STI, HIV, PY.
Using config file: config.json
Using input path: ../input
Using output path: output
using dll path:
--python-script-path (-P) not on command line - not using embedded python
Initializing environment...
Log-levels:
Default -> INFO
Eradication -> INFO
00:00:00 [0] [I] [Eradication] Loaded Configuration...
00:00:00 [0] [I] [Eradication] 99 parameters found.
00:00:00 [0] [I] [Eradication] Initializing Controller...
00:00:00 [0] [I] [Controller] DefaultController::execute_internal()...
00:00:00 [0] [I] [Simulation] Using PSEUDO_DES random number generator.
00:00:00 [0] [I] [Controller] DefaultController::execute_internal() populate simulation...
00:00:00 [0] [I] [Simulation] Campaign file name identified as: campaign.json
00:00:00 [0] [I] [NodeDemographics] Using default 3x3 torus geography
00:00:00 [0] [I] [Climate] Initialize
00:00:00 [0] [I] [LoadBalanceScheme] Using Checkerboard Load Balance Scheme.
00:00:01 [0] [I] [Simulation] Looking for campaign file campaign.json
00:00:01 [0] [I] [Simulation] Found campaign file successfully.
00:00:01 [0] [I] [DllLoader] ReadEmodulesJson: no file, returning.
00:00:01 [0] [I] [DllLoader] dllPath not passed in, getting from EnvPtr
00:00:01 [0] [I] [DllLoader] Trying to copy from string to wstring.
00:00:01 [0] [I] [DllLoader] DLL ws root path:
00:00:01 [0] [W] [Simulation] Failed to load intervention emodules for SimType: GENERIC_SIM from path: interventions
00:00:01 [0] [I] [JsonConfigurable] Using the default value ( "Number_Repetitions" : -1 ) for unspecified parameter.
00:00:01 [0] [I] [JsonConfigurable] Using the default value ( "Timesteps_Between_Repetitions" : -1 ) for unspecified parameter.
00:00:01 [0] [I] [JsonConfigurable] Using the default value ( "Intervention_Name" : "struct Kernel::BaseIntervention" ) for unspecified parameter.
00:00:01 [0] [I] [JsonConfigurable] Using the default value ( "Intervention_Name" : "struct Kernel::BaseIntervention" ) for unspecified parameter.
00:00:01 [0] [I] [JsonConfigurable] Using the default value ( "Intervention_Name" : "struct Kernel::BaseIntervention" ) for unspecified parameter.
00:00:01 [0] [I] [Simulation] populateFromDemographics() created 9 nodes
00:00:01 [0] [I] [Simulation] populateFromDemographics() generated 9 nodes.
00:00:01 [0] [I] [Simulation] Rank 0 contributes 9 nodes...
00:00:01 [0] [I] [Simulation] Merging node rank maps...
00:00:01 [0] [I] [Simulation] Merged rank 0 map now has 9 nodes.
00:00:01 [0] [I] [Simulation] Rank 0 map contents:
{ NodeRankMap:
[1,000000000C10A960]
[2,000000000BF4EAF0]
[3,000000000BFA2250]
[4,000000000BFF1C10]
[5,000000000BE37B60]
[6,000000000BE87380]
[7,000000000BEE74F0]
[8,000000000B721980]
[9,000000000B7AE280]
}
00:00:01 [0] [I] [Simulation] Initialized 'InsetChart.json' reporter
00:00:01 [0] [I] [Simulation] Initialized 'BinnedReport.json' reporter
00:00:01 [0] [I] [Simulation] Initialized 'DemographicsSummary.json' reporter
00:00:01 [0] [I] [Simulation] Update(): Time: 1.0 Rank: 0 StatPop: 900 Infected: 0
00:00:01 [0] [I] [SimulationEventContext] Time for campaign event. Calling Dispatch...
00:00:01 [0] [I] [SimulationEventContext] 9 node(s) visited.
00:00:01 [0] [I] [JsonConfigurable] Using the default value ( "Intervention_Name" : "struct Kernel::BaseIntervention" ) for unspecified parameter.
00:00:01 [0] [I] [JsonConfigurable] Using the default value ( "Intervention_Name" : "struct Kernel::BaseIntervention" ) for unspecified parameter.
00:00:01 [0] [I] [StandardEventCoordinator] UpdateNodes() gave out 0 'OutbreakIndividual' interventions at node 1
00:00:01 [0] [I] [StandardEventCoordinator] UpdateNodes() gave out 2 'OutbreakIndividual' interventions at node 2
00:00:01 [0] [I] [StandardEventCoordinator] UpdateNodes() gave out 0 'OutbreakIndividual' interventions at node 3
00:00:01 [0] [I] [StandardEventCoordinator] UpdateNodes() gave out 0 'OutbreakIndividual' interventions at node 4
00:00:01 [0] [I] [StandardEventCoordinator] UpdateNodes() gave out 0 'OutbreakIndividual' interventions at node 5
00:00:01 [0] [I] [StandardEventCoordinator] UpdateNodes() gave out 0 'OutbreakIndividual' interventions at node 6
00:00:01 [0] [I] [StandardEventCoordinator] UpdateNodes() gave out 0 'OutbreakIndividual' interventions at node 7
00:00:01 [0] [I] [StandardEventCoordinator] UpdateNodes() gave out 1 'OutbreakIndividual' interventions at node 8
00:00:01 [0] [I] [StandardEventCoordinator] UpdateNodes() gave out 1 'OutbreakIndividual' interventions at node 9
00:00:01 [0] [I] [Simulation] Update(): Time: 2.0 Rank: 0 StatPop: 900 Infected: 4
00:00:01 [0] [I] [Simulation] Update(): Time: 3.0 Rank: 0 StatPop: 900 Infected: 18
00:00:01 [0] [I] [Simulation] Update(): Time: 4.0 Rank: 0 StatPop: 900 Infected: 63
00:00:01 [0] [I] [Simulation] Update(): Time: 5.0 Rank: 0 StatPop: 900 Infected: 161
00:00:01 [0] [I] [Simulation] Update(): Time: 6.0 Rank: 0 StatPop: 900 Infected: 232
00:00:01 [0] [I] [Simulation] Update(): Time: 7.0 Rank: 0 StatPop: 900 Infected: 203
00:00:01 [0] [I] [Simulation] Update(): Time: 8.0 Rank: 0 StatPop: 900 Infected: 165
00:00:01 [0] [I] [Simulation] Update(): Time: 9.0 Rank: 0 StatPop: 900 Infected: 132
00:00:01 [0] [I] [Simulation] Update(): Time: 10.0 Rank: 0 StatPop: 900 Infected: 110
00:00:01 [0] [I] [Simulation] Update(): Time: 11.0 Rank: 0 StatPop: 900 Infected: 83
00:00:01 [0] [I] [Simulation] Update(): Time: 12.0 Rank: 0 StatPop: 900 Infected: 69
00:00:01 [0] [I] [Simulation] Update(): Time: 13.0 Rank: 0 StatPop: 900 Infected: 54
00:00:01 [0] [I] [Simulation] Update(): Time: 14.0 Rank: 0 StatPop: 900 Infected: 40
00:00:01 [0] [I] [Simulation] Update(): Time: 15.0 Rank: 0 StatPop: 900 Infected: 30
00:00:01 [0] [I] [Simulation] Update(): Time: 16.0 Rank: 0 StatPop: 900 Infected: 22
00:00:01 [0] [I] [Simulation] Update(): Time: 17.0 Rank: 0 StatPop: 900 Infected: 17
00:00:01 [0] [I] [Simulation] Update(): Time: 18.0 Rank: 0 StatPop: 900 Infected: 14
00:00:01 [0] [I] [Simulation] Update(): Time: 19.0 Rank: 0 StatPop: 900 Infected: 12
00:00:01 [0] [I] [Simulation] Update(): Time: 20.0 Rank: 0 StatPop: 900 Infected: 9
00:00:01 [0] [I] [Simulation] Update(): Time: 21.0 Rank: 0 StatPop: 900 Infected: 7
00:00:01 [0] [I] [Simulation] Update(): Time: 22.0 Rank: 0 StatPop: 900 Infected: 7
00:00:01 [0] [I] [Simulation] Update(): Time: 23.0 Rank: 0 StatPop: 900 Infected: 7
00:00:01 [0] [I] [Simulation] Update(): Time: 24.0 Rank: 0 StatPop: 900 Infected: 5
00:00:01 [0] [I] [Simulation] Update(): Time: 25.0 Rank: 0 StatPop: 900 Infected: 3
00:00:01 [0] [I] [Simulation] Update(): Time: 26.0 Rank: 0 StatPop: 900 Infected: 3
00:00:01 [0] [I] [Simulation] Update(): Time: 27.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 28.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 29.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 30.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 31.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 32.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 33.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 34.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 35.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 36.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 37.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 38.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 39.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 40.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 41.0 Rank: 0 StatPop: 900 Infected: 1
00:00:02 [0] [I] [Simulation] Update(): Time: 42.0 Rank: 0 StatPop: 900 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 43.0 Rank: 0 StatPop: 900 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 44.0 Rank: 0 StatPop: 900 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 45.0 Rank: 0 StatPop: 900 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 46.0 Rank: 0 StatPop: 900 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 47.0 Rank: 0 StatPop: 900 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 48.0 Rank: 0 StatPop: 900 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 49.0 Rank: 0 StatPop: 900 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 50.0 Rank: 0 StatPop: 900 Infected: 0
00:00:02 [0] [I] [Simulation] Finalizing 'InsetChart.json' reporter.
00:00:02 [0] [I] [Simulation] Finalizing 'BinnedReport.json' reporter.
00:00:02 [0] [I] [Simulation] Finalizing 'DemographicsSummary.json' reporter.
00:00:02 [0] [I] [Eradication] Controller executed successfully.
Standard error¶
When you run a simulation on an HPC cluster, it will also generate a standard error logging file (StdErr.txt) in the working directory that captures all standard error messages.
Troubleshooting EMOD simulations¶
If you encounter any of the following problems when attempting to run EMOD simulations, see the information below to resolve the issue.
If you need assistance, you can contact support for help with solving issues. You can contact Institute for Disease Modeling (IDM) support at support@idmod.org. When submitting the issue, please include any error information. See Debugging and testing for troubleshooting issues when attempting to build Eradication.exe or Eradication binary.
Contents
Exceptions¶
Whenever EMOD encounters an error condition while running a simulation, it should throw an exception. These exceptions are designed to help you diagnose any problems so that you can quickly resolve the issue. You can find the exceptions code in the utils directory of the EMOD source code within the files Exceptions.h and Exceptions.cpp.
Each exception will return, at a minimum, the following information:
Exception type caught
The filename where the exception occurred
The line number in the file where the exception was thrown (which may not be exactly where the error actually occurred in the code)
The function name where the exception was thrown
Specific exceptions may also return additional information in a message format. This message (msg) may contain variable names or the values of those variables, the name of a file that wasn’t found, and other informational text regarding the nature of the problem. For example, a file not found exception (FileNotFoundException) might look similar to the following:
00:00:00 [0] [E] [Eradication] FileNotFoundException caught: msg = Could not find
file ./Namawala_single_node_demographics.compiled.json, filename = NodeDemographics.cpp,
lineNumber = 227
BadEnumInSwitchStatementException¶
This exception is thrown when an enumeration value is not handled in the switch statement. In other words, this exception signals that there is a problem with an enumeration value, typically stemming from one of the configuration files, though this is not always the case.
It is possible the enumeration value is not a valid value (out of range of the numeric range of the enumeration), or perhaps the string value is currently not implemented in the code (and should not be used in configuration settings yet).
BadMapKeyException¶
This exception is thrown when there is a standard template library (STL) mapping error. Usually, this occurs where spatial output channel names are specified in the configuration file if an unrecognized channel name is used.
If you have not modified the EMOD source code or used an unrecognized channel name, this error could signal an internal problem with the code. Contact support@idmod.org.
CalculatedValueOutOfRangeException¶
EMOD performs a large number of mathematical operations on parameter values. Therefore, it is possible that, despite original parameter values being with range, the values resulting from these multiple calculations may end up outside its valid range. For example, a probability value (range: 0 to 1.0) that after multiple calculations during a simulation now exceeds 1.0.
This exception is thrown when such a situation is detected. This exception only applies to numeric or Boolean values, not enumeration values.
ConfigurationRangeException¶
This exception is thrown if a parameter value read from a configuration file is detected to be outside its valid range. This exception is similar to the more general case OutOfRangeException. However, this exception is only thrown if the out of range exception comes from a numeric or Boolean value, not enumeration value, read from a configuration file.
DllLoadingException¶
The EMOD architecture is modularized and can be built as a core Eradication.exe along with a series of custom reporter EMODules, as opposed to a single monolithic Eradication.exe. This exception indicates that EMOD couldn’t load on of the EMODule DLLs.
This situation could occur for several reasons:
EMOD couldn’t find the EMODule
Unresolved symbols were found (Windows)
EMOD could not find the necessary symbol during the GetProcAddress call
The custom reporter EMODules were built using a version of Visual Studio that is no longer supported. Rebuild the EMODules using Visual Studio 2015 (Professional, Premium, or Ultimate).
FactoryCreateFromJsonException¶
EMOD implements class factories that instantiate objects at run time and use information from JSON- based configuration information in the creation of these objects. The exception indicates something is incorrect with the JSON information.
In particular, in some cases, the JSON information is nested into a hierarchy of information. Therefore, as the factories are called to create the objects described by the outer layers of one of these nested hierarchies, the factories do not have any knowledge yet of the inner layers of the hierarchies. This inner information contains information the factory needs to complete the object instantiation, but this information might not be correct. If that happens, then the factory will throw this exception.
Campaign files often have this kind of nested hierarchical structure, so it’s important to t verify that the hierarchy is set up correctly. For example, if the class name were mistyped and EMOD had no implementation of that class, this exception will be thrown.
FileIOException¶
This exception is generated if there is an unrecoverable problem loading data from a file. The data might be corrupted or there may be a mismatch. For example, if the file format or configuration information indicates that there should be ten values of some array and there are only nine included in the file, then this exception would be thrown.
This exception is not the same as the exception thrown for a file that is not found. In this case, the file is found and loaded, but there is a problem with the data in the file.
FileNotFoundException¶
This exception is thrown if a file cannot be found. Possible causes might include a incorrectly typed filename in the configuration file, a wrong path to the file, or even the path not being set in the system environment leading to the system not finding a relative path to the file. One of the most likely causes is that quotes are missing around the file name.
GeneralConfigurationException¶
This exception is only thrown if a more specific exception cannot be used for the configuration problem detected. This exception is likely thrown when there is very little information available about the root problem.
For example, this exception might be thrown if a parameter name is invalid, such as using an older, deprecated version of a parameter name.
IllegalOperationException¶
This exception is thrown if an illegal operation was detected. In most cases, a more specific exception will be thrown rather than this more general one. This exception is likely thrown when there is very little information available about the root problem. For example, when a utility function error is detected, there is very sparse information available as to what may have led to the error. As a result, calling a more specific exception with more context is not an option.
IncoherentConfigurationException¶
This exception is thrown if mutually contradictory or incompatible configuration settings have been detected. For example, if mutually exclusive parameters are set, the minimum parameter value is greater than the maximum value, or two distribution axes are specified in a demographics file but there is a mismatch with the number of axes scale factors included. The exception can also occur if there isn’t a corresponding mapping between an reference ID in the metadata of a demographics file and its corresponding data file.
InitializationException¶
This exception is thrown if a problem with initialization was detected. In most cases, a more specific exception will be thrown rather than this more general one. This exception is likely thrown when there is very little information available about the root problem.
For example, if the very first part of a JSON file has corrupted or badly formatted data, this exception may be thrown instead of the more expected file input/output exception, FileIOException.
InvalidInputDataException¶
This exception is thrown when a problem with an input data file is detected. For example, if the wrong data type was detected, such as a float being detected when a string is expected you would see this exception thrown, or even, if a parameter has an invalid value even if the value is of the correct type. As the input data file most likely to have significant modifications, verify that the demographics file is set up correctly.
MissingParameterFromConfigurationException¶
This exception occurs when required parameters are missing. Verify that you are not using deprecated parameters and that all required parameters are specified (or set Use_Defaults to 1).
MPIException¶
This exception is thrown if there is an MPI error. As such, these types of issues are related to interfacing with MPI (and/or networking issues) and do not necessary imply something wrong with the EMOD code or JSON files.
NotYetImplementedException¶
This exception is thrown if an attempt is made to execute code that is not yet implemented. For example, there are areas of EMOD where placeholder enumeration values are defined but not yet implemented. If you specify a value like this, it is considered within a valid range, but this exception will be thrown in response. Verify that any enumeration values use one of the available values as described in the documentation and do not contain any typos.
NullPointerException¶
This exception is thrown when a NULL pointer is detected in the code, or rather when a NULL pointer - that should NOT be NULL - is used. When thrown at the application level, a NULL pointer exception is usually caused by some sort of initialization error, for example, a file not being found.
As a result, in most cases, a more specific exception will be thrown before the code execution reaches a point where this exception would occur. Therefore, this exception is uncommon and likely thrown only when there is very little information available about the root problem.
OutOfRangeException¶
This exception is thrown when a numeric or Boolean value is out of range. For example, if you index an array outside of its valid range, this exception will be thrown. There are other situations where more specific exceptions are thrown instead of this more general one. For example, when the numeric or Boolean values are from a configuration file, but are detected to be out of range, the ConfigurationRangeException is thrown. Likewise, if the value goes out of range as the result of a calculation, the CalculatedValueOutOfRangeException is thrown instead.
QueryInterfaceException¶
The EMOD architecture is modularized and many components now implement QueryInterface. This exception is thrown when a required interface is queried on an object and the object that returns that the interface is not supported.
If you have not modified the EMOD source code and receive this error, it could signal an internal problem with the code. Contact support@idmod.org.
SerializationException¶
This exception is thrown when there is a serialization (or de-serialization) issue. For example, if data is being passed over the network (MPI) and the connection drops, then the serialization fails and this exception is thrown.
CentOS on Azure environment¶
The following problems are specific to running simulations using the Eradication binary on CentOS 7.1 on Azure.
Regression test graphs differ when run on CentOS on Azure¶
After you run regression simulations on CentOS on Azure using runemod.sh in the Scripts directory, it plots graphs from the simulation output data with a red line for the reference output and a blue line for the new output. The reference output was created by running the simulation on Windows, which in some cases may be slightly different than the output from CentOS on Azure.
For simulations that plot a baseline, you can override the Windows reference output by modifying runemod.sh to use output/InsetChart.linux.json as the output location. In that case, the red reference plots should always be completely covered by the blue plots.
Eradication binary cannot locate the input data files¶
If you chose not to have the PrepareLinuxEnvironment.sh script download the EMOD source code and input data files, you need to set up the environment variable, path and symlink that are needed to run simulations on CentOS on Azure. See Install EMOD on CentOS on Azure.
Glossary¶
The Epidemiological MODeling software (EMOD) glossary is divided into the following subsections that define terms related to software usage, general epidemiology, and the particular disease being modeled.
Contents
Software terms¶
The following terms are used to describe both general computing processes and concepts and the files, features, and functionality related to running simulations with Epidemiological MODeling software (EMOD).
- agent-based model
A type of simulation that models the actions and interactions of autonomous agents (both individual and collective entities such as organizations or groups).
- Boost
Free, peer-reviewed, portable C++ source libraries aimed at a wide range of uses including parallel processing applications (Boost.MPI). For more information, please see the Boost website, http://www.boost.org.
- campaign
A collection of events that use interventions to modify a simulation.
- campaign event
A JSON object that determines when and where an intervention is distributed during a campaign.
- campaign file
A JavaScript Object Notation (JSON) formatted file that contains the parameters that specify the distribution instructions for all interventions used in a campaign, such as diagnostic tests, the target demographic, and the timing and cost of interventions. The location of this file is specified in the configuration file with the Campaign_Filename parameter. Typically, the file name is campaign.json.
- channel
A property of the simulation (for example, “Parasite Prevalence”) that is accumulated once per simulated time step and written to file, typically as an array of the accumulated values.
- class factory
A function that instantiate objects at run-time and use information from JSON-based configuration information in the creation of these objects.
- configuration file
A JavaScript Object Notation (JSON) formatted file that contains the parameters sufficient for initiating a simulation. It controls many different aspects of the simulation, such as population size, disease dynamics, and length of the simulation. Typically, the file name is config.json.
- core
In computing, a core refers to an independent central processing unit (CPU) in the computer. Multi-core computers have more than one CPU. However, through technologies such as Hyper- Threading Technology (HTT or HT), a single physical core can actually act like two virtual or logical cores, and appear to the operating system as two processors.
- demographics file
A JavaScript Object Notation (JSON) formatted file that contains the parameters that specify the demographics of a population, such as age distribution, risk, birthrate, and more. IDM provides demographics files for many geographic regions. This file is considered part of the input data files and is typically named <region>_demographics.json.
- disease-specific build
A build of the EMOD executable (Eradication.exe) built using SCons without any dynamic link libraries (DLLs).
- dynamic link library (DLL)
Microsoft’s implementation of a shared library, separate from the EMOD executable (Eradication.exe), that can be dynamically loaded (and unloaded when unneeded) at runtime. This loading can be explicit or implicit.
- EMODule
A modular component of EMOD that are consumed and used by the EMOD executable (Eradication.exe). Under Windows, a EMODule is implemented as a dynamic link library (DLL) and, under CentOS on Azure, EMODules are currently not supported. EMODules are primarily custom reporters.
- Epidemiological MODeling software (EMOD)
The modeling software from the Institute for Disease Modeling (IDM) for disease researchers and developers to investigate disease dynamics, and to assist in combating a host of infectious diseases. You may see this referred to as Disease Transmission Kernel (DTK) in the source code.
- Eradication.exe
Typical (default) name for the EMOD executable (Eradication.exe), whether built using monolithic build or modular (EMODule-enabled) build.
- event coordinator
A JSON object that determines who will receive a particular intervention during a campaign.
- flattened file
A single campaign or configuration file created by combining a default file with one or more overlay files. Multiple files must be flattened prior to running a simulation. Configuration files are flattened to a single-depth JSON file without nesting, the format required for consumption by the EMOD executable (Eradication.exe). Separating the parameters into multiple files is primarily used for testing and experimentation.
- Heterogeneous Intra-Node Transmission (HINT)
A feature for modeling person-to-person transmission of diseases in heterogeneous population segments within a node for generic simulations.
- high-performance computing (HPC)
The use of parallel processing for running advanced applications efficiently, reliably, and quickly.
- input data files
Fixed information used as input to a simulation. Examples of such data are population, altitude, demographics, and transportation migrations. The configurable config.json and campaign.json files do not fall into this category of static fixed input.
- intervention
An object aimed at reducing the spread of a disease that is distributed either to an individual; such as a vaccine, drug, or bednet; or to a node; such as a larvicide. Additionally, initial disease outbreaks and intermediate interventions that schedule another intervention are implemented as interventions in the campaign file.
- JavaScript Object Notation (JSON)
A human-readable, open standard, text-based file format for data interchange. It is typically used to represent simple data structures and associative arrays, and is language- independent.
- Keyhole Markup Language (KML)
A file format used to display geographic data in an Earth browser, for example, Google Maps. The format uses an XML-based structure (tag-based structure with nested elements and attributes). Tags are case-sensitive.
- Link-Time Code Generation (LTCG)
A method for the linker to optimize code (for size and/or speed) after compilation has occurred. The compiled code is turned not into actual code, but instead into an intermediate language form (IL, but not to be confused with .NET IL which has a different purpose). The LTCG then, unlike the compiler, can see the whole body of code in all object files and be able to optimize the result more effectively.
- Message Passing Interface (MPI)
An interface used to pass information between computing cores in parallel simulations. One example is the migration of individuals from one geographic location to another within EMOD simulations.
- microsolver
A microsolver is a type of “miniature model” that operates within the framework of EMOD to compute a particular set of parameters. Each microsolver, in effect, is creating a microsimulation in order to accurately capture the dynamics of that particular aspect of the model.
- Monte Carlo
Monte Carlo methods, or Monte Carlo experiments, are a class of computational algorithms utilizing repeated random sampling to obtain numerical results. Monte Carlo simulations create probability distributions for possible outcome values, which provides a more realistic way of describing uncertainty in variables.
- monolithic build
A single EMOD executable (Eradication.exe) with no DLLs that includes all components as part of Eradication.exe itself. You can still use EMODules with the monolithic build; for example, a custom reporter is a common type of EMODule. View the documentation on EMODules and emodules_map.json for more information about creation and use of EMODules.
- node
A grid size that is used for modeling geographies. Within EMOD, a node is a geographic region containing simulated individuals. Individuals migrate between nodes either temporarily or permanently using mobility patterns driven by local, regional, and long- distance transportation.
- node-targeted intervention
An intervention that is distributed to a geographical node rather than to a single individual. One example is larvicides, which affect all mosquitoes living and feeding within a given node.
- output report
A file that is the output from an EMOD simulation. Output reports are in JSON, CSV, or binary file format. You must pass the data from an output report to graphing software if you want to visualize the output of a simulation.
- overlay file
An additional configuration, campaign, or demographic file that overrides the default parameter values in the primary file. Separating the parameters into multiple files is primarily used for testing a nd experimentation. In the case of configuration and campaign files, the files can use an arbitrary hierarchical structure to organize parameters into logical groups. Configuration and campaign files must be flattened into a single file before running a simulation.
- preview
Software that undergoes a shorter testing cycle in order to make it available more quickly. Previews may contain software defects that could result in unexpected behavior. Use EMOD previews at your own discretion.
- regression test
A test to verify that existing EMOD functionality works with new updates, typically used to refer to one of a set of scenarios included in the EMOD bundle and located in the Regression subdirectory of the bundle. Directory names of each subdirectory in Regression describe the main regression attributes, for example, “1_Generic_Seattle_MultiNode”. Also can refer to the process of regression testing of software.
- release
Software that includes new functionality, scientific tutorials leveraging new or existing functionality, and/or bug fixes that have been thoroughly tested so that any defects have been fixed before release. EMOD releases undergo full regression testing.
- reporter
Functionality that extracts simulation data, aggregates it, and saves it as an output report. EMOD provides several built-in reporters for outputting data from simulations and you also have the ability to create a custom reporter.
- scenario
A collection of input, configuration, and campaign files that describes a real-world example of a disease outbreak and interventions. Many scenarios are included with both the Quick Start and EMOD source installations. The Quick Start documentation includes tutorials that describe how to run simulations using these scenarios to learn more about epidemiology and disease modeling.
- schema
A text or JSON file that can be generated from the EMOD executable (Eradication.exe) that defines all configuration and campaign parameters.
- simulation
An EMOD software execution performed by the kernel. Each simulation has an associated set of files that control the inputs, configuration, and campaign.
- simulation type
The disease or disease class to model.
EMOD supports the following simulation types for modeling a variety of diseases:
Generic disease (GENERIC_SIM)
Vector-borne diseases (VECTOR_SIM)
Malaria (MALARIA_SIM)
Tuberculosis (TB_SIM)
Sexually transmitted infections (STI_SIM)
HIV (HIV_SIM)
- solvers
Solvers are used to find computational solutions to problems. In simulations, they can be used, for example, to determine the time of the next simulation step, or to compute the states of a model at particular time steps.
- Standard Template Library (STL)
A library that contains a set of common C++ classes (including generic algorithms and data structures) that are independent of container and implemented as templates, which enables compile-time polymorphism (often more efficient than run-time polymorphism). For more information and discussion of STL, see Wikipedia.
- state transition event
A change in state (e.g. healthy to infected, undiagnosed to positive diagnosis, or birth) that may trigger a subsequent action, often an intervention. “Campaign events” should not be confused with state transition events.
- time step
A discrete number of hours or days in which the “simulation states” of all “simulation objects” (interventions, infections, immune systems, or individuals) are updated in a simulation. Each time step will complete processing before launching the next one. For example, a time step would process the migration data for populations moving between nodes via rail, airline, and road. The migration of individuals between nodes is the last step of the time step after updating states.
- tutorial
A set of instructions in the Quick Start documentation to learn more about epidemiology and disease modeling. Tutorials are based on real-world scenarios and demonstrate the mechanics of the the model. Each tutorial consists of one or more scenarios.
- working directory
The directory that contains the configuration and campaign files for a simulation. You must be in this directory when you invoke Eradication.exe at the command line to run a simulation.
Epidemiology terms¶
The following terms are used to describe general concepts and processes in the field of epidemiology and disease modeling.
- antigen
A substance that is capable of inducing a specific immune response and that evokes the production of one or more antibodies.
- Clausius-Clayperon relation
A way of characterizing a transition between two phases of matter; provides a method to find a relationship between temperature and pressure along phase boundaries. Frequently used in meteorology and climatology to describe the behavior of water vapor. See Wikipedia - Clausius-Clayperon relation for more information.
- deterministic
Characterized by the output being fully determined by the parameter values and the initial conditions. Given the same inputs, a deterministic model will always produce the same output.
- diffusive migration
The diffusion of people in and out of nearby nodes by foot travel.
- epitope
The portion of an antigen that the immune system recognizes. An epitope is also called an antigenic determinant.
- Euler method
Used in mathematics and computational science, this method is a first-order numerical procedure for solving ordinary differential equations with a given initial value.
- exp(
The exponential function, \(e^x\), where \(e\) is the number (approximately 2.718281828) such that the function \(e^x\) is its own derivative. The exponential function is used to model a relationship in which a constant change in the independent variable gives the same proportional change (i.e. percentage increase or decrease) in the dependent variable. The function is often written as \(exp(x)\). The graph of \(y = exp(x)\) is upward-sloping and increases faster as \(x\) increases.
- herd immunity
The resistance to the spread of a contagious disease within a population that results if a sufficiently high proportion of individuals are immune to the disease, especially through vaccination.
- incidence
The rate of new cases of a disease during a specified time period. This is a measure of the risk of contracting a disease.
- Koppen-Geiger Climate Classification System
A system based on the concept that native vegetation is a good expression of climate. Thus, climate zone boundaries have been selected with vegetation distribution in mind. It combines average annual and monthly temperatures and precipitation, and the seasonality of precipitation. The DTK has several options for configuring the climate, namely air temperature, rainfall, and humidity. One option utilizes Input Files that associate geographic nodes with Koppen climate indices. The modified Koppen classification uses three letters to divide the world into five major climate regions (A, B, C, D, and E) based on average annual precipitation, average monthly precipitation, and average monthly temperature. Each category is further divided into sub-categories based on temperature and precipitation. While the Koppen system does not take such things as temperature extremes, average cloud cover, number of days with sunshine, or wind into account, it is a good representation of our earth’s climate.
- loss to follow-up (LTFU)
Patients who at one point were actively participating in disease treatment or clinical research, but have become lost either by error or by becoming unreachable at the point of follow-up.
- ordinary differential equation (ODE)
A differential equation containing one or more functions of one independent variable and its derivatives.
- prevalence
The rate of all cases of a disease during a specified time period. This is a measure of how widespread a disease is.
- reproductive number
In a fully susceptible population, the basic reproductive number R:sub:0is the number of new cases generated by one infectious case over the course of the infectious period. The effective reproductive number takes into account non-susceptible individuals.
- routine immunization (RI)
The standard practice of vaccinating the majority of susceptible people in a population against vaccine-preventable diseases.
- stochastic
Characterized by having a random probability distribution that may be analyzed statistically but not predicted precisely.
- subpatent
When an individual is infected but asymptomatic, so the infection is not readily detectable.
- SEIR model
A generic epidemiological model that provides a simplified means of describing the transmission of an infectious disease through individuals where those individuals can pass through the following five states: susceptible, exposed, infectious, and recovered.
- SEIRS model
A generic epidemiological model that provides a simplified means of describing the transmission of an infectious disease through individuals where those individuals can pass through the following five states: susceptible, exposed, infectious, recovered, and susceptible.
- SI model
A generic epidemiological model that provides a simplified means of describing the transmission of an infectious disease through individuals where those individuals can pass through the following five states: susceptible and infectious.
- SIR model
A generic epidemiological model that provides a simplified means of describing the transmission of an infectious disease through individuals where those individuals can pass through the following five states: susceptible, infectious, and recovered.
- SIRS model
A generic epidemiological model that provides a simplified means of describing the transmission of an infectious disease through individuals where those individuals can pass through the following five states: susceptible, infectious, recovered, and susceptible.
- SIS model
A generic epidemiological model that provides a simplified means of describing the transmission of an infectious disease through individuals where those individuals can pass through the following five states: susceptible, infectious, and susceptible.
- supplemental immunization activity (SIA)
In contrast to routine immunization (RI), SIAs are large-scale operations with a goal of delivering vaccines to every household.
- WAIFW matrix
A matrix of values that describes the rate of transmission between different population groups. WAIFW is an abbrevation for Who Acquires Infection From Whom.
EMOD source code installation¶
This section describes how to install the software needed to build the EMOD executable (Eradication.exe) or Eradication binary from the EMOD source code. This is necessary if you want to modify the source code to extend the capabilities of the model beyond what’s available with the latest EMOD release. For example, you may want to model a disease that isn’t currently supported in EMOD. You can build Eradication.exe from source code on computers running Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit) or build the Eradication binary on computers running CentOS 7.1 on Azure.
After building, you should run a single simulation to verify basic functionality. We recommend the 27_Vector_Sandbox scenario in the Regression directory, which is a simple five-year vector simulation with an indoor residual spraying (IRS) campaign in the third year, executed on a single-node geography that is based on Namawala, Tanzania. This simulation generally takes a few minutes to execute.
However, you can run a simulation using any of the subdirectories under Regression, which when used with the input data files provided by IDM, contain complete sets of files for EMOD simulations. See Run simulations and Use input data files for more information.
After that, we recommend running full regression tests to further verify that EMOD is behaving as expected and that none of the source code changes inadvertently changed the EMOD functionality. See Regression testing for more information.
The EMOD executable (Eradication.exe) is tested using Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit). Windows HPC Server is used for testing remote simulations on a high-performance computing (HPC) cluster and the other Windows operating systems are used to test local simulations.
The Eradication binary is tested and supported on a CentOS 7.1 on Azure virtual machine. It has also been successfully built and run on Ubuntu, SUSE, and Arch, but has not been tested and is not supported on those Linux distributions.
Prerequisites for working with EMOD source code¶
This section describes the software packages or utilities must be installed to build the EMOD executable (Eradication.exe) or Eradication binary from source code and run regression tests. It assumes you have already installed the required software to run EMOD simulations. If you have not, see EMOD installation.
If additional software is needed for the prerequisite software due to your specific environment, the installer for the prerequisite software should provide instructions. For example, if Microsoft MPI v8 requires additional Visual C++ redistributable packages, the installer will display that information.
Note
IDM does not provide support or guarantees for any third-party software, even software that we recommend you install. Send feedback if you encounter any issues, but any support must come from the makers of those software packages and their user communities.
Install prerequisites for building Eradication.exe¶
The following software packages are required to build the Eradication.exe from EMOD source code on Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit).
Visual Studio¶
Purchase a license from Microsoft or use an MSDN subscription to install Visual Studio 2015 (Professional, Premium, or Ultimate).
While you can use a free copy of Visual Studio Community, IDM does not test on or support this version.
Select the Visual C++ tools for Windows desktop during installation.
Python¶
Python is required for building the disease-specific Eradication.exe and running Python scripts.
Note
EMOD does not support the current version of Python.
Install Python 2.7.11 or 2.7.12. See https://www.python.org/downloads/ for instructions.
In the Customize Python dialog box, verify that Add python.exe to PATH is selected to add Python to the PATH environment variable on your computer.
From Control Panel, select Advanced system settings, and then click Environment Variables.
Add a new variable called IDM_PYTHON_PATH and set it to the directory where you installed Python, and then click OK.
Open a Command Prompt window and type the following to verify installation:
python --version
The Python package manager, pip, is installed as part of Python 2.7.11 or 2.7.12 and is used to install other software packages.
HPC SDK¶
Install the Microsoft HPC Pack 2012 SDK (64-bit). See https://www.microsoft.com/en-us/download/details.aspx?id=36043 for instructions.
Boost¶
Go to https://sourceforge.net/projects/boost/files/boost/1.61.0/ and select one of the compressed files.
Unpack the libraries to the location of your choice.
From Control Panel, select Advanced system settings, and then click Environment Variables.
Add a new variable called IMD_BOOST_PATH and set it to the directory where you installed Boost, and then click OK.
SCons¶
SCons is required for the building disease-specific Eradication.exe and is optional for the monolithic Eradication.exe that includes all simulation types.
Go to http://www.lfd.uci.edu/~gohlke/pythonlibs#scons and select the WHL file for SCons 2.5.0 that is compatible with Python 2.7.11 or 2.7.12.
Save the file to your Python installation directory.
Open a Command Prompt window and navigate to the Python installation directory, then enter the following, substituting the name of the specific matplotlib WHL file you downloaded:
pip install scons-2.x.x-py2-none-any.whl
Install prerequisites for building the Eradication binary¶
For CentOS 7.1 on Azure, all prerequisites for building the Eradication binary are installed by the setup script described in Install EMOD on CentOS on Azure. If you originally installed EMOD without including the source code and input data files that are optional for running simulations using a pre-built Eradication binary, rerun the script and install those.
Install prerequisites for running regression tests¶
The following plotting software is required for running regression tests, where graphs of model output are created both before and after source code changes are made to see if those changes created a discrepancy in the regression test output. For more information, see Regression testing. For CentOS 7.1 on Azure, all Python packages are installed by the setup script, but you may want to install R or MATLAB.
We recommended that you download some of the Python packages from http://www.lfd.uci.edu/~gohlke/pythonlibs, a page compiled by Christoph Gohlke, University of California, Irvine. The libraries there are compiled Windows binaries, including the 64-bit versions required by EMOD.
Python utilities¶
The Python utilities dateutil, six, and pyparsing provide text parsing and datetime functionality.
Open a Command Prompt window.
Enter the following commands:
pip install python-dateutil pip install pyparsing
NumPy¶
The NumPy package adds support for large, multi-dimensional arrays and matrices to Python.
Go to http://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy and select the WHL file for NumPy 1.11.3 (64-bit) that is compatible with Python 2.7.11 or 2.7.12.
Save the file to your Python installation directory.
Open a Command Prompt window and navigate to the Python installation directory, then enter the following, substituting the name of the specific NumPy WHL file you downloaded:
pip install numpy-1.x.x+mkl-cp27m-win_amd64.whl
Matplotlib¶
Matplotlib is a Python library for making publication quality plots using syntax familiar to MATLAB users. Matplotlib also uses NumpPy for numeric manipulation. Output formats include PDF, Postscript, SVG, and PNG, as well as a screen display.
Go to http://www.lfd.uci.edu/~gohlke/pythonlibs/#matplotlib and select the WHL file for Matplotlib 1.5.3 (64-bit) that is compatible with Python 2.7.11 or 2.7.12.
Save the file to your Python installation directory.
Open a Command Prompt window and navigate to the Python installation directory, then enter the following, substituting the name of the specific matplotlib WHL file you downloaded:
pip install matplotlib-1.x.x+mkl-cp27m-win_amd64.whl
R¶
The IDM test team uses R 3.2.0 (64-bit) for regression testing, but it is considered optional.
R is a free software environment for statistical computing and graphics.
Go to https://www.r-project.org/ and install R 3.2.0 (64-bit).
MATLAB¶
The IDM test team uses MATLAB R2015a and the MATLAB Statistics and Machine Learning Toolbox™ R2015a for regression testing, but they are both considered optional.
MATLAB is a high-level language and interactive environment for numerical computation, visualization, and programming. The MATLAB Statistics and Machine Learning Toolbox™ provides functions and applications to describe, analyze and model data using statistics and machine learning algorithms.
Go to http://www.mathworks.com/products/matlab/ and install MATLAB R2015a.
If desired, go to https://www.mathworks.com/products/statistics.html and install the MATLAB Statistics and Machine Learning Toolbox™ R2015a.
Download the EMOD source code¶
The EMOD source code is available on GitHub. The EMOD source includes the source code, Visual Studio solution, sample configuration files, as well as regression test and other files needed to fully build and test the EMOD executable (Eradication.exe).
You can have multiple versions of the EMOD source code in separate directories on your local computer. For example, you might want to download a new release of EMOD but also keep a previous release of the source. In the following examples, the source code is downloaded to the directory EMOD at C:/IDM, but you can save to any location you want.
You can use a Git client of your choice to download from GitHub, however, these instructions show how to use Git GUI and Git Bash.
Install Git GUI and Git Bash¶
To install Git GUI and Git Bash, download a 64-bit version of Git from https://git-scm.com/download. On the Select Components installer window, you can select one or both of Git GUI Here for a GUI or Git Bash Here for a command window.
Use Git GUI to download the EMOD source¶
Launch the Git GUI application and click Clone Existing Repository.
From the Clone Existing Repository window:
In Source Location, enter https://github.com/InstituteforDiseaseModeling/EMOD
In Target Directory, enter the location and target directory name: C:/IDM/EMOD
Click Clone. Git GUI will create the directory and download the source code.
Close the Git GUI window when the download completes.
Use Git Bash to download the EMOD source¶
Note
For a list of the Git Bash commands, you can type git help git from Git Bash, or git help
<command> for information about a specific command.
Launch the Git Bash application. From the command line:
Go to the location where you want your copy of the EMOD source located:
cd C:\IDM
Clone the repository from GitHub:
git clone https://github.com/InstituteforDiseaseModeling/EMOD
Git Bash will copy the EMOD source to a directory named EMOD by default as a different directory name was not specified after the URL.
Verify that all directories on https://github.com/InstituteforDiseaseModeling/EMOD are now reflected on your local clone of the repository. The table below describes each of the directories.
Directory |
Description |
|---|---|
Dependencies |
The ComputeClusterPack. |
Eradication |
Eradication project. Main project for Visual Studio solution. |
Regression |
Scripts to perform regression tests for modified code. It also includes a copy of the Quick Start Scenarios directory that contains simulation configuration, batch, input, and script files that are associated with the training tutorials. |
Scripts |
Scripts used in file creation. |
UnitTest++ |
Software for early release of additional regression testing. |
baseReportLib |
Static library of classes used by EMOD built-in reports and custom reports. |
cajun |
Cajun C++ API for JavaScript Object Notation (JSON) project. |
campaign |
Campaign project. |
componentTests |
Tests that work in conjunction with the UnitTest++ directory. |
interventions |
Interventions project. |
rapidjson |
Rapid JSON project. |
reporters |
Collection of custom reporter projects. |
snappy |
Compression utilities used by the EMOD software. |
utils |
Miscellaneous utilities. |
Additionally, the repository includes additional files, such as the Visual Studio solution file, SCons scripts, the README, and more.
Build EMOD from source code¶
You can build the Eradication.exe for Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit) using Microsoft Visual Studio or SCons. You can build the Eradication binary for CentOS 7.1 on Azure using SCons.
If you want full debugging support, you must build using Visual Studio. However, Visual Studio is only capable of a monolithic build that includes all supported simulation types.
EMOD supports the following simulation types for modeling a variety of diseases:
Generic disease (GENERIC_SIM)
Vector-borne diseases (VECTOR_SIM)
Malaria (MALARIA_SIM)
Tuberculosis (TB_SIM)
Sexually transmitted infections (STI_SIM)
HIV (HIV_SIM)
If you want to create a disease-specific build, you must build using SCons. However, SCons builds build only the release version without extensive debugging information.
Build a monolithic Eradication.exe with Visual Studio¶
You can use the Microsoft Visual Studio solution file in the EMOD source code repository to build the monolithic version of the EMOD executable (Eradication.exe), which can be either a release or debug build.
Open the EradicationKernel solution in Visual Studio.
From the ** Solution Configurations** ribbon, select Debug or Release.
On the Build menu, select Build Solution.
Eradication.exe will be in a subdirectory of the Eradication directory.
Build Eradication.exe or Eradication binary with SCons¶
SCons is a software construction tool that is an alternative to the well-known “Make” build tool. It is implemented in Python and the SCons configuration files, SConstruct and SConscript, are executed as Python scripts. This allows for greater flexibility and extensibility, such as the creation of custom SCons abilities just for EMOD. For more information on Scons, see www.scons.org.
Open a command window.
Go to the directory where EMOD is installed:
cd C:\IDM\EMOD
Run the following command to build Eradication.exe:
For a monolithic build:
scons --Release
For a disease-specific build, specify one of the supported disease types using the
--Diseaseflag:scons --Release --Disease=Vector
The executable will be placed, by default, in the subdirectory build\x64\Release\Eradication\ of your local EMOD source.
Additionally, you can parallelize the build process with the --jobs flag. This flag indicates
the number of jobs that can be run at the same time (a single core can only run one job at a time).
For example:
scons --Release --Disease=Vector --jobs=4
EMOD architecture¶
Epidemiological MODeling software (EMOD) is implemented in C++ and has two subsystems: the environment and the simulation controller. the environment contains the interfaces to the simulation controller subsystem and the external inputs and outputs. the simulation controller contains the epidemiological model (simulation and campaign management), and reporters that capture output data and create reports from a simulation. The following figure shows a high-level view of the system components of EMOD and how they are related to each other.
EMOD system components¶
Warning
If you modify the source code to add or remove configuration or campaign parameters, you may need to update the code used to produce the schema. You must also verify that your simulations are still scientifically valid.
Environment subsystem¶
The environment subsystem provides access to global resources and most of the external input and output interfaces. Output reports are the only output not handled through the environment subsystem. It consists of a a singleton utility class, Environment. The environment subsystem consists of five logical components.
The following figure shows a high-level view of the system components of EMOD and how they are related to each other.
EMOD system components¶
Input file readers¶
Provide small utility functions for reading in the input data, configuration, and campaign files. The actual parsing of the configuration and campaign files is done by the configuration manager component. The parsing of the input data files is done by the model classes that consume that data, which are part of the simulation controller subsystem.
Configuration manager¶
Parses the configuration files, stores the parsed values for system-global configuration values, and provides a central container resource for the configuration as JSON to those classes that need to parse out the remaining configuration values locally for themselves. It retains the contents of the configuration file and the directories provided on the command line.
Error handler¶
Provides an application-level exception library and a centralized mechanism for handling all errors that occur during program execution. These errors are ultimately reported through the logging component.
Logger¶
Writes the output logs and errors. Output reports, such as time-series channel data reports, spatial channel data reports, progress and status summary, and custom reports, are handled by the simulation controller. For information and setting the logging level, see Set log levels.
Message Passing Interface (MPI)¶
EMOD is designed to support large-scale multi-node simulations by running multiple instances of EMOD in parallel across multiple compute nodes on a cluster. During initialization, geographical nodes are assigned to compute nodes. Individuals who migrate between geographical nodes that are not on the same compute node are migrated via a process of serialization, network I/O, and deserialization. The network communication is handled through a mixture of direct calls to the MPI library and use of Boost’s MPI facilities. This component provides the system-wide single interface to MPI, caching the number of tasks and rank of current process from the MPI environment.
Simulation controller subsystem¶
The simulation controller is the top-level structure for the epidemiological model. The controller’s capabilities are simple, running a single simulation in a single time direction at a constant rate. It exists to support future capabilities, such as running multiple simulations, pausing a simulation, or bootstrapping a simulation from an archived simulation. It contains two components: simulation and reporters.
The following figure shows a high-level view of the system components of EMOD and how they are related to each other.
EMOD system components¶
Simulation¶
The simulation component contains core functionality that models the behavior of a disease without any interventions and extended functionality to include migration, climate, or other input data to create a more realistic simulation. Disease transmission may be more or less complex depending on the disease being modeled.
Campaign management¶
The simulation component also includes a campaign manager sub-component for including disease interventions in a simulation.
Reporter¶
The reporter component creates output reports for both simulation-wide aggregate reporting and spatial reporting.
Simulation core components¶
The simulation component contains core functionality that models the behavior of a disease without any interventions and extended functionality to include migration, climate, or other input data to create a more realistic simulation. Disease transmission may be more or less complex depending on the disease being modeled.
Warning
If you modify the source code to add or remove configuration or campaign parameters, you may need to update the code used to produce the schema. You must also verify that your simulations are still scientifically valid.
Each generic EMOD simulation contains the following core base classes:
- Simulation
Created by the simulation controller via a SimulationFactory with each run of EMOD.
- Node
Corresponds to a geographic area. Each simulation maintains a collection of one or more nodes.
- IndividualHuman
Represents a human being. Creates Susceptibility and Infection objects for the collection of individuals it maintains. The file name that defines this class is “Individual” and you may see it likewise shortened in diagrams.
- Susceptibility
Manages an individual’s immunity.
- Infection
Represents an individual’s infection with a disease.
For generic simulations, human-to-human transmission uses a homogeneous contagion pool for each node. Every individual in the node sheds disease into the pool and acquires disease from the pool. For specific disease simulations, transmission is heterogeneous and based on the disease biology.
The relationship between these classes is captured in the following figure.
Simulation components¶
After the simulation is initialized, all objects in the simulation are updated at each time step, typically a single day. Each object implements a method Update that advances the state of the objects it contains, as follows:
Controller updates Simulation
Simulation updates Nodes
Node updates IndividualHuman
IndividualHuman updates Susceptibility, Infections, and InterventionsContainer
InterventionsContainer updates Interventions
As a stochastic model, EMOD uses a random number seed for all simulations. The Simulation object has a data member (RNG) that is an object maintaining the state of the random number generator for the parent Simulation object. The only generator currently supported is pseudo-DES. The random seed is initialized from the configuration parameter Run_Number and from the process MPI rank. All child objects needing access to the RNG must be provided an appropriate (context) pointer by their owners.
The Simulation class contains the following methods:
Method |
Description |
|---|---|
Populate() |
Initializes the simulation. The Populate method initializes the simulation using both the configuration file and the demographic files. Populate calls through to populateFromDemographics to enable the Simulation object to create one or many Node objects populated with IndividualHumans as dictated by the demographics file, in conjunction with the sampling mode and value dictated by the configuration file. If the configuration file indicates that a migration and a climate model are to be used, those input file are also read. Populate also initializes all Reporters. |
Update() |
Advances the state of nodes. |
Simulation object hierarchy¶
For multi-core parallelization, the demographics file is read in order on each process and identity of each node and is compared with a policy assigning nodes to processes embodied in objects implementing InitialLoadBalancingScheme. If the initial load balancing scheme allows a node for the current rank, the node is created via addNewNodeFromDemographics. After all nodes have been created and propagated, the NodeRankMaps are merged across all processes. See Load-balancing file structure for more information.
Nodes are model abstractions that represent a population of individuals that interact in a way that does not depend on their geographic location. However, they represent a geographic location with latitude and longitude coordinates, climate information, migration links to other nodes, and miscellaneous demographic information. The Node is always the container for IndividualHumans and the contagion pool. The Node provides important capabilities for how IndividualHumans are created and managed. It can also contain a Climate object and Migration links if those features are enabled. The climate and migration settings are initialized based on the information in the input data files.
The Node class contains the following methods:
Method |
Description |
|---|---|
PopulateFromDemographics() |
The entry point that invokes populateNewIndividualsFromDemographics(InitPop), which adds individuals to a simulation and initializes them. PopulateNewIndividualsFromBirth() operates similarly, but can use different distributions for demographics and initial infections. |
Update() |
Advances the state of individuals. |
updateInfectivity() |
The workhorse of the simulation, it processes the list of all individuals attached to the Node object and updates the force of infection data members in the contagion pool object. It calls a base class function updatePopulationStatistics, which processes all individuals, sets the counters for prevalence reporting, and calls IndividualHuman::GetInfectiousness for all IndividualHuman objects. The code in GetInfectiousness governs the interaction of the IndividualHuman with the contagion pool object. The rest of the code in updateInfectivity processes the contagion beyond individual contributions. This can include decay of persisting contagion, vector population dynamics, seasonality, etc. This is also where the population-summed infectivity must be scaled by the population in the case of density-independent transmission. |
updateVitalDynamics() |
Manages community level vital dynamics, primarily births, since deaths occur at the individual level. |
By default, an IndividualHuman object is created, tracked, and updated for every person within a node. To reduce memory usage and processing time, you may want to sample such that each IndividualHuman object represents multiple people. There are several different sampling strategies implemented, with different strategies better suited for different simulations. See Sampling for more information.
If migration is enabled, at the end of the Node update, the Node moves all migrating individuals to a separate migration queue for processing. Once the full simulation time step is completed, all migrating individuals are moved from the migration queue and added to their destination nodes.
The IndividualHuman class corresponds to human beings within the simulation. Individuals are always contained by a Node object. Each IndividualHuman object may represent one or more human beings, depending on the sampling strategy and value chosen.
The IndividualHuman class contains components for susceptibility, infection, and interventions. Infection and Susceptibility cooperate to represent the detailed dynamics of infection and immune mechanisms. Every IndividualHuman contains a Susceptibility object that represents the state of the immune system over time. Only an infected IndividualHuman contains an Infection object, and may contain multiple Infection objects.. Susceptibility is passed to initialize the infection immunology in Infection::InitInfectionImmunology(). The state of an individual’s susceptibility and infection are updated with Update() methods. Disease-specific models have additional derived classes with properties and methods to represent specifics of the disease biology.
The InterventionsContainer is the mediating structure for how interventions interrupt disease transmission or progression. Campaign distribution results in an Intervention object being added to an individual’s InterventionsContainer, where it remains unless and until it is removed. When an IndividualHuman calls Update(), the InterventionsContainer is updated and its effects are applied to the IndividualHuman. These effects are used in the individual, infection, and susceptibility update operations. If migration is enabled, at the end of each individual’s update step EMOD checks if the individual is scheduled for migration (IndividualHuman::CheckForMigration()), setting a flag accordingly.
The IndividualHuman class contains the following methods:
Method |
Description |
|---|---|
Update() |
Advances the state of both the infection and the immune system and then registers any necessary changes in an individual’s state resulting from those dynamics (that is, death, paralysis, or clearance). It also updates intrinsic vital dynamics, intervention effects, migration, and exposure to infectivity of the appropriate social network. |
ExposeToInfectivity() |
Passes the IndividualHuman to the ExposeIndividual() function if it is exposed to infectivity at a time step. |
UpdateInfectiousness() |
Advances the quantity of contagion deposited to the contagion pool by an IndividualHuman at each time step of their infectious period. This is explained in more detail below. |
Transmission of disease is mediated through a pool mechanism which tracks abstract quantities of contagion. The pool mediates individual acquisition and transmission of infections as well as external processes that modify the infectivity dynamics external to individuals. The pool provides basic mechanisms for depositing, decaying, and querying quantities of contagion which are associated with a specific StrainIdentity. The pool internally manages a separate ContagionPopulation for each possible antigen identity. ContagionPopulations have further structure and manage an array of contagion quantities for each substrain identity.
Each IndividualHuman has a sampling weight \(W_i\) and a total infectiousness \(X_i\), the rate at which contacts with the infectious individual become infected. This rate can be modified by transmission-reducing immunity or heterogeneous contact rates, which are gathered in \(Y_{i,transmit}\), and the transmission-reducing effects of interventions, such as transmission- blocking vaccines in the factor \(Z_{i,transmit}\). The sampling weight \(W_i\) is not included in the probability of acquiring a new infection. Sample particles are simulated as single individuals, their weighting \(W_i\) is used to determine their effects upon the rest of the simulation.The total infectiousness \(T\) of the local human population is then calculated as:
For simulation of population density-independent transmission, individual infectiousness \(X_i\) includes the average contact rate of the infectious individual, so this total infectiousness is divided by the population \(P\) to get the force of infection \(FI=\frac{T}{P}\) for each individual in the population. The base rate of acquisition of new infections per person is then \(FI\), which can be modified for each individual \(I\) by their characteristics \(Y_{i,acquire}\) and interventions \(Z_{i,acquire}\). Over a time step \(\Delta t\), the probability of an individual acquiring a new infection is then:
A new infection receives an incubation period and infectious period from the input configuration (a constant at present, but possibly from specified distributions in the future) and a counter tracks the full latency, which is possible when simulating individual particles. After the incubation period, the counter for the infectious period begins, during which time the infection contributes to the individual’s infectiousness \(X_i\).
Campaign management¶
Campaigns are structured into campaign events that determine when, where, and to whom the intervention will be distributed and interventions that determine what is distributed, for example vaccines or other treatments. This section describes the software architecture used for managing campaigns.
Campaigns can be very simple, such as a single intervention with fixed parameters at a point in time, or a complex, adaptive, repetitive, and responsive combination of interventions. A Campaign is a collection of events that modify a simulation. An Event is a distribution within a campaign, and an Intervention is an item that is given out, such as a vaccine, a drug or a bednet.
Warning
If you modify the source code to add or remove configuration or campaign parameters, you may need to update the code used to produce the schema. You must also verify that your simulations are still scientifically valid.
Contents
A campaign event triggers the campaign management system to evaluate when, where, and to whom the intervention will be distributed. This section describes the SimulationEventContext, CampaignEvent, NodeSet, and EventCoordinator classes used to manage this process.
For more information on setting up campaign files, see Create a campaign file.
The Simulation class has a nested helper class called SimulationEventContextHost, referred to as SimulationEventContext. It serves as the interface to, or manager of, CampaignEvents for the Simulation class.
Incoming: The Simulation to SimulationEventContext interface contains the following methods:
Method |
Description |
|---|---|
LoadCampaignFromFile() |
Loads the campaign file during simulation initialization (t=0). |
RegisterEventCoordinator() |
Registers new event coordinators. Also used by CampaignEvent during activation to notify the SimulationEventContext of a new active EventCoordinator. |
Update() |
Advances the state at each time step. |
VisitNodes() |
Called from CampaignEvent during its activation. CampaignEvent is not a Node container, so it needs to communicate with the Simulation class to do anything with nodes. |
Outgoing: The SimulationEventContext communicates with CampaignEvents and EventCoordinators, which are described below.
The CampaignEvent class exists primarily as an initialization-time, minimal intelligence container with a 1-to-1 mapping for CampaignEvents found in the JSON campaign file. They do not do much in the way of run-time campaign distribution or control.
Incoming: The public interface for CampaignEvent contains the following methods:
Method |
Description |
|---|---|
CreateInstance() |
For each campaign event that the SimulationEventContext finds in the campaign file, it creates a corresponding CampaignEvent instance via CampaignEventFactory. The nested JSON elements in a campaign event are stored as an opaque (that is, unparsed) JSON object known as Event_Coordinator_Config. Immediate parameters like Start_Day are parsed out of the JSON and stored in explicit variables in the CampaignEvent class. |
Dispatch() |
In its steady-state, the SimulationEventContext checks the start day for all existing CampaignEvents and invokes this method to when the time step matches the start day. |
Outgoing: The CampaignEvent communicates with two other classes: NodeSet and EventCoordinator.
The NodeSet class parses the Nodeset_Config and helps the EventCoordinator determine if a given node is included in a particular intervention distribution. It can be as simple as NodeSetAll, which includes all nodes, or something much more involved. Usual cases include NodeSetPolygon and NodeSetCommunityList.
Incoming: The public interface for NodeSet contains the following methods:
Method |
Description |
|---|---|
Contains() |
The caller passes a Node via the INodeEventContext interface and gets back a Boolean. The NodeSet class completely encapsulates whatever logic is used to evaluate node membership. |
EventCoordinator is a base type that contains most of the functionality in the event distribution mechanism. There are two actual EventCoordinator classes implemented, but you can new implementations easily by creating a new EventCoordinator class.
Incoming: There are four classes or class groups that make calls into EventCoordinator:
CampaignEvents, which create and activate them.
The SimulationEventContext that invokes their steady-state methods.
Nodes (via the NodeEventContext helper class)
Interventions, which get EventCoordinator-level configuration data needed for intervention execution.
The public interface for EventCoordinator contains the following methods:
Method |
Description |
|---|---|
AddNode() |
Invoked by CampaignEvent::Dispatch() to allow the EventCoordinator to act as a node container and have access to all its constituent nodes via the INodeEventContext interface. Note The AddNode calls actually come via a delegate function that is in the EventCoordinator, but is invoked from the VisitNodes method up in the SimulationEventContext. The CampaignEvent passes the delegate function it wants used when it calls SimulationEventContext::VisitNodes() . This circuitous journey is needed because EMOD operates on a node-by-node basis and the SimulationEventContext, not the CampaignEvent, is the primary node container. |
CreateInstance() |
During their instantiation, CampaignEvents create EventCoordinators as the CampaignEvents parse the Event_Coordinator_Config, which specifies the class name and is passed by SimulationEventContext. Nothing then happens until CampaignEvent::Dispatch() is called. |
IsFinished() |
When an EventCoordinator determines that it is finished distributing its interventions, it sets an internal flag. The SimulationEventContext queries the IsFinished() function on each registered EventCoordinator and disposes of it if true. An EventCoordinator can activate and complete in a single time step, or it could last the entire length of the simulation. |
Update() |
The SimulationEventContext calls this on all registered EventCoordinators to advance their state at each time step. This method exists for global EventCoordinator communication and logic. |
UpdateNodes() |
Distributes the actual intervention. For the simplest possible use case, an EventCoordinator will distribute an intervention on its start day and then finish in that same time step. However, an EventCoordinator may implement repeating interventions, phased distributions, or sustained distributions that are contingent on node or individual attributes. |
Outgoing: The outgoing function calls consist of the distribution of the intervention either to individuals or nodes. For the interface between the EventCoordinator and the actual Intervention, the EventCoordinator calls InterventionFactory and passes it the remaining unparsed JSON from the campaign file. Namely, this is the Intervention_Config, the actual intervention-level campaign parameters including the intervention class. The InterventionFactory returns the newly created intervention instance for each individual via a one of two types of IDistributableIntervention interfaces.
Interventions are the actual objects aimed at reducing the spread of disease, such as a vaccine or drug. THey can be either distributed to individuals or to nodes. For example, a vaccine is an individual-distributed intervention and a larvicide is a node-distributed intervention. Intervention is an abstract type class and specific interventions are classes that implement either IDistributableIntervention, for individual-distributed interventions, or INodeDistributableIntervention, for node-distributed interventions.
The determination of whether an intervention is individual-distributed or node-distributed is contained by logic in InterventionFactory. At the beginning of the EventCoordinator::UpdateNodes()**method, the **InterventionFactory is queried with the unparsed JSON campaign file to see if it returns an INodeDistributableInterface pointer. If it does, the intervention is executed as a node-distributed intervention; if it does not, the individual- distributed intervention execution is used.
Incoming: The interface to the abstract type Intervention class is the Distribute() method. It functions slightly differently for each intervention type.
Outgoing: Intervention is an abstract type that interacts with Nodes or IndividualHumans with an interface specific to that intervention type. The intervention calls QueryInterface on the container to ask for a consumer interface, for example IBednetConsumer. If supported, a Give method specific to that intervention will be called, for example, GiveBednet(this) to give itself to this individual. It is then up to the internal IndividualHuman or Node logic to decide what to do with this intervention.
An individual-distributed intervention implements IDistributableIntervention, a container for the actual parameter name-value pairs from the campaign file, that is contained by an IndividualContainer, an IndividualHuman helper class. The EventCoordinator calls IDistributableIntervention::Distribute(), passing the pointer IIndividualHumanDistributionContext, which provides an ISupports interface to the individual by which the intervention can request a consumer interface. This interface can then be used with Give().
In the EventCoordinator::UpdateNodes() method, the EventCoordinator organizes the distribution of Interventions to IndividualHumans mediated by Nodes, which contain the IndividualHuman objects. The EventCoordinator also applies campaign parameters at the event coordinator level (for example, Target_Demographic, Demographic_Coverage, Num_Repetitions, and Days_Between_Reps) which mainly consists of filtering the distribution to individuals based on individual attributes.
A node-distributed intervention implements INodeDistributableIntervention, a container for the actual parameter name-value pairs from the campaign file, that is contained by a Node. The EventCoordinator calls INodeDistributableIntervention::Distribute(), passing the pointer INodeEventContext, which provides an ISupports interface to the individual by which the intervention can request a consumer interface. This interface can then be used with Give(). Similar to individual-distributed interventions, the EventCoordinator also applies campaign parameters for filtering the distribution.
The architectural diagram below illustrates how campaign file settings are processed by an EMOD simulation.
EMOD campaign architecture¶
Reporter component¶
After running simulations, EMOD creates output reports that contain the model results. Two methods of coordinated reporting are implemented: simulation-wide aggregated reporting and spatial reporting. See Output report structure for more information about the different output reports available.
Simulation-wide aggregate reporting is the most commonly used. This reporting method generates the output written to InsetChart.json. Conceptually, for each time step, the value of a named channel is derived from values provided for that channel by each node. The values are accumulated (summed) over all nodes and then transformed (often normalized by an internal parameter or another channel) just prior to writing. This is implemented through the simulation’s insetChartDataAccumulator.
Basic usage of the NodeTimestepDataAccumulator is explained in Report.h. The simulation is responsible for calling Begin/EndTimestep() and collecting and writing out the data at the end of the simulation. The accumulation calls occur in Node::accumulateInsetChartData().
The second method is spatial reporting which is facilitated by SpatialReporter. In spatial reporting, each node again produces values for named channels, but no simulation-wide accumulation takes place. Instead, the values of each channel for each node are written to a binary table (ReportNNNN.dat) where NNNN is the time step. The format of this file is simple and can be summarized as the maximally packed layout of this structure:
struct ReportDataFormat
{
int32_t num_nodes;
int32_t num_channels;
float data[num_nodes*num_channels];
}
Num_Channels is the number of user channels implicitly generated by the number of different channel names requested in calls to Node::reportSpatialDataReportChannels() plus two additional channels for longitude and latitude. JSON metadata for the ReportNNNN.dat files is written to Report.header.dat after the first time step. It does not include entries for latitude and longitude.
In general, the value of channel \(c\) for node \(n\), starting at zero, is found at \(data[n\times num\_channels+c]\). The latitude is \(data[n\times num\_channels+0]\) and the longitude is \(data[n\times num\_channels+1]\).
The report data files are written after every time step at the request of the Controller by calling WriteTimestep(). Under MPI, the default implementation reduces all the data to rank 0 and writes the combined data out to file on rank 0.
See Custom reporters for information about how to use a custom reporter.
Debugging and testing¶
When you build Eradication.exe or Eradication binary from the EMOD source code, it’s important to debug the code and run regression tests to be sure your changes didn’t inadvertently change EMOD functionality. You can run simulations directly from Visual Studio to step through the code, troubleshoot any build errors you encounter, and run the standard IDM regression tests or create a new regression test.
Warning
If you modify the source code to add or remove configuration or campaign parameters, you may need to update the code used to produce the schema. You must also verify that your simulations are still scientifically valid.
Set log levels¶
EMOD simulations output several files, including log files. See Error and logging files for more information on the logging files that are created by a simulation. By default, logging is at the “INFO” level, but you can set the level at which you want logging information generated. If you see redundant log messages, you can also throttle logging to eliminate them.
There are five log levels. The level chosen will log messages for that level and all higher levels (levels of smaller numeric value). You can set default log levels across the entire Eradication.exe or for individual files in the Eradication.exe; individual file settings will override the default. For example, if you want to increase logging for a particular file you are debugging without increasing logging across the entire Eradication.exe, you can set the default log level to “WARNING” and set the log level for the file to “DEBUG”. The standard output will reflect the default log level for all settings except “ERROR” or “WARNING”. For example:
Log-levels:
Default -> INFO
Eradication -> INFO
The following log levels are available:
- ERROR (1)
This is the highest level. Only errors, including critical errors, are logged to standard output.
- WARNING (2)
Warnings and errors are logged to standard output.
- INFO (3)
This is the default logging level for the executable and is set implicitly. Informational messages, warnings, and errors are logged to standard output.
- DEBUG (4)
Debug information, informational messages, warnings, and errors are logged to standard output. Debug level logging messages do not require a debug build of Eradication.exe. This setting will generate a large number of messages and may impact performance. If you need the debugging messages, we recommend that you limit the number of files with this setting and not set it as the default across the entire Eradication.exe.
- VALID (5)
This is the lowest level. Validation information, debug information, informational messages, warnings, and errors are logged to standard output. This log level is for very low-level debugging of specific values, including values in tight loops. Because it could severely impact performance, this level will only output to standard output during a debug build of Eradication.exe.
Set default Eradication.exe level¶
To set the default log level across the entire Eradication.exe, add the parameter logLevel_default to your configuration file and set it to the log level desired. For example:
{
"logLevel_default": "WARNING"
}
Set level for individual files¶
You can set the log level for an individual file, if it supports the ability. This is typically only used for debugging after making source code changes. This setting will override the default set using logLevel_default, whether set to a higher or lower level.
In the C++ files that make up the EMOD source code, open the file for which you want to set the log level.
Search for
static const char * _module.“Module” refers to the C++ file and is not the same as an EMODule. If this string isn’t present, you cannot set a log level for the file.
Look for logging macros in the file, such as LOG_WARN(x).
If macros are present, this indicates that the file supports that log level setting. The file may not support all log levels. Logging macros can be found in utils/Log.h. You can also add your own logging messages to the file using the logging macros.
In the configuration file, add the logLevel_<FileName> parameter with the log level desired. For example:
{ "logLevel_SimulationVectorExport":"DEBUG" }
Throttle redundant logging¶
It’s possible that multiple identical logging messages are generated by a file of Eradication.exe. This is normal behavior, but the verbosity can be unwanted or unnecessary. You can eliminate duplicate messages by turning on “throttling”, which retains only one logging message instead of a series of duplicate messages from each file.
Only one copy of the message will be generated when it is one of a series of duplicates from the same file. The identical messages need not be output one right after one another to be throttled. If an identical message is output from a different file, it will still be generated. Throttling can only be enabled across the entire Eradication.exe, not per file. It is off by default.
To enable throttling, add the following parameter and value to your configuration file:
{
"Enable_Log_Throttling": 1
}
For example, the following log messages are seen with throttling turned off:
00:00:00 [0] [D] [FileA] identical message: I'm in FileA
00:00:00 [0] [D] [FileB] another message from B
00:00:00 [0] [D] [FileA] identical message: I'm in FileA
00:00:00 [0] [D] [FileB] different message from B
00:00:00 [0] [D] [FileA] identical message: I'm in FileA
00:00:00 [0] [D] [FileB] yet another message from B.
00:00:00 [0] [D] [FileA] identical message: I'm in FileA
With throttling on, the repeated messages from file A are removed, even though they are intermixed with other log messages from file B:
00:00:00 [0] [D] [FileA] identical message: I'm in FileA
00:00:00 [0] [D] [FileB] another message from B
00:00:00 [0] [D] [FileB] different message from B
00:00:00 [0] [D] [FileB] yet another message from B.
Run debug simulations in Visual Studio¶
If you have modified the EMOD source code, you can run simulations directly from Visual Studio as part of debugging your changes by using the built-in debugger. For example, you may want to run one or more of the simulations in the Regression directory to verify that the results match those obtained prior to your changes.
Open the EradicationKernel solution in Visual Studio.
On the Solution Explorer pane, right-click the Eradication project and select Properties.
On the Property Pages window, in the Configuration Properties pane, click Debugging.
Set the Command Arguments and Working Directory to the appropriate values and click OK. See Run a simulation using the command line for more information.
On the Debug menu, do one of the following:
Click Start Without Debugging to run the simulation in Release mode, where the simulation runs with essentially the same behavior and performance as running it at the command line.
Click Start Debugging to run the simulation in Debug mode, where you have the ability to add break points and step through the code, inspecting the values of different variables throughout the simulation.
Troubleshooting EMOD builds¶
If you encounter any of the following warnings or errors when attempting to build the EMOD executable (Eradication.exe) or Eradication binary, see the information below to resolve the issue.
If you need assistance, you can contact support for help with solving issues. You can contact Institute for Disease Modeling (IDM) support at support@idmod.org. When submitting the issue, please include any error information.
Unknown compiler version¶
If you encounter the warning “Unknown compiler version - please run the configure tests and report the results” when attempting to build the Eradication.exe or Eradication binary, this indicates you are using a version of Boost that is no longer supported. Install Boost 1.61.0.
Inconsistent DLL linkage¶
If you see the following warning on some files, “c:python27includepymath.h(22): warning C4273: ‘round’: inconsistent dll linkage”, this indicates that you are using a version of Python that is no longer supported. Install Python 2.7.11 or 2.7.12.
Error 255¶
Check to see if you have any white spaces in the path to your local EMOD source code. If you do, remove the white spaces in all of the directory names in the path.
Error LNK4272¶
If you see the error “LNK4272 library machine type ‘X86’ conflicts with target machine type ‘x64’”, this indicates that you need to uninstall 32-bit Python and reinstall 64-bit Python. Install Python 2.7.11 or 2.7.12.
Regression testing¶
After building the EMOD executable (Eradication.exe), it’s important to verify that Eradication.exe is performing properly. Regression testing is a method by which the built code is tested to see if it has “regressed” or moved backwards in any way, such as previously reported (and fixed) issues reappearing.
Within the EMOD Regression directory there are many subdirectories that correspond to different disease scenarios in a variety of locations. Each of these contains the configuration and campaign files needed to run the simulation and the reference output, which represents the expected results. These reference outputs have been calculated by the scientific researchers modeling each scenario.
EMOD regression testing consists of running one or more of these simulations and comparing the output to the reference output. If the two outputs are comparable, the test passes; if they differ, the test fails. Because EMOD is stochastic, a passing test will fall within some acceptable range of the reference output, rather than be an identical match. If a regression test fails, EMOD will produce a matplotlib chart of the first 16 channels in the InsetChart.json output report. You can then review the charts to identify the problem.
If you want to quickly compare a simulation output to the reference output, you can also run any of the regression scenarios as a typical simulation, as described in Run simulations. However, this will not include the comparison and pass/fail evaluation that regression_test.py conducts. In addition, if you choose to do this, be sure to specify a different output directory, such as “testing”, so as not to overwrite the reference output.
Run regression tests¶
The Python script regression_test.py runs a suite of regression simulations and compares the output to the reference output for each simulation. It is set up to run the simulations on an HPC cluster; however, you can run modify the script to run tests locally. However, the script was written with remote execution in mind and running it locally can be time-consuming. Running the entire regression suite locally will take several hours on average.
The regression scenarios, script, configuration file, and other relevant files are all in the Regression directory. Be aware that many of these tests, due to abnormally high or low values, will produce output that should not be considered scientifically accurate.
Modify the configuration file, regression_test.cfg, for your environment, setting the values for the location of the working directory, input data files, binary file, and cluster settings.
For local Windows simulations, set the values under [WINDOWS].
For local CentOS on Azure simulations, set the values under [POSIX].
For simulations on IDM HPC clusters, no changes are necessary if your username and password are cached locally.
For simulations on your own HPC cluster, create [HPC-<cluster>] and [ENVIRONMENT-<cluster>] sections for your cluster that contain the same variables as shown for IDM HPC clusters.
Select the suite of regression tests you want to run. This is indicated by a JSON file in the following format:
{ "tests": [{ "path": "Relative path to test directory." }, { "path": "Relative path to test directory." }] }
You can use one of the JSON files in the Regression directory or create your own. The sanity.json file is recommended for quickly testing a wide range of EMOD functionality.
From the Regression directory, open a Command Prompt window and run the regression test script, regression_test.py. It requires the name of the regression suite (without the .json extension) and the relative path to Eradication.exe. For example:
regression_test.py sanity ..\Eradication\x64\Release\Eradication.exe
In addition, you may need to include the following optional arguments depending on your testing environment or how Eradication.exe was built.
Argument
Default
Description
--perfFalse
Measure Eradication.exe performance.
--hidegraphsFalse
Suppress pop-up graphs in case of validation failures.
--debugFalse
Use the debug path for EMODules.
--labelAdd a custom suffix for HPC job name.
--configregression_test.cfg
The regression test configuration file.
--disable-schema-testTrue
Include to suppress schema testing, which is on by default.
--use-dllsFalse
Use EMODules when running tests.
--all-outputsFalse
Use all output JSON files for validation, not just InsetChart.json.
--dll-pathThe path to the root directory of the EMODules to use.
--skip-emodule-checkFalse
Skip checking if EMODules on the cluster are up-to-date, which can be slow.
--sconsFalse
Indicate that this is a SCons build so custom DLLs are found in the build/64/Release directory.
--localFalse
Run all simulations locally.
Review the output and examine any failures.
EMOD will output the standard error and logging files, StdErr.txt and StdOut.txt, produced from any simulation (see Error and logging files). In addition, regression_test.py will output time.txt under the regression test working directory and report_xxxx.xml under Regression/reports. The time report contains the EMOD version and total run time of the simulation. The regression report is in JUnit standard form and captures run information, including pass/fail/complete and time to complete.
If a simulation completes saying the run passed but the channel order was different than the reference output, this is considered a pass. However, if any output completes but does not match the reference output, this is considered a failure and a matplotlib chart of the output will appear in a pop-up window. The chart will appear immediately after the simulation, before the entire suite of regression tests completes. You can manipulate the output of the charts, such as adjusting the scale of the plots, zooming or panning, and so forth, through the icons at the bottom of the chart window.
If any of the regression tests fail and you have not made any changes to the EMOD source code, email support@idmod.org.
Create a new regression test¶
You can create a new regression based off one of the ones included with the EMOD source code using the steps below.
Under the Regression directory, create a new subdirectory.
Copy the contents of the regression test that you want to base the new test on into the subdirectory.
Modify the configuration, campaign, and demographic files as desired.
Create the reference output by doing one of the following:
Modify the InsetChart.json file to match the output you expect.
Run simulations until you have an acceptable InsetChart.json that you wish to use as the reference.