emod-api 3.0.2__py3-none-any.whl

emod_api/spatialreports/spatial.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+
+"""emod-api spatial report module. Exposes SpatialReport and SpatialNode objects."""
+
+from pathlib import Path
+import numpy as np
+
+
+class SpatialNode(object):
+
+    """
+    Class representing a single node of a spatial report.
+    """
+
+    def __init__(self, node_id: int, data):
+
+        self._id = node_id
+        self._data = data
+
+        return
+
+    @property
+    def id(self) -> int:
+        """Node ID"""
+        return self._id
+
+    @property
+    def data(self):
+        """Time series data for this node."""
+        return self._data
+
+    def __getitem__(self, item: int) -> float:
+        """index into node data by time step"""
+        return self._data[item]
+
+    def __setitem__(self, key: int, value: float) -> None:
+        """index into node data by time step"""
+        self._data[key] = value
+        return
+
+
+NUM_STEPS_INDEX = 0
+NUM_NODES_INDEX = 1
+
+
+class SpatialReport(object):
+
+    """
+    Class for reading (and, optionally, writing) spatial reports in EMOD/DTK format.
+    "Filtered" reports will have start > 0 and/or reporting interval > 1.
+    """
+
+    def __init__(self, filename: str = None, node_ids: list[int] = None, data: np.array = None, start: int = 0, interval: int = 1):
+
+        """
+        Args:
+            filename: file from which to read data
+            node_ids: list of node ids, must be integer values
+            data: NumPy array of data, shape must be (#values, #nodes)
+            start: time step of first sample (used with filtered reports)
+            interval: # of time steps between samples (used with filtered reports)
+        """
+
+        if isinstance(filename, str):
+            self._from_file(filename)
+        else:
+            self._from_node_ids_and_data(node_ids, data, start, interval)
+
+        return
+
+    @property
+    def data(self) -> np.array:
+        """Returns full 2 dimensional NumPy array with report data. Shape is (#values, #nodes)."""
+        return self._data
+
+    @property
+    def node_ids(self) -> list[int]:
+        """Returns list of node IDs (integers) for nodes in the report."""
+        return self._node_ids
+
+    @property
+    def nodes(self) -> dict[int, SpatialNode]:
+        """Returns dictionary of SpatialNodes keyed on node ID."""
+        return self._nodes
+
+    # index into report by node id
+    def __getitem__(self, item: int) -> SpatialNode:
+        return self._nodes[item]
+
+    @property
+    def node_count(self) -> int:
+        """Number of nodes in the report."""
+        return self.data.shape[NUM_NODES_INDEX]
+
+    @property
+    def time_steps(self) -> int:
+        """Number of samples in the report."""
+        return self.data.shape[NUM_STEPS_INDEX]
+
+    @property
+    def start(self) -> int:
+        """Time step of first sample."""
+        return self._start
+
+    @property
+    def interval(self) -> int:
+        """Interval, in time steps, between samples."""
+        return self._interval
+
+    def write_file(self, filename: str):
+
+        """Save current nodes and timeseries data to given file."""
+
+        with open(filename, "wb") as file:
+            np.array([self.node_count], dtype=np.uint32).tofile(file)
+            np.array([self.time_steps], dtype=np.uint32).tofile(file)
+            if self.start != 0 or self.interval != 1:
+                np.array([self.start], dtype=np.float32).tofile(file)
+                np.array([self.interval], dtype=np.float32).tofile(file)
+            np.array([self.node_ids], dtype=np.uint32).tofile(file)
+            self.data.tofile(file)
+
+        return
+
+    def _from_file(self, filename: str):
+        """
+        Read binary spatial report file.
+        #nodes,
+        #time steps,
+        node ids (#nodes values),
+        data (#nodes x #time steps values)
+        """
+        # File format:
+        # number of nodes      - uint32 * 1
+        # number of time steps - uint32 * 1
+        # OPTIONAL:
+        #     starting time step - float32 * 1 (integral value in reality)
+        #     time step interval - float32 * 1 (integral value in reality)
+        # node ids             - uint32 * number of nodes
+        # data                 - (float32 * number of nodes) * number of time_steps
+
+        file_size = Path(filename).stat().st_size
+
+        with open(filename, "rb") as file:
+            num_nodes = np.fromfile(file, dtype=np.uint32, count=1)[0]
+            num_time_steps = np.fromfile(file, dtype=np.uint32, count=1)[0]
+
+            simple_size = (2 + num_nodes + (num_nodes * num_time_steps)) * 4    # num_nodes, num_time_steps, node_ids, and data
+            filtered_size = simple_size + 8     # include starting time step and time step interval
+
+            if file_size == simple_size:
+                self._start = 0
+                self._interval = 1
+            elif file_size == filtered_size:
+                self._start = int(np.fromfile(file, dtype=np.float32, count=1)[0])
+                self._interval = int(np.fromfile(file, dtype=np.float32, count=1)[0])
+                assert self.start >= 0
+                assert self.interval >= 1
+            else:
+                raise RuntimeError(f"Unexpected file size {file_size}, expected {simple_size} (standard spatial report) or {filtered_size} (filtered spatial report).")
+
+            node_ids = np.fromfile(file, dtype=np.uint32, count=num_nodes)
+            data = np.fromfile(file, dtype=np.float32, count=num_nodes * num_time_steps)
+
+        # let us index data[step, node]
+        data = data.reshape((num_time_steps, num_nodes))
+        self._from_node_ids_and_data(node_ids, data, self._start, self._interval)
+
+        return
+
+    def _from_node_ids_and_data(self, node_ids: list, data: np.array, start: int, interval: int) -> None:
+
+        assert _is_iterable(node_ids), "node_ids must be specified and iterable"
+        concrete = list(node_ids)
+        assert len(concrete) > 0, "node_ids must not be empty"
+        assert all(map(lambda i: _isinteger(i), concrete)), "node_ids must be integers"
+        assert len(set(concrete)) == len(concrete), "node_ids must be unique"
+        self._node_ids = sorted(concrete)
+        assert data.dtype is np.dtype("float32"), "data must be np.float32"
+        assert data.shape[1] == len(
+            self._node_ids
+        ), "data shape must be (#values, #nodes)"
+        self._data = data
+
+        self._node_id_to_index_map = {
+            node_ids[n]: n for n in range(data.shape[NUM_NODES_INDEX])
+        }
+        self._nodes = {
+            node_id: SpatialNode(node_id, data[:, self._node_id_to_index_map[node_id]])
+            for node_id in node_ids
+        }
+
+        assert int(start) >= 0, "start sample time must be >= 0"
+        self._start = int(start)
+        assert int(interval) >= 1, "sample interval must be >= 1"
+        self._interval = int(interval)
+
+        return
+
+
+def _is_iterable(obj) -> bool:
+    try:
+        _ = iter(obj)
+        return True
+    except TypeError:
+        return False
+
+
+def _isinteger(item) -> bool:
+    return isinstance(item, (int, np.integer))

