malaria_demographics

`MalariaDemographics`

Bases: Demographics

Malaria-specific demographics, extending emodpy's Demographics.

Uses MalariaNode instead of plain Node so that malaria-only demographics distributions (risk, innate immune) are available.

Adds features:

set_fertility_distribution() — age-and-year pregnancy rates
set_risk_distribution() — heterogeneous biting risk via demographics
set_innate_immune_distribution() — heterogeneous innate immunity
set_initial_prevalence_distribution() — initial infection prevalence
set_migration_heterogeneity() — per-individual migration rate heterogeneity
add_vector_migration() — per-species vector migration
add_weather() — weather files with node/idref validation

Inherited from base (see DemographicsBase):

set_age_distribution() — initial age distribution (simple or complex)
set_mortality_distribution() — gendered mortality (complex)
set_susceptibility_distribution() — susceptibility (simple or complex)

Source code in emodpy_malaria/demographics/malaria_demographics.py

class MalariaDemographics(Demographics):
    """Malaria-specific demographics, extending emodpy's Demographics.

    Uses [MalariaNode](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/demographics/malaria_node/)
    instead of plain [Node](https://emod.idmod.org/emod-api/autoapi/emod_api/demographics/node/) so that
    malaria-only demographics distributions (risk, innate immune) are
    available.

    Adds features:

    - `set_fertility_distribution()` — age-and-year pregnancy rates
    - `set_risk_distribution()` — heterogeneous biting risk via demographics
    - `set_innate_immune_distribution()` — heterogeneous innate immunity
    - `set_initial_prevalence_distribution()` — initial infection prevalence
    - `set_migration_heterogeneity()` — per-individual migration rate heterogeneity
    - `add_vector_migration()` — per-species vector migration
    - `add_weather()` — weather files with node/idref validation

    Inherited from base (see [DemographicsBase](https://emod.idmod.org/emod-api/autoapi/emod_api/demographics/demographics_base/)):

    - `set_age_distribution()` — initial age distribution (simple or complex)
    - `set_mortality_distribution()` — gendered mortality (complex)
    - `set_susceptibility_distribution()` — susceptibility (simple or complex)
    """
    def __init__(self, nodes: list[Node], idref: str = None, default_node: Node = None, set_defaults: bool = True):
        """
        Object representation of an EMOD Demographics input (json) file.

        Args:
            nodes (list[Node]): list(Node) nodes to include in the Demographics object.
            idref (str): (string, optional) an identifier for the Demographics file. Used to co-identify sets of
                Demographics/overlay files as well as migration and weather files. No value will utilize a default (via inheritance).
            default_node (Node): (Node, optional) Represents default values for all **nodes**, unless overridden on a per-node
                basis. If not provided, one will be generated by the superclass.
            set_defaults (bool): (bool) Whether to set default node attributes on the default node. Defaults to True. Should
                always be True unless loading via Demographics.from_file() (to replicate in-file data fully).
        """
        super().__init__(nodes=nodes, idref=idref, default_node=default_node)
        if set_defaults:
            # required for vector simulations
            self.default_node.node_attributes.altitude = 0

    def _generate_default_node(self) -> MalariaNode:
        default_node = MalariaNode(lat=0, lon=0, pop=0, name=self.DEFAULT_NODE_NAME, forced_id=0)
        default_node.birth_rate = 0
        return default_node

    def add_vector_migration(
        self,
        data: object,
        species: str,
        *,
        vector_migration_filename_path: Optional[str] = None,
        x_vector_migration: Optional[float] = None,
        filename: Optional[str] = None,
    ):
        """Add vector migration for a species.

        Provide either ``data`` (a [VectorMigrationData](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/migration/)
        object) or ``vector_migration_filename_path`` (path to an existing binary file),
        not both. The migration file is registered for inclusion in task assets, and an
        implicit config function is registered to set the per-species parameters at task
        build time.

        Args:
            data (object): VectorMigrationData object, or None if using **vector_migration_filename_path**.
            species (str): Species Name to target.
            vector_migration_filename_path (str): Path to a pre-existing binary migration file.
                Mutually exclusive with ``data``.
            x_vector_migration (float): Scale factor for the rate of vector migration to other nodes.
            filename (str): Output path for the binary file when using ``data``.
                If None, auto-generates as ``vector_migration_{species}.bin``.
        """
        from emodpy_malaria.vector_config import _set_vector_migration_config

        if not species:
            raise ValueError("species is required for vector migration.")

        if data is not None and vector_migration_filename_path is not None:
            raise ValueError(
                "Provide either data or vector_migration_filename_path, not both.")
        if data is None and not vector_migration_filename_path:
            raise ValueError(
                "Provide either data (VectorMigrationData) or "
                "vector_migration_filename_path (path to existing binary).")

        if data is not None:
            valid_ids = {n.id for n in self.nodes if n.id != 0}
            data_ids = set(data.node_ids)
            unknown = data_ids - valid_ids
            if unknown:
                raise ValueError(
                    f"Vector migration data contains node IDs not in "
                    f"demographics: {sorted(unknown)}")

            if data.idref != self.idref:
                logger.warning(
                    f"VectorMigrationData idref '{data.idref}' does not match "
                    f"demographics idref '{self.idref}'. Updating migration "
                    f"idref to '{self.idref}'.")
                data._idref = self.idref

            if filename is None:
                filename = f"vector_migration_{species}.bin"
            path = Path(filename).absolute()
            data.to_migration_file(path)
        else:
            path = Path(vector_migration_filename_path).absolute()
            if not path.exists():
                raise FileNotFoundError(
                    f"Vector migration file not found: {path}")

        self.migration_files.append(path)

        kwargs = dict(
            species=species,
            filename=path.name,
        )
        if x_vector_migration is not None:
            kwargs["x_vector_migration"] = x_vector_migration
        self.implicits.append(partial(_set_vector_migration_config, **kwargs))

    _RESOLUTION_SUFFIX = {
        ClimateUpdateResolution.CLIMATE_UPDATE_YEAR: "yearly",
        ClimateUpdateResolution.CLIMATE_UPDATE_MONTH: "monthly",
        ClimateUpdateResolution.CLIMATE_UPDATE_WEEK: "weekly",
        ClimateUpdateResolution.CLIMATE_UPDATE_DAY: "daily",
        ClimateUpdateResolution.CLIMATE_UPDATE_HOUR: "hourly",
    }

    def add_weather(
        self,
        data: WeatherSet,
        *,
        prefix: str = "",
        update_resolution: ClimateUpdateResolution = ClimateUpdateResolution.CLIMATE_UPDATE_DAY,
        air_temperature_offset: float = 0.0,
        air_temperature_variance: float = 0.0,
        rainfall_scale_factor: float = 1.0,
        relative_humidity_scale_factor: float = 1.0,
        relative_humidity_variance: float = 0.0,
        enable_rainfall_stochasticity: bool = False,
    ):
        """Add weather data files and configure ``CLIMATE_BY_DATA`` mode.

        Validates that weather data nodes match demographics nodes. Sets the
        weather files' ``IdReference`` to the demographics ``idref``. Writes
        three ``.bin`` / ``.bin.json`` file pairs (air temperature, rainfall,
        relative humidity), registers them as simulation assets, and sets
        climate config parameters at task build time.

        File names are generated automatically based on ``update_resolution``
        (e.g. ``airtemp_daily.bin``, ``rainfall_monthly.bin``). An optional
        *prefix* is prepended to each file name
        (e.g. ``prefix="era5_"`` produces ``era5_airtemp_daily.bin``).

        ``Land_Temperature_Filename`` is set to the air temperature file —
        EMOD requires it but does not use it for malaria simulations.

        ``Enable_Climate_Stochasticity`` is set automatically when any
        variance is non-zero or rainfall stochasticity is enabled.

        Args:
            data (WeatherSet): [WeatherSet](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/weather/) containing
                air temperature, rainfall, and relative humidity.
            prefix (str): String prepended to each weather file name. Default
                ``""`` (no prefix).
            update_resolution (ClimateUpdateResolution): Climate update frequency. Default
                ``ClimateUpdateResolution.CLIMATE_UPDATE_DAY``.
            air_temperature_offset (float): Additive offset applied to all air
                temperature values (Celsius).
            air_temperature_variance (float): Standard deviation (Celsius) for
                Gaussian noise on daily air temperature.
            rainfall_scale_factor (float): Multiplicative factor applied to all
                rainfall values.
            relative_humidity_scale_factor (float): Multiplicative factor applied to
                all relative humidity values.
            relative_humidity_variance (float): Standard deviation (fraction) for
                Gaussian noise on daily relative humidity.
            enable_rainfall_stochasticity (bool): Draw daily rainfall from an
                exponential distribution with mean equal to the data value.
        """
        from emodpy_malaria.weather.weather_variable import WeatherVariable
        from emodpy_malaria.weather.weather_config import set_climate_by_data

        if not isinstance(update_resolution, ClimateUpdateResolution):
            raise TypeError(
                f"update_resolution must be a ClimateUpdateResolution enum, "
                f"got {type(update_resolution).__name__}. "
                f"Valid options: {list(ClimateUpdateResolution)}")

        if not isinstance(data, WeatherSet):
            raise TypeError(
                f"data must be a WeatherSet instance, got {type(data).__name__}.")

        required_vars = set(WeatherVariable.list(exclude=WeatherVariable.LAND_TEMPERATURE))
        actual_vars = set(data.weather_variables)
        missing = required_vars - actual_vars
        if missing:
            raise ValueError(
                f"WeatherSet is missing required variables: "
                f"{[v.name for v in missing]}")

        demog_ids = {n.id for n in self.nodes if n.id != 0}
        data_ids = set(data.node_ids)
        extra = data_ids - demog_ids
        missing_nodes = demog_ids - data_ids
        if extra or missing_nodes:
            parts = []
            if extra:
                parts.append(f"extra nodes in weather data: {sorted(extra)}")
            if missing_nodes:
                parts.append(f"missing nodes in weather data: {sorted(missing_nodes)}")
            raise ValueError(
                "Weather data nodes must exactly match demographics nodes. "
                + "; ".join(parts))

        data.id_reference = self.idref
        data.update_resolution = update_resolution.value

        res_suffix = self._RESOLUTION_SUFFIX[update_resolution]
        file_names = WeatherSet.make_file_paths(
            prefix=prefix, suffix="{}_" + res_suffix + ".bin"
        )
        file_paths = {}
        for v, name in file_names.items():
            path = Path(name).absolute()
            file_paths[v] = path

        data.to_files(
            dir_path=file_paths[WeatherVariable.AIR_TEMPERATURE].parent,
            file_names={v: p.name for v, p in file_paths.items()},
        )

        for path in file_paths.values():
            self.migration_files.append(path)

        _VARIABLE_TO_FILENAME_PARAM = {
            WeatherVariable.AIR_TEMPERATURE: "air_temperature_filename",
            WeatherVariable.RAINFALL: "rainfall_filename",
            WeatherVariable.RELATIVE_HUMIDITY: "relative_humidity_filename",
        }
        filename_kwargs = {
            _VARIABLE_TO_FILENAME_PARAM[v]: p.name
            for v, p in file_paths.items()
            if v in _VARIABLE_TO_FILENAME_PARAM
        }

        self.implicits.append(partial(
            set_climate_by_data,
            **filename_kwargs,
            update_resolution=update_resolution,
            air_temperature_offset=air_temperature_offset,
            air_temperature_variance=air_temperature_variance,
            rainfall_scale_factor=rainfall_scale_factor,
            relative_humidity_scale_factor=relative_humidity_scale_factor,
            relative_humidity_variance=relative_humidity_variance,
            enable_rainfall_stochasticity=enable_rainfall_stochasticity,
        ))

    # -- Factory method overrides (use MalariaNode instead of Node) --

    @classmethod
    def from_template_node(cls,
                           lat: float = 0,
                           lon: float = 0,
                           pop: int = 1000000,
                           name: str = "Erewhon",
                           forced_id: int = 1) -> "MalariaDemographics":
        """Create a single-node MalariaDemographics using a [MalariaNode](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/demographics/malaria_node/).

        Args:
            lat (float): Latitude of the node. Default 0.
            lon (float): Longitude of the node. Default 0.
            pop (int): Initial population. Default 1,000,000.
            name (str): Node name. Default ``"Erewhon"``.
            forced_id (int): Node ID. Default 1.

        Returns:
            A new MalariaDemographics instance.
        """
        new_nodes = [MalariaNode(lat=lat, lon=lon, pop=pop, forced_id=forced_id, name=name)]
        return cls(nodes=new_nodes)

    @classmethod
    def from_file(cls, path: str) -> "MalariaDemographics":
        """Load a MalariaDemographics from an existing demographics JSON file.

        Uses [MalariaNode](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/demographics/malaria_node/) so that malaria-specific distributions
        (risk, innate immune) are preserved when loading from file.

        Args:
            path (str): Path to an EMOD demographics JSON file.

        Returns:
            A MalariaDemographics instance.
        """
        import warnings
        warnings.warn(
            "Loading Demographics from JSON files is deprecated. Objects should be created "
            "via Python code whenever possible as that route is by far the most tested for "
            "modern EMOD compatibility.",
            DeprecationWarning,
            stacklevel=2,
        )
        with open(path, "r") as src:
            demographics_dict = json.load(src)
        demographics_dict["Defaults"]["NodeID"] = 0
        implicit_functions = []
        nodes = []
        for node_dict in demographics_dict["Nodes"]:
            node, implicits = MalariaNode.from_data(data=node_dict)
            implicit_functions.extend(implicits)
            nodes.append(node)
        default_node, implicits = MalariaNode.from_data(data=demographics_dict["Defaults"])
        implicit_functions.extend(implicits)
        metadata = demographics_dict["Metadata"]
        idref = metadata["IdReference"]

        demographics = cls(nodes=nodes, default_node=default_node, idref=idref, set_defaults=False)
        demographics.metadata = metadata
        demographics.implicits.extend(implicit_functions)
        return demographics

    # -- Distribution setters --

    def set_fertility_distribution(self,
                                   distribution: FertilityDistribution,
                                   node_ids: list[int] = None) -> None:
        """Set a fertility distribution for individual-pregnancy birth rates.

        The fertility distribution defines age-and-year-specific pregnancy
        rates for women of reproductive age. Automatically sets
        ``Birth_Rate_Dependence = "INDIVIDUAL_PREGNANCIES_BY_AGE_AND_YEAR"``
        at task build time.

        Args:
            distribution (FertilityDistribution): A
                [FertilityDistribution](https://emod.idmod.org/emod-api/autoapi/emod_api/demographics/fertility_distribution/)
                defining age-and-year-specific pregnancy rates.
            node_ids (list[int]): Node id(s) to apply to. ``None`` targets the default node.

        Raises:
            TypeError: If *distribution* is not a FertilityDistribution.
        """
        if not isinstance(distribution, FertilityDistribution):
            raise TypeError(
                f"distribution must be a FertilityDistribution instance, "
                f"got {type(distribution).__name__}.")
        from emod_api.demographics.implicit_functions import _set_fertility_age_year
        self._set_distribution(
            distribution=distribution,
            use_case="fertility",
            complex_distribution_implicits=[_set_fertility_age_year],
            node_ids=node_ids,
        )

    def set_risk_distribution(self, distribution: BaseDistribution, node_ids: list[int] = None) -> None:
        """Set the risk distribution for demographics-based heterogeneous biting.

        Each individual is assigned a risk multiplier drawn from this
        distribution at initialization/birth, scaling their probability of being
        bitten relative to others.

        Args:
            distribution (BaseDistribution): A
                [BaseDistribution](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/utils/distributions/)
                defining the simple distribution for individual risk values.
                Valid distributions: ``ConstantDistribution``, ``UniformDistribution``,
                ``GaussianDistribution``, ``ExponentialDistribution``, ``PoissonDistribution``,
                ``LogNormalDistribution``, ``BimodalDistribution``, ``WeibullDistribution``.
                ``DualConstantDistribution`` and ``DualExponentialDistribution`` are not
                supported for demographics and will raise ``NotImplementedError``.
            node_ids (list[int]): Node id(s) to apply to. ``None`` targets the default node.

        Raises:
            TypeError: If *distribution* is not a BaseDistribution.
        """
        if not isinstance(distribution, BaseDistribution):
            raise TypeError(
                f"distribution must be a BaseDistribution instance (simple distribution), "
                f"got {type(distribution).__name__}.")
        self._set_distribution(
            distribution=distribution,
            use_case="risk",
            simple_distribution_implicits=[_set_enable_demog_risk],
            node_ids=node_ids,
        )

    def set_innate_immune_distribution(
        self,
        distribution: Optional[BaseDistribution],
        innate_immune_variation_type: Union[InnateImmuneVariationType, str],
        node_ids: list[int] = None,
    ) -> None:
        """Set the innate immune distribution for heterogeneous innate immunity.

        Each individual is assigned an innate-immunity modifier drawn
        from *distribution* at initialization.

        For EMOD parameter details, see
        [Innate immune variation](https://emod.idmod.org/emodpy-malaria/emod/model-heterogeneity/#innate-immune-variation).

        Args:
            distribution (Optional[BaseDistribution]): A
                [BaseDistribution](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/utils/distributions/)
                defining the simple distribution for innate-immunity modifier values.
                Must be ``None`` for ``PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE``
                (the distribution is forced internally to Uniform(0, 1)); must be a valid
                BaseDistribution for all other types.
            innate_immune_variation_type (Union[InnateImmuneVariationType, str]): How the drawn value modifies innate
                immunity. Accepts a [InnateImmuneVariationType](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/utils/emod_enum/)
                member or its string value. ``NONE`` is rejected — no distribution is needed when
                variation is disabled. Values:

                - ``PYROGENIC_THRESHOLD`` — individual threshold = ``v * Pyrogenic_Threshold``.
                - ``CYTOKINE_KILLING`` — individual kill rate = ``v * Fever_IRBC_Kill_Rate``.
                - ``PYROGENIC_THRESHOLD_VS_AGE_CONCAVE`` — threshold starts at
                  ``v * Pyrogenic_Threshold`` and decreases with age: under 2 years it
                  increases linearly (``+ 0.035 * threshold * age_years``); over 2 years
                  it decays exponentially toward 10% of the initial value
                  (``threshold * 0.965 * exp(-0.09 * (age_years - 2)) + threshold * 0.1``).
                  Updated every 3 months. Bounded by ``Pyrogenic_Threshold_Min/Max``.
                - ``PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE``
                  — pyrogenic threshold = ``v * Pyrogenic_Threshold * 10^(0.132 * age_years)``,
                  capped at ``Pyrogenic_Threshold_Max``; cytokine kill rate =
                  ``Fever_IRBC_Kill_Rate * (2 - v)``. Distribution is forced internally to
                  Uniform(0, 1); pass ``distribution=None``.

            node_ids (list[int]): Node id(s) to apply to. ``None`` targets the default node.

        Raises:
            TypeError: If *distribution* is not a BaseDistribution for types other than
                ``PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE``.
            ValueError: If *innate_immune_variation_type* is ``NONE`` or invalid, or if
                *distribution* is not ``None`` for
                ``PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE``.
        """
        if not isinstance(innate_immune_variation_type, InnateImmuneVariationType):
            try:
                innate_immune_variation_type = InnateImmuneVariationType(innate_immune_variation_type)
            except ValueError:
                raise ValueError(
                    f"Invalid innate_immune_variation_type {innate_immune_variation_type!r}. "
                    f"Valid options: {list(InnateImmuneVariationType)}")
        if innate_immune_variation_type == InnateImmuneVariationType.NONE:
            raise ValueError(
                "innate_immune_variation_type cannot be NONE when setting a distribution. "
                "NONE disables innate immune variation entirely.")
        _UNIFORM_INTERNAL = InnateImmuneVariationType.PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE
        if innate_immune_variation_type == _UNIFORM_INTERNAL:
            if distribution is not None:
                raise ValueError(
                    f"distribution must be None for {_UNIFORM_INTERNAL.value!r} — "
                    "the distribution is forced internally to Uniform(0, 1).")
            self.implicits.append(
                partial(_set_innate_immune_variation_type,
                        variation_type=innate_immune_variation_type.value)
            )
        else:
            if not isinstance(distribution, BaseDistribution):
                raise TypeError(
                    f"distribution must be a BaseDistribution instance (simple distribution), "
                    f"got {type(distribution).__name__}.")
            self._set_distribution(
                distribution=distribution,
                use_case="innate_immune",
                simple_distribution_implicits=[
                    partial(_set_innate_immune_variation_type,
                            variation_type=innate_immune_variation_type.value)
                ],
                node_ids=node_ids,
            )

    def set_initial_prevalence_distribution(self, distribution: BaseDistribution, node_ids: list[int] = None) -> None:
        """Set the initial infection prevalence distribution per simulation.

        Each node starts with its own initial prevalence, a value drawn from this
        distribution at the start of the simulation.

        Args:
            distribution (BaseDistribution): A
                [BaseDistribution](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/utils/distributions/)
                defining the simple distribution for initial prevalence values.
                Valid distributions: ``ConstantDistribution``, ``UniformDistribution``,
                ``GaussianDistribution``, ``ExponentialDistribution``, ``PoissonDistribution``,
                ``LogNormalDistribution``, ``BimodalDistribution``, ``WeibullDistribution``.
                ``DualConstantDistribution`` and ``DualExponentialDistribution`` are not
                supported for demographics and will raise ``NotImplementedError``.
            node_ids (list[int]): Node id(s) to apply to. ``None`` targets the default node.

        Raises:
            TypeError: If *distribution* is not a BaseDistribution.
        """
        if not isinstance(distribution, BaseDistribution):
            raise TypeError(
                f"distribution must be a BaseDistribution instance (simple distribution), "
                f"got {type(distribution).__name__}.")
        from emod_api.demographics.implicit_functions import _set_init_prev
        self._set_distribution(
            distribution=distribution,
            use_case="prevalence",
            simple_distribution_implicits=[_set_init_prev],
            node_ids=node_ids,
        )

    def set_migration_heterogeneity(self, distribution: BaseDistribution, node_ids: list[int] = None) -> None:
        """Set the migration heterogeneity distribution.

        Each individual is assigned a migration rate multiplier drawn from this
        distribution at creation/birth. Values >1 increase migration frequency
        relative to the base rate; values <1 reduce it.

        Human migration rates must be configured separately via ``add_migration()``.

        **Note:** This method is not specific to malaria and would ideally live in
        ``emodpy`` or ``emod-api`` so that downstream modules such as
        ``emodpy-hiv`` can reuse it without duplicating the implementation.

        Args:
            distribution (BaseDistribution): A
                [BaseDistribution](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/utils/distributions/)
                defining the simple distribution for per-individual migration rate multipliers.
                Valid distributions: ``ConstantDistribution``, ``UniformDistribution``,
                ``GaussianDistribution``, ``ExponentialDistribution``, ``PoissonDistribution``,
                ``LogNormalDistribution``, ``BimodalDistribution``, ``WeibullDistribution``.
                ``DualConstantDistribution`` and ``DualExponentialDistribution`` are not
                supported for demographics and will raise ``NotImplementedError``.
            node_ids (list[int]): Node id(s) to apply to. ``None`` targets the default node.

        Raises:
            TypeError: If *distribution* is not a BaseDistribution.
        """
        if not isinstance(distribution, BaseDistribution):
            raise TypeError(
                f"distribution must be a BaseDistribution instance (simple distribution), "
                f"got {type(distribution).__name__}.")
        from emod_api.demographics.implicit_functions import (
            _set_migration_model_fixed_rate,
            _set_enable_migration_model_heterogeneity,
        )
        self._set_distribution(
            distribution=distribution,
            use_case="migration_heterogeneity",
            simple_distribution_implicits=[
                _set_migration_model_fixed_rate,
                _set_enable_migration_model_heterogeneity,
            ],
            node_ids=node_ids,
        )

