DemographicsTemplates

DemographicsTemplatesConstants

Mortality_Rates_Mod30_5yrs_Xval: Mod 30 values closest to the 5 yr age boundaries based on when EMOD actually updates individual mortality rates. The distribution is constant for about 5 years (e.g. values at 0.6 days and 1829.5 days) and linearly interpolated between the 5 yr boundaries.

Source code in emod_api/demographics/DemographicsTemplates.py

class DemographicsTemplatesConstants:
    """Mortality_Rates_Mod30_5yrs_Xval: Mod 30 values closest to the 5 yr age boundaries based on when EMOD actually updates individual mortality rates.
                                        The distribution is constant for about 5 years (e.g. values at 0.6 days and 1829.5 days) and linearly interpolated between the 5 yr boundaries. """
    Mortality_Rates_Mod30_5yrs_Xval = [0.6, 1829.5, 1829.6, 3659.5, 3659.6, 5489.5,
                                       5489.6, 7289.5, 7289.6, 9119.5, 9119.6, 10949.5,
                                       10949.6, 12779.5, 12779.6, 14609.5, 14609.6, 16439.5,
                                       16439.6, 18239.5, 18239.6, 20069.5, 20069.6, 21899.5,
                                       21899.6, 23729.5, 23729.6, 25559.5, 25559.6, 27389.5,
                                       27389.6, 29189.5, 29189.6, 31019.5, 31019.6, 32849.5,
                                       32849.6, 34679.5, 34679.6, 36509.5, 36509.6, 38339.5]

FullRisk(demog, description='')

FullRisk puts everyone at 100% risk.

Source code in emod_api/demographics/DemographicsTemplates.py

def FullRisk(demog, description=""):
    """
    FullRisk puts everyone at 100% risk.
    """
    if not description:
        description = "Setting full risk using default values"

    setting = {"RiskDist_Description": "Full risk",
               "RiskDistributionFlag": 0, # 0 = CONSTANT
               "RiskDistribution1": 1,
               "RiskDistribution2": 0,
               "RiskDistribution_Description": description}
    demog.SetDefaultFromTemplate(setting, _set_enable_demog_risk)

InitRiskExponential(demog, mean=1.0)

InitRiskExponential puts everyone at somewhere between 0% risk and 100% risk, drawn from Exponential.

Parameters:

Name	Type	Description	Default
mean	float	Mean of exponential distribution.	1.0

Returns:

Raises:

Source code in emod_api/demographics/DemographicsTemplates.py

def InitRiskExponential(demog,
                        mean: float = 1.0):
    """
    InitRiskExponential puts everyone at somewhere between 0% risk and 100% risk, drawn from Exponential.

    Args:
        mean: Mean of exponential distribution.

    Returns:

    Raises:

    """
    setting = {"RiskDist_Description": "Exponentially distributed risk",
               "RiskDistributionFlag": 3, # exponential
               "RiskDistribution1": mean,
               "RiskDistribution2": 0}
    demog.SetDefaultFromTemplate(setting, _set_enable_demog_risk)

InitRiskLogNormal(demog, mean=0.0, sigma=1.0)

InitRiskLogNormal puts everyone at somewhere between 0% risk and 100% risk, drawn from LogNormal.

Parameters:

Name	Type	Description	Default
mean	float	Mean of lognormal distribution.	0.0
sigma	float	Sigma of lognormal distribution.	1.0

Returns:

Raises:

Source code in emod_api/demographics/DemographicsTemplates.py

def InitRiskLogNormal(demog, mean=0.0, sigma=1.0):
    """
    InitRiskLogNormal puts everyone at somewhere between 0% risk and 100% risk, drawn from LogNormal.

    Args:
        mean (float): Mean of lognormal distribution.
        sigma (float): Sigma of lognormal distribution.

    Returns:

    Raises:

    """
    setting = {"RiskDist_Description": "LogNormal distributed risk",
               "RiskDistributionFlag": 5, # lognormal
               "RiskDistribution1": mean,
               "RiskDistribution2": sigma}
    demog.SetDefaultFromTemplate(setting, _set_enable_demog_risk)