emod_api/utils/__init__.py

@@ -0,0 +1,26 @@
+from collections.abc import Iterable
+
+
+def check_dimensionality(data, dimensionality: int) -> bool:
+    """
+    Returns True/False: is the provided data a matrix of the specified dimensionality?
+    Args:
+        data: An object to check the dimensionality of
+        dimensionality: The expected dimensionality
+
+    Returns:
+        True if data dimensionality is as expected, False if not.
+    """
+    ret = True
+    if dimensionality == 0:
+        if isinstance(data, Iterable):
+            ret = False  # expected to NOT be iterable still, but it is
+    else:
+        if isinstance(data, Iterable):
+            for item in data:
+                if check_dimensionality(data=item, dimensionality=dimensionality - 1) is False:
+                    ret = False
+                    break
+        else:
+            ret = False  # expected to be iterable still, but it isn't
+    return ret

emod_api/utils/distributions/base_distribution.py

@@ -0,0 +1,38 @@
+from abc import ABC, abstractmethod
+from emod_api import schema_to_class as s2c
+
+
+class BaseDistribution(ABC):
+    """
+    Abstract base class for distribution classes such as UniformDistribution and ExpoentialDistribution. This class
+    should not be instantiated directly.
+    """
+
+    @abstractmethod
+    def set_intervention_distribution(self, intervention_object: s2c.ReadOnlyDict, prefix: str):
+        """
+        Set the distribution parameters to the intervention object.
+
+        Args:
+            intervention_object (s2c.ReadOnlyDict):
+                - The object to set.
+            prefix (str):
+                - The prefix of the parameters.
+        """
+        pass
+
+    @abstractmethod
+    def get_demographic_distribution_parameters(self) -> dict:
+        """
+        Yield the flag and relevant values necessary for setting a demographics distribution of the class type
+
+        Returns:
+            a dict of the form: {'flag': X, 'value1': Y, 'value2': Z}
+        """
+        pass
+
+    def _set_parameters(self, emod_object, key, value):
+        if hasattr(emod_object, key):
+            setattr(emod_object, key, value)
+        else:
+            raise AttributeError(f"Attribute {key} does not exist in {emod_object.__class__.__name__}")