`init(nodes, idref=None, default_node=None, set_defaults=True)`

Object representation of an EMOD Demographics input (json) file.

Parameters:

Name	Type	Description	Default
`nodes`	`list[Node]`	list(Node) nodes to include in the Demographics object.	required
`idref`	`str`	(string, optional) an identifier for the Demographics file. Used to co-identify sets of Demographics/overlay files as well as migration and weather files. No value will utilize a default (via inheritance).	`None`
`default_node`	`Node`	(Node, optional) Represents default values for all nodes, unless overridden on a per-node basis. If not provided, one will be generated by the superclass.	`None`
`set_defaults`	`bool`	(bool) Whether to set default node attributes on the default node. Defaults to True. Should always be True unless loading via Demographics.from_file() (to replicate in-file data fully).	`True`

Source code in emodpy_malaria/demographics/malaria_demographics.py

def __init__(self, nodes: list[Node], idref: str = None, default_node: Node = None, set_defaults: bool = True):
    """
    Object representation of an EMOD Demographics input (json) file.

    Args:
        nodes (list[Node]): list(Node) nodes to include in the Demographics object.
        idref (str): (string, optional) an identifier for the Demographics file. Used to co-identify sets of
            Demographics/overlay files as well as migration and weather files. No value will utilize a default (via inheritance).
        default_node (Node): (Node, optional) Represents default values for all **nodes**, unless overridden on a per-node
            basis. If not provided, one will be generated by the superclass.
        set_defaults (bool): (bool) Whether to set default node attributes on the default node. Defaults to True. Should
            always be True unless loading via Demographics.from_file() (to replicate in-file data fully).
    """
    super().__init__(nodes=nodes, idref=idref, default_node=default_node)
    if set_defaults:
        # required for vector simulations
        self.default_node.node_attributes.altitude = 0

