emod-api

emod-api is a set of Python tools for working with EMOD configuration, campaign, and output files.

Project status

EMOD-Hub projects are provided as open source software under the MIT License for community use, research, and development.

Unless otherwise noted, these projects are no longer actively maintained or supported by IDM or the Gates Foundation.

Community contributions are welcome, and trusted collaborators may review and merge pull requests, but no guarantees are made regarding support, pull request review, security response, maintenance, or release timelines.

Python Version

Python 3.13 is the recommended and supported version.

Documentation

Documentation available at https://emod.idmod.org/emod-api/

To build the documentation locally, do the following:

1. Create and activate a venv.
2. Navigate to the root directory of the repo.

   python -m pip install .[docs]
   mkdocs serve
   

Dependencies

Linux

emod-api can use Snappy [de]compression (python-snappy) as necessary if it is installed, which requires libsnappy-dev on Ubuntu 22.04 (Jammy Jellyfish).

Ubuntu: [sudo] apt install libsnappy-dev

NOTE: The python-snappy version needs to be 0.6.1. Newer versions have problems working correctly with emod-api.

User Stories

Input

• User wants to be able to create a minimal working config.json for any sim type guaranteed to work with a given Eradication binary.
• User wants to be able to create config.json from large static 'defaults' file and small variable parameters-of-interest file.
• User wants to be able to create guaranteed to work campaigns without having to interact with campaign.json files.
• User wants to create a migration file without having to grok our custom binary migration format.
• User wants to be able to create large multi-node demographics files programatically.

Output

• User wants to be able to get post-processed (cleaned up) schema.
• User wants to be able to get data from InsetChart.json without worrying about exact file format of the files.
• User wants to be able to extract data of interest from spatial binary files.
• User wants to be able to work easily with serialization files.
• User wants to be able to work easily with (pending) events.sql file.

Capability Wishlist

• Migration files: users should never have to edit migration binary or header files.
• Serialization: Population manipulation, such as adding IPs or adding risk factors.
• Demographics: HINT matrices should not be created directly in demographics.
• Demographics: Population demographic initalization should be easier and reliable.
• Config: param_overrides and custom events.

Running tests

Please see the documentation for testing.

Community

Have a question or a comment? Check out our Discussions space.

Contributing

If you have feature requests, issues, or new code, please see our CONTRIBUTING page for how to provide your feedback.

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.