institutefordiseasemodeling / emod

Source files for building the IDM EMOD disease transmission model.

EMOD - V2.22

Epidemiological MODeling software (EMOD), is an agent-based model (ABM) that simulates the simultaneous interactions of agents in an effort to recreate 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.

EMOD is also stochastic, meaning that there is randomness built into the model. Infection and recovery processes are represented as probabilistic Bernoulli random draws. In other words, when a susceptible person comes into contact with a pathogen, they are not guaranteed to become infected. Instead, you can imagine flipping a coin that has a λ chance of coming up tails S(t) times, and for every person who gets a “head” you say they are infected. This randomness better approximates what happens in reality. It also means that you must run many simulations to determine the probability of particular outcomes.

As of V2.22, EMOD will only support malaria and HIV and will no longer support diseases such as TB and Typhoid.

History & Publication Samples

EMOD development was started by Philip Welkoff in 2010 to model malaria. Since that time, EMOD has been used in numerous studies and policy decisions. Below is short sample of papers about EMOD and that used EMOD:

A malaria transmission-directed model of mosquito life cycle and ecology

• Philip A Eckhoff
• Malaria Journal, 2011
• https://malariajournal.biomedcentral.com/articles/10.1186/1475-2875-10-303

Description of the EMOD-HIV Model v0.7

• Anna Bershteyn, Daniel J. Klein, Edward Wenger, and Philip A. Eckhoff
• arXiv.org, 2012
• https://arxiv.org/pdf/1206.3720

Effectiveness of reactive case detection for malaria elimination in three archetypical transmission settings: a modelling study

• Jaline Gerardin,Caitlin A. Bever, Daniel Bridenbecker, Busiku Hamainza, Kafula Silumbe, John M. Miller, Thomas P. Eisele, Philip A. Eckoff, and Edward A. Wenger
• Malaria Journal, 2017
• https://malariajournal.biomedcentral.com/articles/10.1186/s12936-017-1903-z

Implementation and applications of EMOD, an individual-based multi-disease modeling platform

• Anna Bershteyn, Jaline Gerardin, Daniel Bridenbecker, Christopher W Lorton, Jonathan Bloedow, Robert S Baker, Guillaume Chabot-Couture, Ye Chen, Thomas Fischle, Kurt Frey, Jillian S Gauld, Hao Hu, Amanda S Izzo, Daniel J Klein, Dejan Lukacevic, Kevin A McCarthy, Joel C Miller, Andre Lin Ouedraogo, T Alex Perkins, Jeffrey Steinkraus, Tony Ting, Quirine A ten Bosch, Hung-Fu Ting, Svetlana Titova, Bradley G Wagner, Philip A Welkhoff, Edward A Wenger, Christian N Wiswell
• Pathogens and Disease, 2018
• https://academic.oup.com/femspd/article/76/5/fty059/5050059?login=false

Vector genetics, insecticide resistance and gene drives: an agent-based modeling approach to evaluate malaria transmission and elimination

• Prashanth Selvaraj, Edward A. Wenger, Daniel Bridenbecker, Nikolai Windbichler, Jonathan R. Russell , Jaline Gerardin, Caitlin A. Bever, Milen Nikolov
• BioRxiv, 2020
• https://www.biorxiv.org/content/10.1101/2020.01.27.920421v1.full

The effect of 90-90-90 on HIV-1 incidence and mortality in eSwatini: a mathematical modelling study

• Adam Akullian , Michelle Morrison, Geoffrey P Garnett, Zandile Mnisi, Nomthandazo Lukhele, Daniel Bridenbecker, Anna Bershteyn
• The Lancet HIV, 2020
• https://www.thelancet.com/action/showPdf?pii=S2352-3018%2819%2930436-9

Running EMOD

Since EMOD is a stochastic model, you must run numerous realizations of each scenario in order to collect proper statistics. You will likely need a high performance computing (HPC) platform to run these simulations. As of July 2024, we only support a SLURM-based HPC.

To make running EMOD easier, we have created some python packages that simplify configuring, running, and plotting the results. As of July 2024, we are working to make these packages more user friendly and will have updates coming in Q4 of 2024.

