sid.initial_conditions

This module contains everything related to initial conditions.

The initial conditions govern the distribution of infections and immunity in the beginning of a simulation and can used to create patterns which match the real data.

Module Contents

Functions

sample_initial_infections(infections: Union[int, float], n_people: Optional[int] = None, index: Optional[pandas.Index] = None, seed: Optional[int] = None) → pandas.Series	Create a pandas.Series indicating infected individuals.
sample_initial_immunity(immunity: Union[int, float, pandas.Series, None], infected_or_immune: pandas.Series, seed: Optional[int]) → pandas.Series	Create indicator for initially immune people.
sample_initial_distribution_of_infections_and_immunity(states: pandas.DataFrame, params: pandas.DataFrame, initial_conditions: Dict[str, Any], testing_demand_models: Dict[str, Dict[str, Any]], testing_allocation_models: Dict[str, Dict[str, Any]], testing_processing_models: Dict[str, Dict[str, Any]], virus_strains: Dict[str, Any], vaccination_models: Optional[Callable], seed: itertools.count, derived_state_variables: Dict[str, str])	Sample the initial distribution of infections and immunity.
_scale_up_initial_infections(initial_infections, states, assort_by, known_cases_multiplier, seed)	Increase number of infections by a multiplier taken from params.
_scale_up_initial_infections_numba(initial_infections, probabilities, seed)	Scale up initial infections.
_spread_out_initial_infections(scaled_infections: pandas.Series, burn_in_periods: List[pandas.Timestamp], growth_rate: float, seed: int) → pandas.DataFrame	Spread out initial infections over several periods, given a growth rate.
_sample_factorized_virus_strains_for_infections(spread_out_infections: pandas.DataFrame, virus_shares: Dict[str, Any], seed: int) → pandas.DataFrame	Convert boolean infections to factorized virus strains.
_integrate_immune_individuals(states: pandas.DataFrame, params: pandas.DataFrame, initial_immunity: pandas.Series, n_burn_in_periods: int, seed: int) → pandas.DataFrame	Integrate immunity level of individuals in states.

sample_initial_infections(infections: Union[int, float], n_people: Optional[int] = None, index: Optional[pandas.Index] = None, seed: Optional[int] = None) → pandas.Series

Create a pandas.Series indicating infected individuals.

Parameters

• infections (Union[int, float]) – The infections can be either a pandas.Series where each individual has an indicator for the infection status, an integer representing the number of infected people or a float representing the share of infected individuals.

• n_people (Optional[int]) – The number of individuals.

• index (Optional[pandas.Index]) – The index for the infections.

• seed (Optional[int]) – A seed.

Returns

A series indicating infected individuals.

Return type

infections (pandas.Series)

sample_initial_immunity(immunity: Union[int, float, pandas.Series, None], infected_or_immune: pandas.Series, seed: Optional[int]) → pandas.Series

Create indicator for initially immune people.

There are some special cases to handle:

1. Infected individuals are always treated as being immune and reduce the number of additional immune individuals.

2. If immunity is given as an integer or float, additional immune individuals are sampled randomly.

3. If immunity is given as a series, immune and infected individuals form the total immune population.

Parameters

• immunity (Union[int, float, pandas.Series]) – The people who are immune in the beginning can be specified as an integer for the number, a float between 0 and 1 for the share, and a pandas.Series with the same index as states. Note that, infected individuals are immune and included.

• infected_or_immune (pandas.Series) – A series which indicates immunity level from from individuals in state.

• seed (optional[int]) – A seed.

Returns

Indicates immune individuals.

Return type

initial_immunity (pandas.Series)

sample_initial_distribution_of_infections_and_immunity(states: pandas.DataFrame, params: pandas.DataFrame, initial_conditions: Dict[str, Any], testing_demand_models: Dict[str, Dict[str, Any]], testing_allocation_models: Dict[str, Dict[str, Any]], testing_processing_models: Dict[str, Dict[str, Any]], virus_strains: Dict[str, Any], vaccination_models: Optional[Callable], seed: itertools.count, derived_state_variables: Dict[str, str])

Sample the initial distribution of infections and immunity.

This functions allows to

• set the number of initial infections.

• increase the number of infections by some factor to reduce underreporting, for example, due to asymptomatic cases. You can also keep shares between subgroups constant.

• let infections evolve over some periods to have courses of diseases in every stage.

• assume pre-existing immunity in the population.

Parameters

• states (pandas.DataFrame) – The states.

• params (pandas.DataFrame) – The parameters.

