emodpy_hiv.utils.distributions module#

class emodpy_hiv.utils.distributions.BaseDistribution#

Bases: ABC

Abstract base class for distribution classes. This class should not be instantiated directly.

abstract get_demographic_distribution_parameters() → dict[source]#

Yield the flag and relevant values necessary for setting a demographics distribution of the class type

Returns:: {‘flag’: X, ‘value1’: Y, ‘value2’: Z}
Return type:: a dict of the form

abstract set_intervention_distribution(intervention_object: ReadOnlyDict, prefix: str)[source]#

Set the distribution parameters to the intervention object.

Parameters:

intervention_object (s2c.ReadOnlyDict) –
- The object to set.
prefix (str) –
- The prefix of the parameters.

class emodpy_hiv.utils.distributions.ConstantDistribution(value: float)#

Bases: 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.

Parameters:

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

get_demographic_distribution_parameters() → dict[source]#

Yield the flag and relevant values necessary for setting a demographics constant distribution

Returns:: {‘flag’: X, ‘value1’: Y, ‘value2’: Z}
Return type:: a dict of the form

set_intervention_distribution(intervention_object: ReadOnlyDict, prefix: str)[source]#

Set the distribution parameters to the object.

Parameters:

intervention_object (s2c.ReadOnlyDict) –
- The object to set.
prefix (str) –
- The prefix of the parameters.

class emodpy_hiv.utils.distributions.ExponentialDistribution(mean: float)#

Bases: 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.

Parameters:

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

get_demographic_distribution_parameters() → dict[source]#

Yield the flag and relevant values necessary for setting a demographics exponential distribution

Returns:: {‘flag’: X, ‘value1’: Y, ‘value2’: Z}
Return type:: a dict of the form

set_intervention_distribution(intervention_object: ReadOnlyDict, prefix: str)[source]#

Set the distribution parameters to the object.

Parameters:

intervention_object (s2c.ReadOnlyDict) –
- The object to set.
prefix (str) –
- The prefix of the parameters.

class emodpy_hiv.utils.distributions.UniformDistribution(uniform_min: float, uniform_max: float)#

Bases: BaseDistribution

This class represents a uniform distribution, which is a type of statistical distribution where all outcomes are equally likely within a specified range. A uniform distribution is defined by two parameters: the minimum and maximum values that define the range of outcomes.

Parameters:

uniform_min (float) –
- The minimum value of the range for this distribution.
- The value should not be negative.
uniform_max (float) –
- The maximum value of the range for this distribution.
- The value should not be negative.

Raises:

ValueError – If ‘uniform_min’ or ‘uniform_max’ arguments are negative.

Example

>>> # Create  a UniformDistribution object.
>>> ud = UniformDistribution(0, 10)
>>> # The uniform_min and uniform_max attributes can be accessed and updated.
>>> ud.uniform_min
0
>>> ud.uniform_max
10
>>> ud.uniform_min = 5
>>> ud.uniform_min
5

get_demographic_distribution_parameters() → dict[source]#

Yield the flag and relevant values necessary for setting a demographics uniform distribution

Returns:: {‘flag’: X, ‘value1’: Y, ‘value2’: Z}
Return type:: a dict of the form

set_intervention_distribution(intervention_object: ReadOnlyDict, prefix: str)[source]#

Set the distribution parameters to the object.

Parameters:

intervention_object (s2c.ReadOnlyDict) –
- The object to set.
prefix (str) –
- The prefix of the parameters.

class emodpy_hiv.utils.distributions.GaussianDistribution(mean: float, std_dev: float)#

Bases: BaseDistribution

This class represents a Gaussian distribution, a type of statistical distribution where the values are distributed symmetrically around the mean. A Gaussian distribution is defined by two parameters: the mean and the standard deviation.

Parameters:

mean (float) –
- The mean of the Gaussian distribution.
- This value should not be negative.
std_dev (float) –
- The standard deviation of the Gaussian distribution.
- This value should be positive.

Raises:

ValueError – If ‘mean’ argument is negative or ‘std_dev’ argument is not positive.

Example

>>> # Create a GaussianDistribution object.
>>> gd = GaussianDistribution(0, 1)
>>> # The mean and std_dev attributes can be accessed and updated.
>>> gd.mean
0
>>> gd.std_dev
1
>>> gd.mean = 5
>>> gd.mean
5

get_demographic_distribution_parameters() → dict[source]#

Yield the flag and relevant values necessary for setting a demographics gaussian distribution

Returns:: {‘flag’: X, ‘value1’: Y, ‘value2’: Z}
Return type:: a dict of the form

set_intervention_distribution(intervention_object: ReadOnlyDict, prefix: str)[source]#

Set the distribution parameters to the object.

Parameters:

intervention_object (s2c.ReadOnlyDict) –
- The object to set.
prefix (str) –
- The prefix of the parameters.

class emodpy_hiv.utils.distributions.PoissonDistribution(mean: float)#

Bases: BaseDistribution

This class represents a Poisson distribution, a type of statistical distribution where the probability of a given number of events occurring in a fixed interval of time or space is proportional to the mean number of events.

Parameters:

mean (float) –

The mean of the Poisson distribution.
This value should not be negative.