InitRiskUniform(demog, min_lim=0, max_lim=1, description='')

InitRiskUniform puts everyone at somewhere between 0% risk and 100% risk, drawn uniformly.

Parameters:

Name	Type	Description	Default
min_lim	float	Low end of uniform distribution. Must be >=0, <1.	0
max_lim	float	High end of uniform distribution. Must be >=min, <=1.	1
description	str	Why were these values chosen?	''

Returns:

Raises:

Source code in emod_api/demographics/DemographicsTemplates.py

def InitRiskUniform(demog,
                    min_lim: float = 0,
                    max_lim: float = 1,
                    description: str = ""):
    """
    InitRiskUniform puts everyone at somewhere between 0% risk and 100% risk, drawn uniformly.

    Args:
        min_lim: Low end of uniform distribution. Must be >=0, <1.
        max_lim: High end of uniform distribution. Must be >=min, <=1.
        description: Why were these values chosen?

    Returns:

    Raises:

    """
    if not description:
        description = f"Risk is drawn from a uniform distribution, min_lim={min_lim} and max_lim={max_lim}"

    if min_lim < 0:
        raise ValueError(f"min_lim value of {min_lim} is less than 0. Not valid.")
    setting = {"RiskDist_Description": "Uniformly distributed risk",
               "RiskDistributionFlag": 1,
               "RiskDistribution1": min_lim,
               "RiskDistribution2": max_lim,
               "RiskDistribution_Description": description}
    demog.SetDefaultFromTemplate(setting, _set_enable_demog_risk)

MortalityRateByAge(demog, age_bins, mort_rates)

Set (non-disease) mortality rates by age bins. No checks are done on input arrays.

Parameters:

Name	Type	Description	Default
age_bins	list[float]	list of age bins, with ages in years.	required
mort_rates	list[float]	list of mortality rates, where mortality rate is daily probability of dying..	required

Returns:

Source code in emod_api/demographics/DemographicsTemplates.py

def MortalityRateByAge(demog,
                       age_bins: list[float],
                       mort_rates: list[float]):
    """
        Set (non-disease) mortality rates by age bins. No checks are done on input arrays.

        Args:
            age_bins: list of age bins, with ages in years.
            mort_rates: list of mortality rates, where mortality rate is daily probability of dying..

        Returns:

    """
    # Note that the first input axis is sex (or gender). There are two values, but the rates are applied
    # equally for both here. The second input axis is age bin, and that is much more configurable.
    mort_dist = {"MortalityDistribution": {"AxisNames": ["gender", "age"],
                                           "AxisUnits": ["male=0,female=1", "years"],
                                           "AxisScaleFactors": [1, 365],
                                           "PopulationGroups": [[0, 1], age_bins],
                                           "ResultScaleFactor": 1,
                                           "ResultUnits": "daily probability of dying",
                                           "ResultValues": [mort_rates, mort_rates]}}
    demog.SetDefaultFromTemplate(mort_dist, _set_mortality_age_gender)

NoInitialPrevalence(demog)

NoInitialPrevalence disables initial prevalence; outbreak seeding must be done from an Outbreak intervention (or serialized population).

Parameters:

Name	Type	Description	Default
demog	Demographics	Demographics object	required

Returns:

Raises:

Source code in emod_api/demographics/DemographicsTemplates.py

def NoInitialPrevalence(demog):
    """
    NoInitialPrevalence disables initial prevalence; outbreak seeding must be done from an Outbreak intervention (or serialized population).

    Args:
        demog (Demographics): Demographics object

    Returns:

    Raises:

    """

    setting = {"PrevalenceDist_Description": "No initial prevalence",
               "InitialPrevalence": 0}
    # why not just disable it at config?
    demog.SetDefaultFromTemplate(setting)