• initial_conditions (Dict[str, Any]) –

  The initial conditions allow you to govern the distribution of infections and immunity and the heterogeneity of courses of disease at the start of the simulation. Use None to assume no heterogeneous courses of diseases and 1% infections. Otherwise, initial_conditions is a dictionary containing the following entries:

  • assort_by (Optional[Union[str, List[str]]]): The relative infections is preserved between the groups formed by assort_by variables. By default, no group is formed and infections spread across the whole population.

  • burn_in_periods (List[pd.Timestamp]): List of dates that make up the burn-in period.

  • growth_rate (float): The growth rate specifies the increase of infections from one burn-in period to the next. For example, two indicates doubling case numbers every period. The value must be greater than or equal to one. Default is one which is no distribution over time.

  • initial_immunity (Union[int, float, pandas.Series]): The n_people who are immune in the beginning can be specified as an integer for the number, a float between 0 and 1 for the share, and a pandas.Series with the same index as states. Note that infected individuals are also immune. For a 10% pre-existing immunity with 2% currently infected people, set the key to 0.12. By default, only infected individuals indicated by the initial infections are immune.

  • initial_infections (Union[int, float, pandas.Series, pandas.DataFrame]): The initial infections can be given as an integer which is the number of randomly infected individuals, as a float for the share or as a pandas.Series which indicates whether an individuals is infected. If initial infections are a pandas.DataFrame, then, the index is the same as states, columns are dates or periods which can be sorted, and values are infected individuals on that date. This step will skip upscaling and distributing infections over days and directly jump to the evolution of states. By default, 1% of individuals is infected.

  • known_cases_multiplier (int): The factor can be used to scale up the initial infections while keeping shares between assort_by variables constant. This is helpful if official numbers are underreporting the number of cases.

  • virus_shares (Union[dict, pandas.Series]): A mapping between the names of the virus strains and their share among newly infected individuals in each burn-in period.

• virus_strains (Dict[str, Any]) – A dictionary with the keys "names" and "factors" holding the different contagiousness factors of multiple viruses.

• vaccination_models (Optional[Dict[str, Dict[str, Any]) – A dictionary of models which allow to vaccinate individuals. The "model" key holds a function with arguments states, params, and a seed which returns boolean indicators for individuals who received a vaccination.

• seed (itertools.count) – The seed counter.

• derived_state_variables (Dict[str, str]) – A dictionary that maps names of state variables to pandas evaluation strings that generate derived state variables, i.e. state variables that can be calculated from the existing state variables.

Returns

The states with sampled infections and immunity.

Return type

states (pandas.DataFrame)

_scale_up_initial_infections(initial_infections, states, assort_by, known_cases_multiplier, seed)

Increase number of infections by a multiplier taken from params.

If no assort_by variables are provided, infections are simply scaled up in the whole population without regarding any inter-group differences.

If assort_by variables are passed to the function, the probability for each individual to become infectious depends on the share of infected people in their group, \(\mu\) and the growth factor, \(r\).

\[p_i = \frac{\mu * (r - 1)}{1 - \mu}\]

The formula ensures that relative number of cases between groups defined by the variables in assort_by is preserved.

Parameters

• initial_infections (pandas.Series) – Boolean array indicating initial infections.

• states (pandas.DataFrame) – The states DataFrame.

• assort_by (Optional[List[str]]) – A list of assort_by variables if infections should be proportional between groups or None if no groups are used.

• known_cases_multiplier (float) – The multiplier which can be used to scale infections from observed infections to the real number of infections.

• seed (int) – The seed.

Returns

A boolean series with upscaled infections.

Return type

scaled_up (pandas.Series)

_scale_up_initial_infections_numba(initial_infections, probabilities, seed)

Scale up initial infections.

Parameters

• initial_infections (numpy.ndarray) – Boolean array indicating initial infections.

• probabilities (numpy.ndarray) – Probabilities for becoming infected.

• seed (int) – Seed to control randomness.

Returns

Upscaled infections.

Return type

scaled_infections (numpy.ndarray)

_spread_out_initial_infections(scaled_infections: pandas.Series, burn_in_periods: List[pandas.Timestamp], growth_rate: float, seed: int) → pandas.DataFrame

Spread out initial infections over several periods, given a growth rate.

Parameters

• scaled_infections (pandas.Series) – The scaled infections.

• burn_in_periods (List[pd.Timestamp]) – List of dates that make up the burn-in period.

• growth_rate (float) – The growth rate of infections from one burn-in period to the next.

• seed (int) – Seed to control randomness.

Returns

A list of boolean arrays which indicate

new infections for each day of the burn-in period.

Return type

spread_infections (pandas.DataFrame)

_sample_factorized_virus_strains_for_infections(spread_out_infections: pandas.DataFrame, virus_shares: Dict[str, Any], seed: int) → pandas.DataFrame

Convert boolean infections to factorized virus strains.

_integrate_immune_individuals(states: pandas.DataFrame, params: pandas.DataFrame, initial_immunity: pandas.Series, n_burn_in_periods: int, seed: int) → pandas.DataFrame

Integrate immunity level of individuals in states.

Parameters

• states (pandas.DataFrame) – The states which already include sampled infections.

• params (pandas.DataFrame) – The parameters.

• initial_immunity (pandas.Series) – A series with sampled immunity levels of individuals.

• n_burn_in_periods (int) – The number of periods over which infections are distributed and can progress.

• seed (int) – Seed to control randomness.

Returns

The states with initial immunity integrated.

Return type

states (pandas.DataFrame)