emod-api 1.35.0__tar.gz

emod_api-1.35.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 - 2026 Gates Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

emod_api-1.35.0/MANIFEST.in

@@ -0,0 +1,2 @@
+graft emod_api/tests/data/*
+graft emod_api/dtk_tools/serialization/test-data/*

emod_api-1.35.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: emod-api
+Version: 1.35.0
+Summary: Core tools for modeling using EMOD
+Author-email: Sharon Chen <sharon.chen@gatesfoundation.org>, Zhaowei Du <zhaowei.du@gatesfoundation.org>, Clark Kirkman IV <clark.kirkmand@gatesfoundation.org>, Daniel Bridenbecker <daniel.bridenbecker@gatesfoundation.org>, Svetlana Titova <svetlana.titova@gatesfoundation.org>, Ye Chen <ye.chen@gatesfoundation.org>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/EMOD-Hub/emod-api
+Project-URL: Issues, https://github.com/EMOD-Hub/emod-api/issues
+Keywords: modeling,IDM
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+Requires-Dist: scipy
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: shapely
+Requires-Dist: pyproj
+Requires-Dist: geographiclib
+Requires-Dist: scikit-learn
+Requires-Dist: lz4
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs-include-markdown-plugin; extra == "docs"
+Requires-Dist: mkdocstrings-python; extra == "docs"
+Requires-Dist: mkdocs-autoapi; extra == "docs"
+Requires-Dist: mkdocs-glightbox; extra == "docs"
+Provides-Extra: lint
+Requires-Dist: flake8; extra == "lint"
+Provides-Extra: test
+Requires-Dist: emod-common; extra == "test"
+Requires-Dist: emod-generic; extra == "test"
+Requires-Dist: emod-hiv; extra == "test"
+Requires-Dist: emod-malaria; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+Dynamic: license-file
+
+# emod-api
+
+[![Run tests](https://github.com/EMOD-Hub/emod-api/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/EMOD-Hub/emod-api/actions/workflows/run-tests.yml)
+[![Lint](https://github.com/EMOD-Hub/emod-api/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/EMOD-Hub/emod-api/actions/workflows/lint.yml)
+[![Test and deploy to staging](https://github.com/EMOD-Hub/emod-api/actions/workflows/test_and_publish_package_to_staging.yml/badge.svg?branch=main)](https://github.com/EMOD-Hub/emod-api/actions/workflows/test_and_publish_package_to_staging.yml)
+
+## Python Version
+
+Python 3.13 is the recommended and supported version.
+
+## Documentation
+
+Documentation available at https://emod-hub.github.io/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]
+    ```
+
+## Dependencies
+
+### Linux
+
+emod-api can use Snappy [de]compression (python-snappy) as necessary if it is installed which requires libdev-snappy (Debian/Ubuntu) or snappy-devel (RedHat/CentOS) on Linux.
+
+Ubuntu: ```[sudo] apt install libdev-snappy```
+
+CentOS: ```[sudo] yum install snappy-devel``` (not yet tested)
+
+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.
+
+## Dev Tips
+
+- To build package:
+    `python -m build --wheel`
+
+- To install package (fill in actual version number in filename):  
+    `python -m pip install dist/emod_api...whl`
+
+## 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](/tests/README.md).
+
+## Community
+
+The EMOD Community is made up of researchers and software developers, primarily focused on malaria and HIV research.
+We value mutual respect, openness, and a collaborative spirit. If these values resonate with you, we invite you to join our EMOD Slack Community by completing this form:
+
+https://forms.office.com/r/sjncGvBjvZ
+
+## 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_api-1.35.0/README.md

@@ -0,0 +1,84 @@
+# emod-api
+
+[![Run tests](https://github.com/EMOD-Hub/emod-api/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/EMOD-Hub/emod-api/actions/workflows/run-tests.yml)
+[![Lint](https://github.com/EMOD-Hub/emod-api/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/EMOD-Hub/emod-api/actions/workflows/lint.yml)
+[![Test and deploy to staging](https://github.com/EMOD-Hub/emod-api/actions/workflows/test_and_publish_package_to_staging.yml/badge.svg?branch=main)](https://github.com/EMOD-Hub/emod-api/actions/workflows/test_and_publish_package_to_staging.yml)
+
+## Python Version
+
+Python 3.13 is the recommended and supported version.
+
+## Documentation
+
+Documentation available at https://emod-hub.github.io/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]
+    ```
+
+## Dependencies
+
+### Linux
+
+emod-api can use Snappy [de]compression (python-snappy) as necessary if it is installed which requires libdev-snappy (Debian/Ubuntu) or snappy-devel (RedHat/CentOS) on Linux.
+
+Ubuntu: ```[sudo] apt install libdev-snappy```
+
+CentOS: ```[sudo] yum install snappy-devel``` (not yet tested)
+
+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.
+
+## Dev Tips
+
+- To build package:
+    `python -m build --wheel`
+
+- To install package (fill in actual version number in filename):  
+    `python -m pip install dist/emod_api...whl`
+
+## 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](/tests/README.md).
+
+## Community
+
+The EMOD Community is made up of researchers and software developers, primarily focused on malaria and HIV research.
+We value mutual respect, openness, and a collaborative spirit. If these values resonate with you, we invite you to join our EMOD Slack Community by completing this form:
+
+https://forms.office.com/r/sjncGvBjvZ
+
+## 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_api-1.35.0/emod_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.35.0"

emod_api-1.35.0/emod_api/campaign.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python
+"""
+You use this simple campaign builder by importing it, adding valid events via "add", and writing it out with "save".
+"""
+
+import json
+
+schema_path = None
+campaign_dict = {"Events": [], "Use_Defaults": 1}
+pubsub_signals_subbing = []
+pubsub_signals_pubbing = []
+adhocs = []
+custom_coordinator_events = []
+custom_node_events = []
+event_map = {}
+use_old_adhoc_handling = False
+unsafe = False
+implicits = list()
+trigger_list = None
+
+
+def reset():
+    del (campaign_dict["Events"][:])
+    global pubsub_signals_subbing
+    global pubsub_signals_pubbing
+    global adhocs
+    global event_map
+    del (pubsub_signals_subbing[:])
+    del (pubsub_signals_pubbing[:])
+    del (adhocs[:])
+    del (custom_coordinator_events[:])
+    del (custom_node_events[:])
+    event_map = {}
+    from emod_api import schema_to_class as s2c
+    s2c.schema_cache = None
+    del (implicits[:])
+
+
+def set_schema(schema_path_in):
+    """
+    Set the (path to) the schema file. And reset all campaign variables. This is essentially a
+    "start_building_campaign" function.
+
+    Args:
+
+        schema_path_in. The path to a schema.json.
+    Returns:
+        Nothing
+    """
+    reset()
+    global schema_path
+    schema_path = schema_path_in
+
+
+def get_schema():
+    schema = None
+    if schema_path:
+        with open(schema_path) as schema_file:
+            schema = json.load(schema_file)
+    return schema
+
+
+def add(event, name=None, first=False):
+    """
+    Add a complete campaign event to the campaign builder. The new event is assumed to be a Python dict, and a 
+    valid event. The new event is not validated here. 
+    Set the first flag to True if this is the first event in a campaign because it functions as an
+    accumulator and in some situations like sweeps it might have been used recently.
+    """
+    event.finalize()
+    if first:
+        print("Use of 'first' flag is deprecated. Use set_schema to start build a new, empty campaign.")
+        global campaign_dict
+        campaign_dict["Events"] = []
+    if "Event_Name" not in event and name is not None:
+        event["Event_Name"] = name
+    if "Listening" in event:
+        pubsub_signals_subbing.extend(event["Listening"])
+        event.pop("Listening")
+    if "Broadcasting" in event:
+        pubsub_signals_pubbing.extend(event["Broadcasting"])
+        event.pop("Broadcasting")
+    campaign_dict["Events"].append(event)
+
+
+def get_trigger_list():
+    global trigger_list
+    if get_schema():
+        # This needs to be fixed in the schema post-processor: maybe create a new idmTime:EventEnum and replace
+        # all the occurrences with a reference to that.
+        try:
+            trigger_list = get_schema()["idmTypes"]["idmAbstractType:EventCoordinator"]["BroadcastCoordinatorEvent"][
+                "Broadcast_Event"]["enum"]
+        except Exception as ex:
+            trigger_list = get_schema()["idmTypes"]["idmType:IncidenceCounter"]["Trigger_Condition_List"]["Built-in"]
+    return trigger_list
+
+
+def save(filename="campaign.json"):
+    """
+    Save 'campaign_dict' as file named 'filename'.
+    """
+    with open(filename, "w") as camp_file:
+        json.dump(campaign_dict, camp_file, sort_keys=True, indent=4)
+    import copy
+    ignored_events = copy.deepcopy(set(pubsub_signals_pubbing))
+    non_camp_events = set()
+    if len(pubsub_signals_subbing) > 0:
+        for event in set(pubsub_signals_subbing):
+            if event in ignored_events:
+                ignored_events.remove(event)
+    if len(non_camp_events) > 0:
+        for event in set(non_camp_events):
+            if event in get_adhocs() and not unsafe:
+                raise RuntimeError(f"ERROR: Report is configured to LISTEN to the following non-existent event: \n"
+                                   f"{event} \nPlease fix the error.\n")
+    return filename
+
+
+def get_adhocs():
+    return event_map
+
+
+def get_custom_coordinator_events():
+    return list(set(custom_coordinator_events))
+
+
+def get_custom_node_events():
+    return list(set(custom_node_events))
+
+
+def get_recv_trigger(trigger, old=use_old_adhoc_handling):
+    """
+    Get the correct representation of a trigger (also called signal or even event) that is being listened to.
+    """
+    pubsub_signals_subbing.append(trigger)
+    return get_event(trigger, old)
+
+
+def get_send_trigger(trigger, old=use_old_adhoc_handling):
+    """
+    Get the correct representation of a trigger (also called signal or even event) that is being broadcast.
+    """
+    pubsub_signals_pubbing.append(trigger)
+    return get_event(trigger, old)
+
+
+def get_event(event, old=False):
+    """
+    Basic placeholder functionality for now. This will map new ad-hoc events to GP_EVENTs and manage that 'cache'
+    If event in built-ins, return event, else if in adhoc map, return mapped event, else add to adhoc_map and return
+    mapped event.
+    """
+    if event is None or event == "":
+        raise ValueError("campaign.get_event() called with an empty event. Please specify a string.")
+
+    return_event = None
+    global trigger_list
+    if trigger_list is None:
+        trigger_list = get_trigger_list()
+
+    if event in trigger_list:
+        return_event = event
+    elif event in event_map:
+        return_event = event_map[event]
+    else:
+        # get next entry in GP_EVENT_xxx
+        new_event_name = event if old else 'GP_EVENT_{:03d}'.format(len(event_map))
+        event_map[event] = new_event_name
+        return_event = event_map[event]
+    return return_event

emod_api-1.35.0/emod_api/channelreports/__main__.py

@@ -0,0 +1,5 @@
+#/usr/bin/env python
+
+import emod_api.channelreports as conf
+help(conf)
+