Raises:

ValueError – If ‘mean’ argument is negative.

Example

>>> # Create a PoissonDistribution object.
>>> pd = PoissonDistribution(1)
>>> # The mean attribute can be accessed and updated.
>>> pd.mean
1
>>> pd.mean = 2
>>> pd.mean
2

get_demographic_distribution_parameters() → dict[source]#

Yield the flag and relevant values necessary for setting a demographics poisson distribution

Returns:: {‘flag’: X, ‘value1’: Y, ‘value2’: Z}
Return type:: a dict of the form

set_intervention_distribution(intervention_object: ReadOnlyDict, prefix: str)[source]#

Set the distribution parameters to the object.

Parameters:

intervention_object (s2c.ReadOnlyDict) –
- The object to set.
prefix (str) –
- The prefix of the parameters.

class emodpy_hiv.utils.distributions.LogNormalDistribution(mean: float, std_dev: float)#

Bases: BaseDistribution

This class represents a log-normal distribution, a type of statistical distribution where the logarithm of the values is normally distributed. A log-normal distribution is defined by two parameters: the mean and the standard deviation.

Parameters:

mean (float) –
- The mean/mu of the log-normal distribution.
std_dev (float) –
- The standard deviation/sigma/width of the log-normal distribution.

Example

>>> # Create a LogNormalDistribution object.
>>> lnd = LogNormalDistribution(0, 1)
>>> # The mean and std_dev attributes can be accessed and updated.
>>> lnd.mean
0
>>> lnd.std_dev
1
>>> lnd.mean = 5
>>> lnd.mean
5

get_demographic_distribution_parameters() → dict[source]#

Yield the flag and relevant values necessary for setting a demographics log normal distribution

Returns:: {‘flag’: X, ‘value1’: Y, ‘value2’: Z}
Return type:: a dict of the form

set_intervention_distribution(intervention_object: ReadOnlyDict, prefix: str)[source]#

Set the distribution parameters to the object.

Parameters:

intervention_object (s2c.ReadOnlyDict) –
- The object to set.
prefix (str) –
- The prefix of the parameters.

class emodpy_hiv.utils.distributions.WeibullDistribution(weibull_kappa: float, weibull_lambda: float)#

Bases: BaseDistribution

This class represents a Weibull distribution, a type of statistical distribution where the probability density function is defined by two parameters: the shape parameter (kappa) and the scale parameter (lambda).

Parameters:

weibull_kappa (float) –
- The shape parameter of the Weibull distribution.
- This value should be positive.
weibull_lambda (float) –
- The scale parameter of the Weibull distribution.
- This value should be positive.

Raises:

ValueError – If ‘weibull_kappa’ or ‘weibull_lambda’ arguments are not positive.

Example

>>> # Create a WeibullDistribution object.
>>> wd = WeibullDistribution(1, 2)
>>> # The weibull_kappa and weibull_lambda attributes can be accessed and updated.
>>> wd.weibull_kappa
1
>>> wd.weibull_lambda
2
>>> wd.weibull_kappa = 3
>>> wd.weibull_kappa
3

get_demographic_distribution_parameters() → dict[source]#

Yield the flag and relevant values necessary for setting a demographics weibull distribution

Returns:: {‘flag’: X, ‘value1’: Y, ‘value2’: Z}
Return type:: a dict of the form

set_intervention_distribution(intervention_object: ReadOnlyDict, prefix: str)[source]#

Set the distribution parameters to the object.

Parameters:

intervention_object (s2c.ReadOnlyDict) –
- The object to set.
prefix (str) –
- The prefix of the parameters.

class emodpy_hiv.utils.distributions.DualConstantDistribution(proportion: float, constant: float)#

Bases: 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.

Parameters:

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

get_demographic_distribution_parameters() → dict[source]#: This function is not supported in the demographic object. Raise NotImplementedError if called.

set_intervention_distribution(intervention_object: ReadOnlyDict, prefix: str)[source]#

Set the distribution parameters to the object.

Parameters:

intervention_object (s2c.ReadOnlyDict) –
- The object to set.
prefix (str) –
- The prefix of the parameters.

class emodpy_hiv.utils.distributions.DualExponentialDistribution(proportion: float, mean_1: float, mean_2: float)#

Bases: 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.

Parameters:

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

get_demographic_distribution_parameters() → None[source]#: This function is not supported in the demographic object. Raise NotImplementedError if called.

set_intervention_distribution(intervention_object: ReadOnlyDict, prefix: str)[source]#

Set the distribution parameters to the object.

Parameters:

intervention_object (s2c.ReadOnlyDict) –
- The object to set.
prefix (str) –
- The prefix of the parameters.

class emodpy_hiv.utils.distributions.BimodalDistribution(proportion: float, constant: float)#

Bases: 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.

Parameters:

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

get_demographic_distribution_parameters() → dict[source]#

Yield the flag and relevant values necessary for setting a demographics bimodal distribution

Returns:: {‘flag’: X, ‘value1’: Y, ‘value2’: Z}
Return type:: a dict of the form

set_intervention_distribution(intervention_object: ReadOnlyDict, prefix: str)[source]#: This function is not supported in the intervention object. Raise NotImplementedError if called.