emod_api/utils/distributions/bimodal_distribution.py

@@ -0,0 +1,64 @@
+from emod_api import schema_to_class as s2c
+from emod_api.utils.distributions.base_distribution import BaseDistribution
+from emod_api.utils.distributions.demographic_distribution_flag import DemographicDistributionFlag
+
+
+class BimodalDistribution(BaseDistribution):
+    """
+    This class represents a bimodal distribution, a type of statistical distribution with two different modes (peaks).
+    A bimodal distribution is defined by two parameters: the proportion of the second bin, user defined bin, and the
+    constant value of the second bin. The 1-proportion will be the first bin and constant value in the first bin is 1.
+
+    This distribution is not supported in EMOD interventions.
+
+    Args:
+        proportion (float):
+            - The proportion of the second bin.
+            - This value should be between 0 and 1.
+
+        constant (float):
+            - The constant value of the second bin.
+            - The value should not be negative.
+
+    Examples:
+        >>> # Create a BimodalDistribution object.
+        >>> # In the follow example, there will be 20% of the second bin(5) and 80% of the first bin(1).
+        >>> bd = BimodalDistribution(0.2, 5)
+        >>> # The proportion and constant attributes can be accessed and updated.
+        >>> bd.proportion
+        0.2
+        >>> bd.constant
+        5
+        >>> bd.proportion = 0.6
+        >>> bd.proportion
+        0.6
+
+    """
+    DEMOGRAPHIC_DISTRIBUTION_FLAG = DemographicDistributionFlag.BIMODAL.value
+
+    def __init__(self, proportion: float, constant: float):
+        super().__init__()
+        if proportion < 0 or proportion > 1:
+            raise ValueError("The 'proportion' argument should be between 0 and 1.")
+        if constant < 0:
+            raise ValueError("The 'constant' argument should not be negative.")
+        self.proportion = proportion
+        self.constant = constant
+
+    def set_intervention_distribution(self, intervention_object: s2c.ReadOnlyDict, prefix: str):
+        """
+        This function is not supported in the intervention object. Raise NotImplementedError if called.
+        """
+        raise NotImplementedError("BimodalDistribution does not support intervention distribution. Please use "
+                                  "other distributions.")
+
+    def get_demographic_distribution_parameters(self) -> dict:
+        """
+        Yield the flag and relevant values necessary for setting a demographics bimodal distribution
+
+        Returns:
+            a dict of the form: {'flag': X, 'value1': Y, 'value2': Z}
+        """
+        return {"flag": self.DEMOGRAPHIC_DISTRIBUTION_FLAG,
+                "value1": self.proportion,
+                "value2": self.constant}

emod_api/utils/distributions/constant_distribution.py