`add_vector_migration(data, species, *, vector_migration_filename_path=None, x_vector_migration=None, filename=None)`

Add vector migration for a species.

Provide either data (a VectorMigrationData object) or vector_migration_filename_path (path to an existing binary file), not both. The migration file is registered for inclusion in task assets, and an implicit config function is registered to set the per-species parameters at task build time.

Parameters:

Name	Type	Description	Default
`data`	`object`	VectorMigrationData object, or None if using vector_migration_filename_path.	required
`species`	`str`	Species Name to target.	required
`vector_migration_filename_path`	`str`	Path to a pre-existing binary migration file. Mutually exclusive with `data`.	`None`
`x_vector_migration`	`float`	Scale factor for the rate of vector migration to other nodes.	`None`
`filename`	`str`	Output path for the binary file when using `data`. If None, auto-generates as `vector_migration_{species}.bin`.	`None`

Source code in emodpy_malaria/demographics/malaria_demographics.py

def add_vector_migration(
    self,
    data: object,
    species: str,
    *,
    vector_migration_filename_path: Optional[str] = None,
    x_vector_migration: Optional[float] = None,
    filename: Optional[str] = None,
):
    """Add vector migration for a species.

    Provide either ``data`` (a [VectorMigrationData](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/migration/)
    object) or ``vector_migration_filename_path`` (path to an existing binary file),
    not both. The migration file is registered for inclusion in task assets, and an
    implicit config function is registered to set the per-species parameters at task
    build time.

    Args:
        data (object): VectorMigrationData object, or None if using **vector_migration_filename_path**.
        species (str): Species Name to target.
        vector_migration_filename_path (str): Path to a pre-existing binary migration file.
            Mutually exclusive with ``data``.
        x_vector_migration (float): Scale factor for the rate of vector migration to other nodes.
        filename (str): Output path for the binary file when using ``data``.
            If None, auto-generates as ``vector_migration_{species}.bin``.
    """
    from emodpy_malaria.vector_config import _set_vector_migration_config

    if not species:
        raise ValueError("species is required for vector migration.")

    if data is not None and vector_migration_filename_path is not None:
        raise ValueError(
            "Provide either data or vector_migration_filename_path, not both.")
    if data is None and not vector_migration_filename_path:
        raise ValueError(
            "Provide either data (VectorMigrationData) or "
            "vector_migration_filename_path (path to existing binary).")

    if data is not None:
        valid_ids = {n.id for n in self.nodes if n.id != 0}
        data_ids = set(data.node_ids)
        unknown = data_ids - valid_ids
        if unknown:
            raise ValueError(
                f"Vector migration data contains node IDs not in "
                f"demographics: {sorted(unknown)}")

        if data.idref != self.idref:
            logger.warning(
                f"VectorMigrationData idref '{data.idref}' does not match "
                f"demographics idref '{self.idref}'. Updating migration "
                f"idref to '{self.idref}'.")
            data._idref = self.idref

        if filename is None:
            filename = f"vector_migration_{species}.bin"
        path = Path(filename).absolute()
        data.to_migration_file(path)
    else:
        path = Path(vector_migration_filename_path).absolute()
        if not path.exists():
            raise FileNotFoundError(
                f"Vector migration file not found: {path}")

    self.migration_files.append(path)

    kwargs = dict(
        species=species,
        filename=path.name,
    )
    if x_vector_migration is not None:
        kwargs["x_vector_migration"] = x_vector_migration
    self.implicits.append(partial(_set_vector_migration_config, **kwargs))

