emod-api 3.1.1__tar.gz → 3.2.1__tar.gz

{emod_api-3.1.1 → emod_api-3.2.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 - 2025 Gates Foundation
+Copyright (c) 2010-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

{emod_api-3.1.1/emod_api.egg-info → emod_api-3.2.1}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: emod-api
-Version: 3.1.1
+Version: 3.2.1
 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
+Project-URL: Documentation, https://emod.idmod.org/emod-api/
+Project-URL: Issues, https://github.com/EMOD-Hub/issues-and-discussions/issues
 Keywords: modeling,IDM
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
@@ -30,6 +31,7 @@ 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"
+Requires-Dist: mkdocs-table-reader-plugin; extra == "docs"
 Provides-Extra: lint
 Requires-Dist: flake8; extra == "lint"
 Provides-Extra: test
@@ -44,17 +46,31 @@ Dynamic: license-file
 
 # emod-api
 
+**emod-api** is a set of Python tools for working with EMOD configuration, campaign, and output files.
+
 [![Build docs and deploy to GH Pages](https://github.com/EMOD-Hub/emod-api/actions/workflows/mkdocs_deploy.yml/badge.svg)](https://github.com/EMOD-Hub/emod-api/actions/workflows/mkdocs_deploy.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 update version](https://github.com/EMOD-Hub/emod-api/actions/workflows/test_and_bump_version.yml/badge.svg)](https://github.com/EMOD-Hub/emod-api/actions/workflows/test_and_bump_version.yml)
 
+## 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-hub.github.io/emod-api/.
+Documentation available at https://emod.idmod.org/emod-api/
 
 To build the documentation locally, do the following:
 
@@ -62,17 +78,16 @@ To build the documentation locally, do the following:
 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 libdev-snappy (Debian/Ubuntu) or snappy-devel (RedHat/CentOS) on 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 libdev-snappy```
-
-CentOS: ```[sudo] yum install snappy-devel``` (not yet tested)
+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.
@@ -94,14 +109,6 @@ Output
 - 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.
@@ -116,13 +123,21 @@ 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:
+Have a question or a comment? Check out our
+[Discussions](https://github.com/orgs/EMOD-Hub/discussions) space.
+
+## Contributing
 
-https://forms.office.com/r/sjncGvBjvZ
+If you have feature requests, issues, or new code, please see our
+[CONTRIBUTING](https://github.com/EMOD-Hub/.github/blob/main/CONTRIBUTING.md)
+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.
+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-3.1.1 → emod_api-3.2.1}/README.md

@@ -1,16 +1,30 @@
 # emod-api
 
+**emod-api** is a set of Python tools for working with EMOD configuration, campaign, and output files.
+
 [![Build docs and deploy to GH Pages](https://github.com/EMOD-Hub/emod-api/actions/workflows/mkdocs_deploy.yml/badge.svg)](https://github.com/EMOD-Hub/emod-api/actions/workflows/mkdocs_deploy.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 update version](https://github.com/EMOD-Hub/emod-api/actions/workflows/test_and_bump_version.yml/badge.svg)](https://github.com/EMOD-Hub/emod-api/actions/workflows/test_and_bump_version.yml)
 
+## 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-hub.github.io/emod-api/.
+Documentation available at https://emod.idmod.org/emod-api/
 
 To build the documentation locally, do the following:
 
@@ -18,17 +32,16 @@ To build the documentation locally, do the following:
 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 libdev-snappy (Debian/Ubuntu) or snappy-devel (RedHat/CentOS) on 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 libdev-snappy```
-
-CentOS: ```[sudo] yum install snappy-devel``` (not yet tested)
+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.
@@ -50,14 +63,6 @@ Output
 - 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.
@@ -72,13 +77,21 @@ 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:
+Have a question or a comment? Check out our
+[Discussions](https://github.com/orgs/EMOD-Hub/discussions) space.
+
+## Contributing
 
-https://forms.office.com/r/sjncGvBjvZ
+If you have feature requests, issues, or new code, please see our
+[CONTRIBUTING](https://github.com/EMOD-Hub/.github/blob/main/CONTRIBUTING.md)
+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.
+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-3.2.1/emod_api/__init__.py

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

emod_api-3.2.1/emod_api/campaign.py

@@ -0,0 +1,371 @@
+#!/usr/bin/env python
+"""Simple campaign builder for EMOD simulations.
+
+Import this module, add valid campaign events via ``add``, and write the
+campaign file with ``save``.
+"""
+
+import json
+import warnings
+
+from emod_api import schema_to_class as s2c
+
+schema_path = None
+_schema_json = None
+campaign_dict = {"Events": [], "Use_Defaults": 1}
+individual_events_listened = []
+individual_events_broadcast = []
+node_events_broadcast = []
+node_events_listened = []
+coordinator_events_broadcast = []
+coordinator_events_listened = []
+use_old_adhoc_handling = False
+unsafe = False
+implicits = list()
+individual_builtin_events = []
+node_builtin_events = []
+coordinator_builtin_events = []
+
+
+def reset():
+    """Reset all campaign state to defaults.
+
+    Clears accumulated events, signal tracking lists, event mappings,
+    and the schema cache.
+    """
+    campaign_dict["Events"].clear()
+
+    individual_events_listened.clear()
+    individual_events_broadcast.clear()
+    node_events_broadcast.clear()
+    node_events_listened.clear()
+    coordinator_events_broadcast.clear()
+    coordinator_events_listened.clear()
+    implicits.clear()
+    individual_builtin_events.clear()
+    node_builtin_events.clear()
+    coordinator_builtin_events.clear()
+    s2c.clear_schema_cache()
+
+
+def _find_builtin_events(schema, reporter_key, events_key):
+    """Recursively find a builtin events using reporter entry and extract its event list.
+
+    Walks the schema looking for ``reporter_key`` as a dict key. When
+    found, looks up ``events_key`` inside it and returns the
+    ``"Built-in"`` list if present, otherwise the ``"enum"`` list (used in EMOD-Generic)
+
+    Args:
+        schema: The schema JSON object (or sub-object) to search.
+        reporter_key: The reporter key to find (e.g.
+            ``"ReportEventRecorder"``).
+        events_key: The events parameter inside the reporter (e.g.
+            ``"Report_Event_Recorder_Events"``).
+
+    Returns:
+        A list of event name strings, or ``None`` if the reporter
+        or its event list is not found.
+    """
+    if isinstance(schema, dict):
+        if reporter_key in schema:
+            events_entry = schema[reporter_key]
+            if isinstance(events_entry, dict):
+                events_param = events_entry.get(events_key)
+                if isinstance(events_param, dict):
+                    builtin = events_param.get("Built-in")
+                    if isinstance(builtin, list):
+                        return builtin
+                    enum = events_param.get("enum")
+                    if isinstance(enum, list):
+                        return enum
+            return None
+        for value in schema.values():
+            result = _find_builtin_events(value, reporter_key, events_key)
+            if result is not None:
+                return result
+    elif isinstance(schema, list):
+        for item in schema:
+            result = _find_builtin_events(item, reporter_key, events_key)
+            if result is not None:
+                return result
+    return None
+
+
+def set_schema(schema_path_in):
+    """Set the schema file path and reset all campaign state.
+
+    This is essentially the "start building a campaign" entry point.
+    It clears any previously accumulated events and loads the new schema.
+    Also extracts built-in event lists for individual, node, and
+    coordinator levels by recursively searching for
+    ``ReportEventRecorder``, ``ReportEventRecorderNode``, and
+    ``ReportEventRecorderCoordinator`` in the schema.
+
+    Args:
+        schema_path_in: Path to a ``schema.json`` file.
+    """
+    reset()
+    global schema_path, _schema_json
+
+    schema_path = schema_path_in
+    with open(schema_path_in) as schema_file:
+        _schema_json = json.load(schema_file)
+
+    found = _find_builtin_events(_schema_json, "ReportEventRecorder", "Report_Event_Recorder_Events")
+    if found:
+        individual_builtin_events.extend(found)
+
+    found = _find_builtin_events(_schema_json, "ReportEventRecorderNode", "Report_Node_Event_Recorder_Events")
+    if found:
+        node_builtin_events.extend(found)
+
+    found = _find_builtin_events(_schema_json, "ReportEventRecorderCoordinator", "Report_Coordinator_Event_Recorder_Events")
+    if found:
+        coordinator_builtin_events.extend(found)
+
+
+def get_schema():
+    """Return the loaded schema JSON dictionary.
+
+    Returns:
+        The parsed schema dictionary, or ``None`` if ``set_schema`` has
+        not been called.
+    """
+    return _schema_json
+
+
+def add(event, note: str = None):
+    """Add a complete campaign event to the campaign builder.
+
+    The event is assumed to be valid and is not validated here.
+
+    Args:
+        event: A complete campaign event object. It must support
+            ``finalize()`` and dict-style key assignment.
+        note: An optional human-readable note added to the event
+            inside the output ``campaign.json`` file.
+    """
+    event.finalize()
+    if note is not None:
+        event["Note"] = note
+    campaign_dict["Events"].append(event)
+
+
+def save(filename: str = "campaign.json"):
+    """Save the accumulated campaign events to a JSON file.
+
+    Args:
+        filename: Output file path.
+
+    Returns:
+        The filename that was written.
+    """
+    with open(filename, "w") as camp_file:
+        json.dump(campaign_dict, camp_file, sort_keys=True, indent=4)
+
+    return filename
+
+
+def _validate_custom_events(listened_list, broadcast_list, builtin_list, level):
+    """Validate that listened-to events are broadcast and vice versa.
+
+    Built-in events are excluded from validation since they are
+    handled by the simulation engine and do not need to be explicitly
+    broadcast or listened to in the campaign.
+
+    Args:
+        listened_list: List of event names being listened to.
+        broadcast_list: List of event names being broadcast.
+        builtin_list: List of built-in event names to exclude from
+            validation.
+        level: Label for the event level (e.g. ``"coordinator"``
+            or ``"node"``) used in error/warning messages.
+
+    Returns:
+        A deduplicated list of custom (non-built-in) broadcast event
+        name strings.
+
+    Raises:
+        ValueError: If any events are listened to but never broadcast.
+    """
+    builtins = set(builtin_list)
+
+    broadcast_matching_builtins = set(broadcast_list) & builtins
+    if broadcast_matching_builtins:
+        warnings.warn(
+            f"The following {level}-level broadcast events mirror built-in {level}-level events, "
+            f"therefore these events will be broadcast by the simulation as well as the campaign: "
+            f"{sorted(broadcast_matching_builtins)}")
+
+    listened = set(listened_list) - builtins
+    broadcast = set(broadcast_list) - builtins
+
+    listened_not_broadcast = listened - broadcast
+    if listened_not_broadcast:
+        raise ValueError(
+            f"The following {level}-level events are listened to but never broadcast. This means that any campaign "
+            f"interventions that rely on listening to these events will never fire. Please fix the error by either "
+            f"broadcasting these events in the campaign or removing the interventions that are listening for them:\n"
+            f"{sorted(listened_not_broadcast)}")
+
+    broadcast_not_listened = broadcast - listened
+    if broadcast_not_listened:
+        warnings.warn(
+            f"The following {level} events are broadcast but nothing is listening to them within "
+            f"the campaign: {sorted(broadcast_not_listened)}")
+
+    return list(broadcast)
+
+
+def get_custom_coordinator_events():
+    """Validate and return deduplicated custom coordinator-level events.
+
+    Returns:
+        A list of unique coordinator event name strings that are broadcast
+        in the campaign.
+
+    Raises:
+        ValueError: If any coordinator events are listened to but
+            never broadcast.
+    """
+    return _validate_custom_events(coordinator_events_listened, coordinator_events_broadcast, coordinator_builtin_events, "coordinator")
+
+
+def get_custom_node_events():
+    """Validate and return deduplicated custom node-level events.
+
+    Returns:
+        A list of unique node event name strings that are broadcast
+        in the campaign.
+
+    Raises:
+        ValueError: If any node events are listened to but
+            never broadcast.
+    """
+    return _validate_custom_events(node_events_listened, node_events_broadcast, node_builtin_events, "node")
+
+
+def get_custom_individual_events():
+    """Validate and return deduplicated custom individual-level events.
+
+    Returns:
+        A list of unique individual event name strings that are broadcast
+        in the campaign.
+
+    Raises:
+        ValueError: If any individual events are listened to but
+            never broadcast.
+    """
+    return _validate_custom_events(individual_events_listened, individual_events_broadcast, individual_builtin_events, "individual")
+
+
+def get_recv_trigger(trigger, old=use_old_adhoc_handling):
+    """Register an individual-level event as listened to.
+
+    Tracks which individual events are used throughout the simulation
+    so that ``get_custom_individual_events`` can validate that every
+    listened-to event has a corresponding broadcast.
+
+    Args:
+        trigger: The individual event name string.
+        old: Unused. Kept for backwards compatibility.
+
+    Returns:
+        The event name, unchanged.
+    """
+    if not trigger:
+        raise ValueError("Event name must not be None or empty.")
+    individual_events_listened.append(trigger)
+    return trigger
+
+
+def set_listened_node_event(event: str) -> str:
+    """Register a node-level event as listened to.
+
+    Tracks which node events are used throughout the simulation so
+    that ``get_custom_node_events`` can validate that every listened-to
+    event has a corresponding broadcast.
+
+    Args:
+        event: The node event name string.
+
+    Returns:
+        The event name, unchanged.
+    """
+    if not event:
+        raise ValueError("Event name must not be None or empty.")
+    node_events_listened.append(event)
+    return event
+
+
+def set_listened_coordinator_event(event: str) -> str:
+    """Register a coordinator-level event as listened to.
+
+    Tracks which coordinator events are used throughout the simulation
+    so that ``get_custom_coordinator_events`` can validate that every
+    listened-to event has a corresponding broadcast.
+
+    Args:
+        event: The coordinator event name string.
+
+    Returns:
+        The event name, unchanged.
+    """
+    if not event:
+        raise ValueError("Event name must not be None or empty.")
+    coordinator_events_listened.append(event)
+    return event
+
+
+def get_send_trigger(trigger, old=use_old_adhoc_handling):
+    """Register an individual-level event as broadcast.
+
+    Args:
+        trigger: The individual event name string.
+        old: Unused. Kept for backwards compatibility.
+
+    Returns:
+        The event name, unchanged.
+    """
+    if not trigger:
+        raise ValueError("Event name must not be None or empty.")
+    individual_events_broadcast.append(trigger)
+    return trigger
+
+
+def set_broadcast_node_event(event: str) -> str:
+    """Register a node-level event as broadcast.
+
+    Tracks which node events are used throughout the simulation so
+    that ``get_custom_node_events`` can validate that every broadcast
+    event has something listening to it.
+
+    Args:
+        event: The node event name string.
+
+    Returns:
+        The event name, unchanged.
+    """
+    if not event:
+        raise ValueError("Event name must not be None or empty.")
+    node_events_broadcast.append(event)
+    return event
+
+
+def set_broadcast_coordinator_event(event: str) -> str:
+    """Register a coordinator-level event as broadcast.
+
+    Tracks which coordinator events are used throughout the simulation
+    so that ``get_custom_coordinator_events`` can validate that every
+    broadcast event has something listening to it.
+
+    Args:
+        event: The coordinator event name string.
+
+    Returns:
+        The event name, unchanged.
+    """
+    if not event:
+        raise ValueError("Event name must not be None or empty.")
+    coordinator_events_broadcast.append(event)
+    return event

{emod_api-3.1.1 → emod_api-3.2.1}/emod_api/demographics/demographics.py

@@ -7,7 +7,7 @@ from typing import Union
 
 from emod_api.demographics.demographics_base import DemographicsBase
 from emod_api.demographics.node import Node
-from emod_api.demographics.properties_and_attributes import NodeAttributes
+from emod_api.demographics.properties_and_attributes import NodeAttributes, NodeProperty, NodeProperties  # noqa: F401
 from emod_api.demographics.service import service
 
 
@@ -30,13 +30,9 @@ class Demographics(DemographicsBase):
         """
         super().__init__(nodes=nodes, idref=idref, default_node=default_node)
 
-        # set some standard EMOD defaults. set_defaults should always be True unless reading from a demographics file,
-        # as False allows setting default_node.node_attributes exactly as they are in the file. Loading via
-        # Demographics.from_file() is deprecated, see below.
+        # No current default settings
         if set_defaults:
-            self.default_node.node_attributes.airport = 1
-            self.default_node.node_attributes.seaport = 1
-            self.default_node.node_attributes.region = 1
+            pass
 
     def to_file(self, path: Union[str, Path] = "demographics.json", indent: int = 4) -> None:
         """
@@ -96,6 +92,12 @@ class Demographics(DemographicsBase):
         demographics = cls(nodes=nodes, default_node=default_node, idref=idref, set_defaults=False)
         demographics.metadata = metadata
         demographics.implicits.extend(implicit_functions)
+
+        node_properties_list = demographics_dict.get("NodeProperties")
+        if node_properties_list:
+            for np_dict in node_properties_list:
+                demographics.node_properties.add(NodeProperty.from_dict(np_dict))
+
         return demographics
 
     @classmethod