Directory structure

• baseReportLib - A library of commonly used report components and base classes.
• cajun - A C++ API for JSON
• campaign - A library of commonly used intervention components and base classes.
• componentTests - A collection of unit tests that verify that the EMOD pieces do the right thing.
• Dependencies - Microsoft Cluster Pack
• Eradication - The core components of EMOD including human intra-host, relationship, and vector models.
• interventions - A collection of interventions that can be used with EMOD.
• libsqlite - The SQLite source code for reading and creating SQLite databases.
• lz4 - A fast compression engine used to read and write serialized populations.
• rapidjson - A fast JSON parser/generator for C++ with box SAX/DOM style API
• Regression - A collection of scripts, input data, and output data used to verify that EMOD models things correctly.
• reporters - A collection of data extraction, or report, classes used to collect data during a simulation.
• Scripts - A collection of support scripts
• snappy - A fast compression engine used to read and write serialized populations.
• UnitTest++ - A C++ unit test framework used by the componentTests
• untils - A collection of utility classes to do things like help with configuring and generating pseudo random numbers.

If wanting to navigate through the code, the place to start is Eradication\Eradication.cpp.

More information on the EMOD Architecture can be found at:

https://docs.idmod.org/projects/emod-malaria/en/latest/dev-architecture-overview.html

Source Code Installation for Development

The following link provides instructions for installing the prerequisites required to build and run EMOD. This intended for code development and not doing research.

https://docs.idmod.org/projects/emod-malaria/en/latest/dev-install-overview.html

Contributing

Questions or comments can be directed to [email protected].

Full information about EMOD is provided in the documentation.

Disclaimer

The code in this repository was developed by IDM and other collaborators to support our joint research on flexible agent-based modeling. We've made it publicly available under the MIT License to provide others with a better understanding of our research and an opportunity to build upon it for their own work. We make no representations that the code works as intended or that we will provide support, address issues that are found, or accept pull requests. You are welcome to create your own fork and modify the code to suit your own modeling needs as permitted under the MIT License.

emod's Issues

refactor renaming and filtering for reports

Improving the portability of EMOD

I would like to make EMOD more compatible with other platforms and I'm trying to
figure out how the compilation of EMOD works. Could you explain how the logic
works? Also, which dependencies are needed for which part of EMOD?
Is python used outside of reporting?