`add_weather(data, *, prefix='', update_resolution=ClimateUpdateResolution.CLIMATE_UPDATE_DAY, air_temperature_offset=0.0, air_temperature_variance=0.0, rainfall_scale_factor=1.0, relative_humidity_scale_factor=1.0, relative_humidity_variance=0.0, enable_rainfall_stochasticity=False)`

Add weather data files and configure CLIMATE_BY_DATA mode.

Validates that weather data nodes match demographics nodes. Sets the weather files' IdReference to the demographics idref. Writes three .bin / .bin.json file pairs (air temperature, rainfall, relative humidity), registers them as simulation assets, and sets climate config parameters at task build time.

File names are generated automatically based on update_resolution (e.g. airtemp_daily.bin, rainfall_monthly.bin). An optional prefix is prepended to each file name (e.g. prefix="era5_" produces era5_airtemp_daily.bin).

Land_Temperature_Filename is set to the air temperature file — EMOD requires it but does not use it for malaria simulations.

Enable_Climate_Stochasticity is set automatically when any variance is non-zero or rainfall stochasticity is enabled.

Parameters:

Name	Type	Description	Default
`data`	`WeatherSet`	WeatherSet containing air temperature, rainfall, and relative humidity.	required
`prefix`	`str`	String prepended to each weather file name. Default `""` (no prefix).	`''`
`update_resolution`	`ClimateUpdateResolution`	Climate update frequency. Default `ClimateUpdateResolution.CLIMATE_UPDATE_DAY`.	`CLIMATE_UPDATE_DAY`
`air_temperature_offset`	`float`	Additive offset applied to all air temperature values (Celsius).	`0.0`
`air_temperature_variance`	`float`	Standard deviation (Celsius) for Gaussian noise on daily air temperature.	`0.0`
`rainfall_scale_factor`	`float`	Multiplicative factor applied to all rainfall values.	`1.0`
`relative_humidity_scale_factor`	`float`	Multiplicative factor applied to all relative humidity values.	`1.0`
`relative_humidity_variance`	`float`	Standard deviation (fraction) for Gaussian noise on daily relative humidity.	`0.0`
`enable_rainfall_stochasticity`	`bool`	Draw daily rainfall from an exponential distribution with mean equal to the data value.	`False`