@@ -0,0 +1,58 @@
+from emod_api import schema_to_class as s2c
+from emod_api.utils.distributions.base_distribution import BaseDistribution
+from emod_api.utils.distributions.demographic_distribution_flag import DemographicDistributionFlag
+from emod_api.utils.distributions.distribution_type import DistributionType
+
+
+class ConstantDistribution(BaseDistribution):
+    """
+    This class represents a constant distribution, a type of statistical distribution where all outcomes are equally
+    likely. A constant distribution is defined by a single value that is returned for all inputs.
+
+    Args:
+        value (float):
+            - The constant value that this distribution returns.
+            - The value should not be negative.
+
+    Raises:
+        ValueError: If the 'value' argument is negative.
+
+    Example:
+        >>> # Create a ConstantDistribution object.
+        >>> cd = ConstantDistribution(5)
+        >>> # The value attribute can be accessed and updated.
+        >>> cd.value
+        5
+        >>> cd.value = 10
+        >>> cd.value
+        10
+    """
+    DEMOGRAPHIC_DISTRIBUTION_FLAG = DemographicDistributionFlag.CONSTANT.value
+
+    def __init__(self, value: float):
+        super().__init__()
+        if value < 0:
+            raise ValueError("The 'value' argument should not be negative.")
+        self.value = value
+
+    def set_intervention_distribution(self, intervention_object: s2c.ReadOnlyDict, prefix: str):
+        """
+        Set the distribution parameters to the object.
+
+        Args:
+            intervention_object (s2c.ReadOnlyDict):
+                - The object to set.
+            prefix (str):
+                - The prefix of the parameters.
+        """
+        self._set_parameters(intervention_object, f"{prefix}_Distribution", DistributionType.CONSTANT_DISTRIBUTION.value)
+        self._set_parameters(intervention_object, f"{prefix}_Constant", self.value)
+
+    def get_demographic_distribution_parameters(self) -> dict:
+        """
+        Yield the flag and relevant values necessary for setting a demographics constant distribution
+
+        Returns:
+            a dict of the form: {'flag': X, 'value1': Y, 'value2': Z}
+        """
+        return {"flag": self.DEMOGRAPHIC_DISTRIBUTION_FLAG, "value1": self.value, "value2": None}  # value 2 not used

emod_api/utils/distributions/demographic_distribution_flag.py

@@ -0,0 +1,16 @@
+from enum import Enum
+
+
+class DemographicDistributionFlag(Enum):
+    CONSTANT = 0
+    UNIFORM = 1
+    GAUSSIAN = 2
+    EXPONENTIAL = 3
+    POISSON = 4
+    LOG_NORMAL = 5
+    BIMODAL = 6
+    WEIBULL = 7
+
+    # Not supported for demographics
+    # DUAL_CONSTANT = -1
+    # DUAL_EXPONENTIAL = -2

emod_api/utils/distributions/distribution_type.py

@@ -0,0 +1,15 @@
+from emod_api.utils.str_enum import StrEnum
+
+
+class DistributionType(StrEnum):
+    NOT_INITIALIZED = 'NOT_INITIALIZED'
+    CONSTANT_DISTRIBUTION = 'CONSTANT_DISTRIBUTION'
+    UNIFORM_DISTRIBUTION = 'UNIFORM_DISTRIBUTION'
+    GAUSSIAN_DISTRIBUTION = 'GAUSSIAN_DISTRIBUTION'
+    EXPONENTIAL_DISTRIBUTION = 'EXPONENTIAL_DISTRIBUTION'
+    POISSON_DISTRIBUTION = 'POISSON_DISTRIBUTION'
+    LOG_NORMAL_DISTRIBUTION = 'LOG_NORMAL_DISTRIBUTION'
+    DUAL_CONSTANT_DISTRIBUTION = 'DUAL_CONSTANT_DISTRIBUTION'
+    WEIBULL_DISTRIBUTION = 'WEIBULL_DISTRIBUTION'
+    DUAL_EXPONENTIAL_DISTRIBUTION = 'DUAL_EXPONENTIAL_DISTRIBUTION'
+    BIMODAL_DISTRIBUTION = 'BIMODAL_DISTRIBUTION'

emod_api/utils/distributions/dual_constant_distribution.py