Looking at the main SConscript file, there seems to be a section for building
shared libraries (DLLs), but as far as I understand the paths that it is
referring to do not exist (libgeneric/*). Is this directory built during the
compilation or is the code stale?

Ultimately, I would like to use CMake instead of Scons as the build manager for
better portability and possibly faster builds using Ninja.

Rename master to main

Rename master to main

Malaria: relatively small "Vector_Migration_Food_Modifier" can cause floating point crash

Was trying to make vectors really hungry and changed "Vector_Migration_Food_Modifier": 100,
this causes floating point issue when the modification is exponential because we use:
fm = exp( sp * m_ModifierFood * pr ) - 1.0f; formula and sp and pr are often likely to be 1;

I think we need to limit Vector_Migration_Food_Modifier food size when using ModiferEquationType::EXPONENTIAL

unattended / shared linux install?

Working on a shared system, such as a cluster compute environment, I would like to be able to (and have been asked to) install this package for several non-privileged users. I can handle making the dependencies available, but is there documentation (other than reading through PrepareLinuxEnvironment.sh) on the proper setup for people?

I may also want to present the package as a container (docker or singularity). Making it possible to run the PrepareLinuxEnvironment.sh script without y/n prompts would make that a lot easier as well.

Happy to contribute where you see fit, just point me in the right direction!

Request - open source photonic fence device for killing mosquitoes

or link to this
https://github.com/retomerz/mosquito

Output the JSON schema in a stardard format

EMOD has a command line option to output the schema for configuration files, but it is in a non-standard format. There is an existing standard for JSON schemas. Probably the easiest way to generate this schema is to infer it from existing configuration files using Quicktype.

The schema makes it possible to validate the configuration files and automatically generate wrappers for generating the JSON in a number of different languages such as Python, C++, Rust and Go.

How can this be used to model nCoV?

title

Requiring additional files for running Namawala examples

Hi,

I am trying to run Namawala examples - it complains some additional files are needed, such as "Namawala_single_node_air_temperature_daily.bin.json". I cannot locate these files in this repository, would someone mind pointing me to them?

Many thanks and regards

Christian Schroeder de Witt

Enable_Vector_Migration being not on the same chunk as Vector_Migration_parameters causes error in emod_api

emod_api.schema_to_class tries to find the "depends-on" paramater in the same chunk of schema wher the parameter with the depends-on is located, but Vector_Migration_ parameters are now inside Vector_Species_Parameters while Enable_Vector_Migration is in the main parameters: chunk.

error:
Creating EMODTask (from files)...
Traceback (most recent call last):
File "C:\GitHub\emodpy-malaria\examples\vector_migration_example\example.py", line 282, in
general_sim()
File "C:\GitHub\emodpy-malaria\examples\vector_migration_example\example.py", line 219, in general_sim
task = EMODTask.from_default2(
File "C:\GitHub\emodpy-malaria\venv_malaria\lib\site-packages\emodpy\emod_task.py", line 283, in from_default2
task.config = dfs.get_config_from_default_and_params(config=default_config, set_fn=param_custom_cb)
File "C:\GitHub\emodpy-malaria\venv_malaria\lib\site-packages\emod_api\config\default_from_schema_no_validation.py", line 154, in get_config_from_default_and_params
config = set_fn(config)
File "C:\GitHub\emodpy-malaria\examples\vector_migration_example\example.py", line 62, in set_param_fn
vector_config.add_vector_migration(config, species="gambiae",
File "C:\GitHub\emodpy-malaria\venv_malaria\lib\site-packages\emodpy_malaria\vector_config.py", line 868, in add_vector_migration
species_params.Vector_Migration_Filename = vector_migration_filename
File "C:\GitHub\emodpy-malaria\venv_malaria\lib\site-packages\emod_api\schema_to_class.py", line 81, in setattr
if self["schema"][k]['default'] == self[k]:
File "C:\GitHub\emodpy-malaria\venv_malaria\lib\site-packages\emod_api\schema_to_class.py", line 19, in missing
raise KeyError(f"'{key}' not found in this object. List of keys = {self.keys()}.")
KeyError: "'Enable_Vector_Migration' not found in this object. List of keys = odict_keys(['Acquire_Modifier', 'Adult_Life_Expectancy', 'Anthropophily', 'Aquatic_Arrhenius_1', 'Aquatic_Arrhenius_2', 'Aquatic_Mortality_Rate', 'Cycle_Arrhenius_1', 'Cycle_Arrhenius_2', 'Cycle_Arrhenius_Reduction_Factor', 'Days_Between_Feeds', 'Drivers', 'Egg_Batch_Size', 'Gene_To_Trait_Modifiers', 'Genes', 'Habitats', 'Immature_Duration', 'Indoor_Feeding_Fraction', 'Infected_Arrhenius_1', 'Infected_Arrhenius_2', 'Infected_Egg_Batch_Factor', 'Infectious_Human_Feed_Mortality_Factor', 'Male_Life_Expectancy', 'Microsporidia', 'Name', 'Temperature_Dependent_Feeding_Cycle', 'Transmission_Rate', 'Vector_Migration_Filename', 'Vector_Migration_Food_Modifier', 'Vector_Migration_Habitat_Modifier', 'Vector_Migration_Modifier_Equation', 'Vector_Migration_Stay_Put_Modifier', 'Vector_Sugar_Feeding_Frequency', 'x_Vector_Migration'])."

Proposed solution: I think since vector migration is per-species and each species keeps track of it's own "vectormigrationenabled" parameter (m_IsEnabled) I believe, we could just use "is Vector_Migration_Filename set to readable file" as a flag for "does this species migrate" and if the Filename paramater is defined (and not just present), we can set internal flag of "m_IsEnabled" and require the MigrationModifierEquation parameters. If the species doesn't have Vector_Migration_Filename defined, we just not have migration turned on for tht species.