Source code in emodpy_malaria/demographics/malaria_demographics.py

def add_weather(
    self,
    data: WeatherSet,
    *,
    prefix: str = "",
    update_resolution: ClimateUpdateResolution = ClimateUpdateResolution.CLIMATE_UPDATE_DAY,
    air_temperature_offset: float = 0.0,
    air_temperature_variance: float = 0.0,
    rainfall_scale_factor: float = 1.0,
    relative_humidity_scale_factor: float = 1.0,
    relative_humidity_variance: float = 0.0,
    enable_rainfall_stochasticity: bool = False,
):
    """Add weather data files and configure ``CLIMATE_BY_DATA`` mode.

    Validates that weather data nodes match demographics nodes. Sets the
    weather files' ``IdReference`` to the demographics ``idref``. Writes
    three ``.bin`` / ``.bin.json`` file pairs (air temperature, rainfall,
    relative humidity), registers them as simulation assets, and sets
    climate config parameters at task build time.

    File names are generated automatically based on ``update_resolution``
    (e.g. ``airtemp_daily.bin``, ``rainfall_monthly.bin``). An optional
    *prefix* is prepended to each file name
    (e.g. ``prefix="era5_"`` produces ``era5_airtemp_daily.bin``).

    ``Land_Temperature_Filename`` is set to the air temperature file —
    EMOD requires it but does not use it for malaria simulations.

    ``Enable_Climate_Stochasticity`` is set automatically when any
    variance is non-zero or rainfall stochasticity is enabled.

    Args:
        data (WeatherSet): [WeatherSet](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/weather/) containing
            air temperature, rainfall, and relative humidity.
        prefix (str): String prepended to each weather file name. Default
            ``""`` (no prefix).
        update_resolution (ClimateUpdateResolution): Climate update frequency. Default
            ``ClimateUpdateResolution.CLIMATE_UPDATE_DAY``.
        air_temperature_offset (float): Additive offset applied to all air
            temperature values (Celsius).
        air_temperature_variance (float): Standard deviation (Celsius) for
            Gaussian noise on daily air temperature.
        rainfall_scale_factor (float): Multiplicative factor applied to all
            rainfall values.
        relative_humidity_scale_factor (float): Multiplicative factor applied to
            all relative humidity values.
        relative_humidity_variance (float): Standard deviation (fraction) for
            Gaussian noise on daily relative humidity.
        enable_rainfall_stochasticity (bool): Draw daily rainfall from an
            exponential distribution with mean equal to the data value.
    """
    from emodpy_malaria.weather.weather_variable import WeatherVariable
    from emodpy_malaria.weather.weather_config import set_climate_by_data

    if not isinstance(update_resolution, ClimateUpdateResolution):
        raise TypeError(
            f"update_resolution must be a ClimateUpdateResolution enum, "
            f"got {type(update_resolution).__name__}. "
            f"Valid options: {list(ClimateUpdateResolution)}")

    if not isinstance(data, WeatherSet):
        raise TypeError(
            f"data must be a WeatherSet instance, got {type(data).__name__}.")

    required_vars = set(WeatherVariable.list(exclude=WeatherVariable.LAND_TEMPERATURE))
    actual_vars = set(data.weather_variables)
    missing = required_vars - actual_vars
    if missing:
        raise ValueError(
            f"WeatherSet is missing required variables: "
            f"{[v.name for v in missing]}")

    demog_ids = {n.id for n in self.nodes if n.id != 0}
    data_ids = set(data.node_ids)
    extra = data_ids - demog_ids
    missing_nodes = demog_ids - data_ids
    if extra or missing_nodes:
        parts = []
        if extra:
            parts.append(f"extra nodes in weather data: {sorted(extra)}")
        if missing_nodes:
            parts.append(f"missing nodes in weather data: {sorted(missing_nodes)}")
        raise ValueError(
            "Weather data nodes must exactly match demographics nodes. "
            + "; ".join(parts))

    data.id_reference = self.idref
    data.update_resolution = update_resolution.value

    res_suffix = self._RESOLUTION_SUFFIX[update_resolution]
    file_names = WeatherSet.make_file_paths(
        prefix=prefix, suffix="{}_" + res_suffix + ".bin"
    )
    file_paths = {}
    for v, name in file_names.items():
        path = Path(name).absolute()
        file_paths[v] = path

    data.to_files(
        dir_path=file_paths[WeatherVariable.AIR_TEMPERATURE].parent,
        file_names={v: p.name for v, p in file_paths.items()},
    )

    for path in file_paths.values():
        self.migration_files.append(path)

    _VARIABLE_TO_FILENAME_PARAM = {
        WeatherVariable.AIR_TEMPERATURE: "air_temperature_filename",
        WeatherVariable.RAINFALL: "rainfall_filename",
        WeatherVariable.RELATIVE_HUMIDITY: "relative_humidity_filename",
    }
    filename_kwargs = {
        _VARIABLE_TO_FILENAME_PARAM[v]: p.name
        for v, p in file_paths.items()
        if v in _VARIABLE_TO_FILENAME_PARAM
    }

    self.implicits.append(partial(
        set_climate_by_data,
        **filename_kwargs,
        update_resolution=update_resolution,
        air_temperature_offset=air_temperature_offset,
        air_temperature_variance=air_temperature_variance,
        rainfall_scale_factor=rainfall_scale_factor,
        relative_humidity_scale_factor=relative_humidity_scale_factor,
        relative_humidity_variance=relative_humidity_variance,
        enable_rainfall_stochasticity=enable_rainfall_stochasticity,
    ))