@@ -0,0 +1,68 @@
+from emod_api import schema_to_class as s2c
+from emod_api.utils.distributions.base_distribution import BaseDistribution
+from emod_api.utils.distributions.distribution_type import DistributionType
+
+
+class DualConstantDistribution(BaseDistribution):
+    """
+    This class represents a dual constant distribution, a type of statistical distribution where the outcomes are
+    distributed between a constant value and zero based on a proportion. A dual constant
+    distribution is defined by two parameters: the proportion and the constant value.
+
+    This distribution is not supported in EMOD demographics.
+
+    Args:
+        proportion (float):
+            - The proportion of value of zero.
+            - This value should be between 0 and 1.
+
+        constant (float):
+            - The second constant value that this distribution returns other than zero.
+            - The value should not be negative.
+
+    Raises:
+        ValueError: If 'proportion' argument is not between 0 and 1 or 'constant' argument is negative.
+
+    Example:
+        >>> # Create a DualConstantDistribution object.
+        >>> # In the follow example, there will be 20% of zeros and 80% of 5s.
+        >>> dcd = DualConstantDistribution(0.2, 5)
+        >>> # The proportion and constant attributes can be accessed and updated.
+        >>> dcd.proportion
+        0.2
+        >>> dcd.constant
+        5
+        >>> dcd.proportion = 0.6
+        >>> dcd.proportion
+        0.6
+    """
+    def __init__(self, proportion: float, constant: float):
+        if proportion < 0 or proportion > 1:
+            raise ValueError("The 'proportion' argument should be between 0 and 1.")
+        if constant < 0:
+            raise ValueError("The 'constant' argument should not be negative.")
+        super().__init__()
+        self.proportion = proportion
+        self.constant = constant
+
+    def set_intervention_distribution(self, intervention_object: s2c.ReadOnlyDict, prefix: str):
+        """
+        Set the distribution parameters to the object.
+
+        Args:
+            intervention_object (s2c.ReadOnlyDict):
+                - The object to set.
+            prefix (str):
+                - The prefix of the parameters.
+        """
+        self._set_parameters(intervention_object, f"{prefix}_Distribution",
+                             DistributionType.DUAL_CONSTANT_DISTRIBUTION.value)
+        self._set_parameters(intervention_object, f"{prefix}_Proportion_0", self.proportion)
+        self._set_parameters(intervention_object, f"{prefix}_Peak_2_Value", self.constant)
+
+    def get_demographic_distribution_parameters(self) -> dict:
+        """
+        This function is not supported in the demographic object. Raise NotImplementedError if called.
+        """
+        raise NotImplementedError("DualConstantDistribution does not support demographic distribution. Please use "
+                                  "other distributions.")

emod_api/utils/distributions/dual_exponential_distribution.py

@@ -0,0 +1,75 @@
+from emod_api import schema_to_class as s2c
+from emod_api.utils.distributions.base_distribution import BaseDistribution
+from emod_api.utils.distributions.distribution_type import DistributionType
+
+
+class DualExponentialDistribution(BaseDistribution):
+    """
+    This class represents a dual exponential distribution, a type of statistical distribution where the outcomes are
+    distributed between two exponential distributions based on a proportion. A dual exponential distribution is defined
+    by three parameters: the proportion, the first mean, and the second mean.
+
+    This distribution is not supported in EMOD demographics.
+
+    Args:
+        proportion (float):
+            - The proportion of the first exponential distribution.
+            - This value should be between 0 and 1.
+
+        mean_1 (float):
+            - The mean of the first exponential distribution.
+            - This value should be positive.
+
+        mean_2 (float):
+            - The mean of the second exponential distribution.
+            - This value should be positive.
+
+    Raises:
+        ValueError: If 'proportion' argument is not between 0 and 1 or 'mean_1' or 'mean_2' arguments are negative.
+
+    Example:
+        >>> # Create a DualExponentialDistribution object.
+        >>> # In the follow example, there will be 20% of the first exponential distribution and 80% of the second.
+        >>> ded = DualExponentialDistribution(0.2, 1, 2)
+        >>> # The proportion, mean_1, and mean_2 attributes can be accessed and updated.
+        >>> ded.proportion
+        0.2
+        >>> ded.mean_1
+        1
+        >>> ded.mean_2
+        2
+        >>> ded.proportion = 0.6
+        >>> ded.proportion
+        0.6
+    """
+    def __init__(self, proportion: float, mean_1: float, mean_2: float):
+        if proportion < 0 or proportion > 1:
+            raise ValueError("The 'proportion' argument should be between 0 and 1.")
+        if mean_1 <= 0 or mean_2 <= 0:
+            raise ValueError("The 'mean_1' and 'mean_2' arguments should be positive.")
+        super().__init__()
+        self.proportion = proportion
+        self.mean_1 = mean_1
+        self.mean_2 = mean_2
+
+    def set_intervention_distribution(self, intervention_object: s2c.ReadOnlyDict, prefix: str):
+        """
+        Set the distribution parameters to the object.
+
+        Args:
+            intervention_object (s2c.ReadOnlyDict):
+                - The object to set.
+            prefix (str):
+                - The prefix of the parameters.
+        """
+        self._set_parameters(intervention_object, f"{prefix}_Distribution", DistributionType.DUAL_EXPONENTIAL_DISTRIBUTION.value)
+        self._set_parameters(intervention_object, f"{prefix}_Proportion_1", self.proportion)
+        self._set_parameters(intervention_object, f"{prefix}_Mean_1", self.mean_1)
+        self._set_parameters(intervention_object, f"{prefix}_Mean_2", self.mean_2)
+
+    def get_demographic_distribution_parameters(self) -> None:
+        """
+        This function is not supported in the demographic object. Raise NotImplementedError if called.
+        """
+        raise NotImplementedError("DualExponentialDistribution does not support demographic distribution. Please use "
+                                  "other distributions.")