NoRisk()

NoRisk puts everyone at 0 risk.

Source code in emod_api/demographics/DemographicsTemplates.py

def NoRisk():
    """
    NoRisk puts everyone at 0 risk.
    """
    return {"RiskDist_Description": "No risk",
            "RiskDistributionFlag": 0, # 0 = CONSTANT
            "RiskDistribution1": 0,
            "RiskDistribution2": 0}

SimpleSusceptibilityDistribution(demog, meanAgeAtInfection=2.5)

Rough initialization to reduce burn-in and prevent huge outbreaks at sim start For ages 0 through 99 the susceptibility distribution is set to an exponential distribution with an average age at infection. The minimum susceptibility is 2.5% at old ages.

Parameters:

Name	Type	Description	Default
demog	Demographics	Demographics object	required
meanAgeAtInfection	float	Rough average age at infection in years.	2.5

Note: Requires that config.parameters.Susceptibility_Initialization_Distribution_Type=DISTRIBUTION_COMPLEX

Source code in emod_api/demographics/DemographicsTemplates.py

def SimpleSusceptibilityDistribution(demog,
                                     meanAgeAtInfection: float = 2.5):
    """
    Rough initialization to reduce burn-in and prevent huge outbreaks at sim start
    For ages 0 through 99 the susceptibility distribution is set to an exponential distribution with an average age at infection.
    The minimum susceptibility is 2.5% at old ages.

    Args:
        demog (Demographics): Demographics object
        meanAgeAtInfection: Rough average age at infection in years.

    Note:
    Requires that ``config.parameters.Susceptibility_Initialization_Distribution_Type=DISTRIBUTION_COMPLEX``

    """
    # set config.Susceptibility_Initialization_Distribution_Type=COMPLEX
    # This function is first to be switched over to be reversed.
    # Calling code in emodpy will call this and pass the demographics instance then we
    # call SetDefaultFromTemplate on the demog object so we can also pass the setter function
    res_vals = [1.0, 1.0] + [0.025 + 0.975 * math.exp(-(i - 1) / (meanAgeAtInfection / math.log(2))) for i in range(2, 100, 1)]
    desc = "Rough initialization to reduce burn-in and prevent huge outbreaks at sim start. "
    desc += f"Exponential distribution, Average age at infection ~{meanAgeAtInfection} years, minimum susceptibility is 2.5% at old ages"
    suscDist = {"SusceptibilityDist_Description": desc,
                "SusceptibilityDistribution": {"DistributionValues": [i * 365 for i in range(100)],
                                               "ResultScaleFactor": 1,
                                               "ResultValues": res_vals}}
    demog.SetDefaultFromTemplate(suscDist, _set_suscept_complex)

get_fert_dist_from_rates(rates)

Create dictionary with DTK-compatible distributions from input vectors of fertility (crude) rates.

Parameters:

Name	Type	Description	Default
rates	list[float]	Array/vector of crude rates for whole population, for a range of years.	required

Source code in emod_api/demographics/DemographicsTemplates.py

def get_fert_dist_from_rates(rates: list[float]):
    """
    Create dictionary with DTK-compatible distributions from input vectors of fertility (crude) rates.

    Args:
        rates: Array/vector of crude rates for whole population, for a range of years.

    """
    fert_dist = {"FertilityDistribution": {"AxisNames": ["age", "year"],
                                           "AxisUnits": ["years", "simulation_year"],
                                           "AxisScaleFactors": [365, 1],
                                           "PopulationGroups": [[0, 125],
                                                                [x for x in range(len(rates))]],
                                           "ResultScaleFactor": 2.73972602739726e-03,
                                           "ResultUnits": "annual births per 1000 individuals",
                                           "ResultValues": [rates, rates]}}
    return FertilityDistribution().from_dict(fertility_distribution=fert_dist["FertilityDistribution"])