`from_file(path)` `classmethod`

Load a MalariaDemographics from an existing demographics JSON file.

Uses MalariaNode so that malaria-specific distributions (risk, innate immune) are preserved when loading from file.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to an EMOD demographics JSON file.	required

Returns:

Type	Description
`MalariaDemographics`	A MalariaDemographics instance.

Source code in emodpy_malaria/demographics/malaria_demographics.py

@classmethod
def from_file(cls, path: str) -> "MalariaDemographics":
    """Load a MalariaDemographics from an existing demographics JSON file.

    Uses [MalariaNode](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/demographics/malaria_node/) so that malaria-specific distributions
    (risk, innate immune) are preserved when loading from file.

    Args:
        path (str): Path to an EMOD demographics JSON file.

    Returns:
        A MalariaDemographics instance.
    """
    import warnings
    warnings.warn(
        "Loading Demographics from JSON files is deprecated. Objects should be created "
        "via Python code whenever possible as that route is by far the most tested for "
        "modern EMOD compatibility.",
        DeprecationWarning,
        stacklevel=2,
    )
    with open(path, "r") as src:
        demographics_dict = json.load(src)
    demographics_dict["Defaults"]["NodeID"] = 0
    implicit_functions = []
    nodes = []
    for node_dict in demographics_dict["Nodes"]:
        node, implicits = MalariaNode.from_data(data=node_dict)
        implicit_functions.extend(implicits)
        nodes.append(node)
    default_node, implicits = MalariaNode.from_data(data=demographics_dict["Defaults"])
    implicit_functions.extend(implicits)
    metadata = demographics_dict["Metadata"]
    idref = metadata["IdReference"]

    demographics = cls(nodes=nodes, default_node=default_node, idref=idref, set_defaults=False)
    demographics.metadata = metadata
    demographics.implicits.extend(implicit_functions)
    return demographics

`from_template_node(lat=0, lon=0, pop=1000000, name='Erewhon', forced_id=1)` `classmethod`

Create a single-node MalariaDemographics using a MalariaNode.

Parameters:

Name	Type	Description	Default
`lat`	`float`	Latitude of the node. Default 0.	`0`
`lon`	`float`	Longitude of the node. Default 0.	`0`
`pop`	`int`	Initial population. Default 1,000,000.	`1000000`
`name`	`str`	Node name. Default `"Erewhon"`.	`'Erewhon'`
`forced_id`	`int`	Node ID. Default 1.	`1`

Returns:

Type	Description
`MalariaDemographics`	A new MalariaDemographics instance.

Source code in emodpy_malaria/demographics/malaria_demographics.py

@classmethod
def from_template_node(cls,
                       lat: float = 0,
                       lon: float = 0,
                       pop: int = 1000000,
                       name: str = "Erewhon",
                       forced_id: int = 1) -> "MalariaDemographics":
    """Create a single-node MalariaDemographics using a [MalariaNode](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/demographics/malaria_node/).

    Args:
        lat (float): Latitude of the node. Default 0.
        lon (float): Longitude of the node. Default 0.
        pop (int): Initial population. Default 1,000,000.
        name (str): Node name. Default ``"Erewhon"``.
        forced_id (int): Node ID. Default 1.

    Returns:
        A new MalariaDemographics instance.
    """
    new_nodes = [MalariaNode(lat=lat, lon=lon, pop=pop, forced_id=forced_id, name=name)]
    return cls(nodes=new_nodes)

`set_fertility_distribution(distribution, node_ids=None)`

Set a fertility distribution for individual-pregnancy birth rates.

The fertility distribution defines age-and-year-specific pregnancy rates for women of reproductive age. Automatically sets Birth_Rate_Dependence = "INDIVIDUAL_PREGNANCIES_BY_AGE_AND_YEAR" at task build time.

Parameters:

Name	Type	Description	Default
`distribution`	`FertilityDistribution`	A FertilityDistribution defining age-and-year-specific pregnancy rates.	required
`node_ids`	`list[int]`	Node id(s) to apply to. `None` targets the default node.	`None`

Raises:

Type	Description
`TypeError`	If distribution is not a FertilityDistribution.

Source code in emodpy_malaria/demographics/malaria_demographics.py

def set_fertility_distribution(self,
                               distribution: FertilityDistribution,
                               node_ids: list[int] = None) -> None:
    """Set a fertility distribution for individual-pregnancy birth rates.

    The fertility distribution defines age-and-year-specific pregnancy
    rates for women of reproductive age. Automatically sets
    ``Birth_Rate_Dependence = "INDIVIDUAL_PREGNANCIES_BY_AGE_AND_YEAR"``
    at task build time.

    Args:
        distribution (FertilityDistribution): A
            [FertilityDistribution](https://emod.idmod.org/emod-api/autoapi/emod_api/demographics/fertility_distribution/)
            defining age-and-year-specific pregnancy rates.
        node_ids (list[int]): Node id(s) to apply to. ``None`` targets the default node.

    Raises:
        TypeError: If *distribution* is not a FertilityDistribution.
    """
    if not isinstance(distribution, FertilityDistribution):
        raise TypeError(
            f"distribution must be a FertilityDistribution instance, "
            f"got {type(distribution).__name__}.")
    from emod_api.demographics.implicit_functions import _set_fertility_age_year
    self._set_distribution(
        distribution=distribution,
        use_case="fertility",
        complex_distribution_implicits=[_set_fertility_age_year],
        node_ids=node_ids,
    )

`set_initial_prevalence_distribution(distribution, node_ids=None)`

Set the initial infection prevalence distribution per simulation.