emod_api/utils/distributions/exponential_distribution.py

@@ -0,0 +1,63 @@
+from emod_api import schema_to_class as s2c
+from emod_api.utils.distributions.base_distribution import BaseDistribution
+from emod_api.utils.distributions.demographic_distribution_flag import DemographicDistributionFlag
+from emod_api.utils.distributions.distribution_type import DistributionType
+
+
+class ExponentialDistribution(BaseDistribution):
+    """
+    This class represents an exponential distribution, a type of statistical distribution
+    where the probability of an event decreases exponentially with time.
+    An exponential distribution is defined by a single parameter: the mean, which represents the average time
+    between events.
+
+    Args:
+        mean (float):
+            - The mean, also the scale parameter of the exponential distribution.
+            - It's the 1/rate parameter.
+            - This value is set during the initialization of the class instance. It can be updated using the 'update_attribute()' method.
+            - The value should not be negative.
+
+    Raises:
+        ValueError: If 'mean' argument is negative.
+
+    Example:
+        >>> # Create an ExponentialDistribution object.
+        >>> ed = ExponentialDistribution(1)
+        >>> # The mean attribute can be accessed and updated.
+        >>> ed.mean
+        1
+        >>> ed.mean = 2
+        >>> ed.mean
+        2
+    """
+    DEMOGRAPHIC_DISTRIBUTION_FLAG = DemographicDistributionFlag.EXPONENTIAL.value
+
+    def __init__(self, mean: float):
+        super().__init__()
+        if mean < 0:
+            raise ValueError("The 'mean' argument should not be negative.")
+        self.mean = mean
+
+    def set_intervention_distribution(self, intervention_object: s2c.ReadOnlyDict, prefix: str):
+        """
+        Set the distribution parameters to the object.
+
+        Args:
+            intervention_object (s2c.ReadOnlyDict):
+                - The object to set.
+            prefix (str):
+                - The prefix of the parameters.
+        """
+        self._set_parameters(intervention_object, f"{prefix}_Distribution",
+                             DistributionType.EXPONENTIAL_DISTRIBUTION.value)
+        self._set_parameters(intervention_object, f"{prefix}_Exponential", self.mean)
+
+    def get_demographic_distribution_parameters(self) -> dict:
+        """
+        Yield the flag and relevant values necessary for setting a demographics exponential distribution
+
+        Returns:
+            a dict of the form: {'flag': X, 'value1': Y, 'value2': Z}
+        """
+        return {"flag": self.DEMOGRAPHIC_DISTRIBUTION_FLAG, "value1": self.mean, "value2": None}  # value2 not used