Each node starts with its own initial prevalence, a value drawn from this distribution at the start of the simulation.

Parameters:

Name	Type	Description	Default
`distribution`	`BaseDistribution`	A BaseDistribution defining the simple distribution for initial prevalence values. Valid distributions: `ConstantDistribution`, `UniformDistribution`, `GaussianDistribution`, `ExponentialDistribution`, `PoissonDistribution`, `LogNormalDistribution`, `BimodalDistribution`, `WeibullDistribution`. `DualConstantDistribution` and `DualExponentialDistribution` are not supported for demographics and will raise `NotImplementedError`.	required
`node_ids`	`list[int]`	Node id(s) to apply to. `None` targets the default node.	`None`

Raises:

Type	Description
`TypeError`	If distribution is not a BaseDistribution.

Source code in emodpy_malaria/demographics/malaria_demographics.py

def set_initial_prevalence_distribution(self, distribution: BaseDistribution, node_ids: list[int] = None) -> None:
    """Set the initial infection prevalence distribution per simulation.

    Each node starts with its own initial prevalence, a value drawn from this
    distribution at the start of the simulation.

    Args:
        distribution (BaseDistribution): A
            [BaseDistribution](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/utils/distributions/)
            defining the simple distribution for initial prevalence values.
            Valid distributions: ``ConstantDistribution``, ``UniformDistribution``,
            ``GaussianDistribution``, ``ExponentialDistribution``, ``PoissonDistribution``,
            ``LogNormalDistribution``, ``BimodalDistribution``, ``WeibullDistribution``.
            ``DualConstantDistribution`` and ``DualExponentialDistribution`` are not
            supported for demographics and will raise ``NotImplementedError``.
        node_ids (list[int]): Node id(s) to apply to. ``None`` targets the default node.

    Raises:
        TypeError: If *distribution* is not a BaseDistribution.
    """
    if not isinstance(distribution, BaseDistribution):
        raise TypeError(
            f"distribution must be a BaseDistribution instance (simple distribution), "
            f"got {type(distribution).__name__}.")
    from emod_api.demographics.implicit_functions import _set_init_prev
    self._set_distribution(
        distribution=distribution,
        use_case="prevalence",
        simple_distribution_implicits=[_set_init_prev],
        node_ids=node_ids,
    )

`set_innate_immune_distribution(distribution, innate_immune_variation_type, node_ids=None)`

Set the innate immune distribution for heterogeneous innate immunity.

Each individual is assigned an innate-immunity modifier drawn from distribution at initialization.

For EMOD parameter details, see Innate immune variation.

Parameters:

Name	Type	Description	Default
`distribution`	`Optional[BaseDistribution]`	A BaseDistribution defining the simple distribution for innate-immunity modifier values. Must be `None` for `PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE` (the distribution is forced internally to Uniform(0, 1)); must be a valid BaseDistribution for all other types.	required
`innate_immune_variation_type`	`Union[InnateImmuneVariationType, str]`	How the drawn value modifies innate immunity. Accepts a InnateImmuneVariationType member or its string value. `NONE` is rejected — no distribution is needed when variation is disabled. Values: `PYROGENIC_THRESHOLD` — individual threshold = `v * Pyrogenic_Threshold`. `CYTOKINE_KILLING` — individual kill rate = `v * Fever_IRBC_Kill_Rate`. `PYROGENIC_THRESHOLD_VS_AGE_CONCAVE` — threshold starts at `v * Pyrogenic_Threshold` and decreases with age: under 2 years it increases linearly (`+ 0.035 * threshold * age_years`); over 2 years it decays exponentially toward 10% of the initial value (`threshold * 0.965 * exp(-0.09 * (age_years - 2)) + threshold * 0.1`). Updated every 3 months. Bounded by `Pyrogenic_Threshold_Min/Max`. `PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE` — pyrogenic threshold = `v * Pyrogenic_Threshold * 10^(0.132 * age_years)`, capped at `Pyrogenic_Threshold_Max`; cytokine kill rate = `Fever_IRBC_Kill_Rate * (2 - v)`. Distribution is forced internally to Uniform(0, 1); pass `distribution=None`.	required
`node_ids`	`list[int]`	Node id(s) to apply to. `None` targets the default node.	`None`

Raises:

Type	Description
`TypeError`	If distribution is not a BaseDistribution for types other than `PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE`.
`ValueError`	If innate_immune_variation_type is `NONE` or invalid, or if distribution is not `None` for `PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE`.

Source code in emodpy_malaria/demographics/malaria_demographics.py

def set_innate_immune_distribution(
    self,
    distribution: Optional[BaseDistribution],
    innate_immune_variation_type: Union[InnateImmuneVariationType, str],
    node_ids: list[int] = None,
) -> None:
    """Set the innate immune distribution for heterogeneous innate immunity.

    Each individual is assigned an innate-immunity modifier drawn
    from *distribution* at initialization.

    For EMOD parameter details, see
    [Innate immune variation](https://emod.idmod.org/emodpy-malaria/emod/model-heterogeneity/#innate-immune-variation).

    Args:
        distribution (Optional[BaseDistribution]): A
            [BaseDistribution](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/utils/distributions/)
            defining the simple distribution for innate-immunity modifier values.
            Must be ``None`` for ``PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE``
            (the distribution is forced internally to Uniform(0, 1)); must be a valid
            BaseDistribution for all other types.
        innate_immune_variation_type (Union[InnateImmuneVariationType, str]): How the drawn value modifies innate
            immunity. Accepts a [InnateImmuneVariationType](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/utils/emod_enum/)
            member or its string value. ``NONE`` is rejected — no distribution is needed when
            variation is disabled. Values:

            - ``PYROGENIC_THRESHOLD`` — individual threshold = ``v * Pyrogenic_Threshold``.
            - ``CYTOKINE_KILLING`` — individual kill rate = ``v * Fever_IRBC_Kill_Rate``.
            - ``PYROGENIC_THRESHOLD_VS_AGE_CONCAVE`` — threshold starts at
              ``v * Pyrogenic_Threshold`` and decreases with age: under 2 years it
              increases linearly (``+ 0.035 * threshold * age_years``); over 2 years
              it decays exponentially toward 10% of the initial value
              (``threshold * 0.965 * exp(-0.09 * (age_years - 2)) + threshold * 0.1``).
              Updated every 3 months. Bounded by ``Pyrogenic_Threshold_Min/Max``.
            - ``PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE``
              — pyrogenic threshold = ``v * Pyrogenic_Threshold * 10^(0.132 * age_years)``,
              capped at ``Pyrogenic_Threshold_Max``; cytokine kill rate =
              ``Fever_IRBC_Kill_Rate * (2 - v)``. Distribution is forced internally to
              Uniform(0, 1); pass ``distribution=None``.

        node_ids (list[int]): Node id(s) to apply to. ``None`` targets the default node.

    Raises:
        TypeError: If *distribution* is not a BaseDistribution for types other than
            ``PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE``.
        ValueError: If *innate_immune_variation_type* is ``NONE`` or invalid, or if
            *distribution* is not ``None`` for
            ``PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE``.
    """
    if not isinstance(innate_immune_variation_type, InnateImmuneVariationType):
        try:
            innate_immune_variation_type = InnateImmuneVariationType(innate_immune_variation_type)
        except ValueError:
            raise ValueError(
                f"Invalid innate_immune_variation_type {innate_immune_variation_type!r}. "
                f"Valid options: {list(InnateImmuneVariationType)}")
    if innate_immune_variation_type == InnateImmuneVariationType.NONE:
        raise ValueError(
            "innate_immune_variation_type cannot be NONE when setting a distribution. "
            "NONE disables innate immune variation entirely.")
    _UNIFORM_INTERNAL = InnateImmuneVariationType.PYROGENIC_THRESHOLD_VS_AGE_INCREASING_AND_CYTOKINE_KILLING_INVERSE
    if innate_immune_variation_type == _UNIFORM_INTERNAL:
        if distribution is not None:
            raise ValueError(
                f"distribution must be None for {_UNIFORM_INTERNAL.value!r} — "
                "the distribution is forced internally to Uniform(0, 1).")
        self.implicits.append(
            partial(_set_innate_immune_variation_type,
                    variation_type=innate_immune_variation_type.value)
        )
    else:
        if not isinstance(distribution, BaseDistribution):
            raise TypeError(
                f"distribution must be a BaseDistribution instance (simple distribution), "
                f"got {type(distribution).__name__}.")
        self._set_distribution(
            distribution=distribution,
            use_case="innate_immune",
            simple_distribution_implicits=[
                partial(_set_innate_immune_variation_type,
                        variation_type=innate_immune_variation_type.value)
            ],
            node_ids=node_ids,
        )

`set_migration_heterogeneity(distribution, node_ids=None)`

Set the migration heterogeneity distribution.

Each individual is assigned a migration rate multiplier drawn from this distribution at creation/birth. Values >1 increase migration frequency relative to the base rate; values <1 reduce it.

Human migration rates must be configured separately via add_migration().

Note: This method is not specific to malaria and would ideally live in emodpy or emod-api so that downstream modules such as emodpy-hiv can reuse it without duplicating the implementation.

Parameters:

Name	Type	Description	Default
`distribution`	`BaseDistribution`	A BaseDistribution defining the simple distribution for per-individual migration rate multipliers. Valid distributions: `ConstantDistribution`, `UniformDistribution`, `GaussianDistribution`, `ExponentialDistribution`, `PoissonDistribution`, `LogNormalDistribution`, `BimodalDistribution`, `WeibullDistribution`. `DualConstantDistribution` and `DualExponentialDistribution` are not supported for demographics and will raise `NotImplementedError`.	required
`node_ids`	`list[int]`	Node id(s) to apply to. `None` targets the default node.	`None`

Raises:

Type	Description
`TypeError`	If distribution is not a BaseDistribution.

Source code in emodpy_malaria/demographics/malaria_demographics.py

def set_migration_heterogeneity(self, distribution: BaseDistribution, node_ids: list[int] = None) -> None:
    """Set the migration heterogeneity distribution.

    Each individual is assigned a migration rate multiplier drawn from this
    distribution at creation/birth. Values >1 increase migration frequency
    relative to the base rate; values <1 reduce it.

    Human migration rates must be configured separately via ``add_migration()``.

    **Note:** This method is not specific to malaria and would ideally live in
    ``emodpy`` or ``emod-api`` so that downstream modules such as
    ``emodpy-hiv`` can reuse it without duplicating the implementation.

    Args:
        distribution (BaseDistribution): A
            [BaseDistribution](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/utils/distributions/)
            defining the simple distribution for per-individual migration rate multipliers.
            Valid distributions: ``ConstantDistribution``, ``UniformDistribution``,
            ``GaussianDistribution``, ``ExponentialDistribution``, ``PoissonDistribution``,
            ``LogNormalDistribution``, ``BimodalDistribution``, ``WeibullDistribution``.
            ``DualConstantDistribution`` and ``DualExponentialDistribution`` are not
            supported for demographics and will raise ``NotImplementedError``.
        node_ids (list[int]): Node id(s) to apply to. ``None`` targets the default node.

    Raises:
        TypeError: If *distribution* is not a BaseDistribution.
    """
    if not isinstance(distribution, BaseDistribution):
        raise TypeError(
            f"distribution must be a BaseDistribution instance (simple distribution), "
            f"got {type(distribution).__name__}.")
    from emod_api.demographics.implicit_functions import (
        _set_migration_model_fixed_rate,
        _set_enable_migration_model_heterogeneity,
    )
    self._set_distribution(
        distribution=distribution,
        use_case="migration_heterogeneity",
        simple_distribution_implicits=[
            _set_migration_model_fixed_rate,
            _set_enable_migration_model_heterogeneity,
        ],
        node_ids=node_ids,
    )

`set_risk_distribution(distribution, node_ids=None)`

Set the risk distribution for demographics-based heterogeneous biting.

Each individual is assigned a risk multiplier drawn from this distribution at initialization/birth, scaling their probability of being bitten relative to others.

Parameters:

Name	Type	Description	Default
`distribution`	`BaseDistribution`	A BaseDistribution defining the simple distribution for individual risk values. Valid distributions: `ConstantDistribution`, `UniformDistribution`, `GaussianDistribution`, `ExponentialDistribution`, `PoissonDistribution`, `LogNormalDistribution`, `BimodalDistribution`, `WeibullDistribution`. `DualConstantDistribution` and `DualExponentialDistribution` are not supported for demographics and will raise `NotImplementedError`.	required
`node_ids`	`list[int]`	Node id(s) to apply to. `None` targets the default node.	`None`

Raises:

Type	Description
`TypeError`	If distribution is not a BaseDistribution.

Source code in emodpy_malaria/demographics/malaria_demographics.py

def set_risk_distribution(self, distribution: BaseDistribution, node_ids: list[int] = None) -> None:
    """Set the risk distribution for demographics-based heterogeneous biting.

    Each individual is assigned a risk multiplier drawn from this
    distribution at initialization/birth, scaling their probability of being
    bitten relative to others.

    Args:
        distribution (BaseDistribution): A
            [BaseDistribution](https://emod.idmod.org/emodpy-malaria/autoapi/emodpy_malaria/utils/distributions/)
            defining the simple distribution for individual risk values.
            Valid distributions: ``ConstantDistribution``, ``UniformDistribution``,
            ``GaussianDistribution``, ``ExponentialDistribution``, ``PoissonDistribution``,
            ``LogNormalDistribution``, ``BimodalDistribution``, ``WeibullDistribution``.
            ``DualConstantDistribution`` and ``DualExponentialDistribution`` are not
            supported for demographics and will raise ``NotImplementedError``.
        node_ids (list[int]): Node id(s) to apply to. ``None`` targets the default node.

    Raises:
        TypeError: If *distribution* is not a BaseDistribution.
    """
    if not isinstance(distribution, BaseDistribution):
        raise TypeError(
            f"distribution must be a BaseDistribution instance (simple distribution), "
            f"got {type(distribution).__name__}.")
    self._set_distribution(
        distribution=distribution,
        use_case="risk",
        simple_distribution_implicits=[_set_enable_demog_risk],
        node_ids=node_ids,
    )

malaria_demographics