sid

Submodules

Package Contents

Functions

get_colors(palette, number, as_cmap=False, skip_dark=0, skip_bright=0)

Return a list with hex codes representing a color palette.

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_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.

get_msm_func(simulate, calc_moments, empirical_moments, replace_nans, weighting_matrix=None, additional_outputs=None)

Get the msm function.

load_epidemiological_parameters()

Load epidemiological_parameters.

get_simulate_func(params: pandas.DataFrame, initial_states: pandas.DataFrame, contact_models: Dict[str, Any], duration: Optional[Dict[str, Any]] = None, events: Optional[Dict[str, Any]] = None, contact_policies: Optional[Dict[str, Any]] = None, testing_demand_models: Optional[Dict[str, Any]] = None, testing_allocation_models: Optional[Dict[str, Any]] = None, testing_processing_models: Optional[Dict[str, Any]] = None, seed: Optional[int] = None, path: Union[str, pathlib.Path, None] = None, saved_columns: Optional[Dict[str, Union[bool, str, List[str]]]] = None, initial_conditions: Optional[Dict[str, Any]] = None, susceptibility_factor_model: Optional[Callable] = None, virus_strains: Optional[List[str]] = None, vaccination_models: Optional[Callable] = None, rapid_test_models: Optional[Dict[str, Dict[str, Any]]] = None, rapid_test_reaction_models: Optional[Dict[str, Dict[str, Any]]] = None, seasonality_factor_model: Optional[Callable] = None, derived_state_variables: Optional[Dict[str, str]] = None, period_outputs: Optional[Dict[str, Callable]] = None, return_time_series: bool = True, return_last_states: bool = True)

Get a function that simulates the spread of an infectious disease.

get_date(states)

Get date from states.

Attributes

get_colors(palette, number, as_cmap=False, skip_dark=0, skip_bright=0)[source]

Return a list with hex codes representing a color palette.

Parameters
  • palette (str) – One of [“categorical”, “ordered”, “blue”, “red”, “yellow”, “green”, “orange”, “purple”] or combinations of two colors, e.g. “red-green”.

  • number (int) – Number of colors needed. Between 1 and 12 for non combined color scales and between 1 and 24 for combined color scales.

  • as_cmap (bool) – If True, the result is returned as matplotlib cmap.

  • skip_dark (int) – How many colors to skip from the dark side. Only available for monochrome and combined color palettes.

  • skip_bright (int) – How many colors to skip from the bright side. Only available for monochrome and combined color palettes.

Returns

List of hex codes or cmap.

Return type

list or cmap

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

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_infections(infections: Union[int, float], n_people: Optional[int] = None, index: Optional[pandas.Index] = None, seed: Optional[int] = None) pandas.Series[source]

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)

get_msm_func(simulate, calc_moments, empirical_moments, replace_nans, weighting_matrix=None, additional_outputs=None)[source]

Get the msm function.

Parameters
  • simulate (callable) – Function which accepts parameters and returns simulated data.

  • calc_moments (callable or dict) – Function(s) used to calculate simulated moments. If it is a dictionary, it must have the same keys as empirical_moments

  • empirical_moments (pandas.DataFrame or pandas.Series or dict) – One pandas object or a dictionary of pandas objects with empirical moments.

  • replace_nans (callable or list) – Functions(s) specifying how to handle NaNs in simulated_moments. Must match structure of empirical_moments. Exception: If only one replacement function is specified, it will be used on all sets of simulated moments.

  • weighting_matrix (numpy.ndarray) – Square matrix of dimension (NxN) with N denoting the number of empirical_moments. Used to weight squared moment errors.

  • additional_outputs (dict or None) – Dictionary of functions. Each function is evaluated on the output of the simulate function and the result is saved in the output dictionary of the msm function.

Returns

MSM function where all arguments except the parameter

vector are set.

Return type

msm_func (callable)

load_epidemiological_parameters()[source]

Load epidemiological_parameters.

get_simulate_func(params: pandas.DataFrame, initial_states: pandas.DataFrame, contact_models: Dict[str, Any], duration: Optional[Dict[str, Any]] = None, events: Optional[Dict[str, Any]] = None, contact_policies: Optional[Dict[str, Any]] = None, testing_demand_models: Optional[Dict[str, Any]] = None, testing_allocation_models: Optional[Dict[str, Any]] = None, testing_processing_models: Optional[Dict[str, Any]] = None, seed: Optional[int] = None, path: Union[str, pathlib.Path, None] = None, saved_columns: Optional[Dict[str, Union[bool, str, List[str]]]] = None, initial_conditions: Optional[Dict[str, Any]] = None, susceptibility_factor_model: Optional[Callable] = None, virus_strains: Optional[List[str]] = None, vaccination_models: Optional[Callable] = None, rapid_test_models: Optional[Dict[str, Dict[str, Any]]] = None, rapid_test_reaction_models: Optional[Dict[str, Dict[str, Any]]] = None, seasonality_factor_model: Optional[Callable] = None, derived_state_variables: Optional[Dict[str, str]] = None, period_outputs: Optional[Dict[str, Callable]] = None, return_time_series: bool = True, return_last_states: bool = True)[source]

Get a function that simulates the spread of an infectious disease.

The resulting function only depends on parameters. The computational time it takes to process the user input is only incurred once in get_simulate_func() and not when the resulting function is called.

Parameters
  • params (pandas.DataFrame) – params is a DataFrame with a three-level index which contains parameters for various aspects of the model. For example, infection probabilities of contact models, multiplier effects of policies, determinants of the course of the disease. More information can be found in params.

  • initial_states (pandas.DataFrame) – The initial states are a DataFrame which contains individuals and their characteristics. More information can be found in The states DataFrame.

  • contact_models (Dict[str, Any]) – A dictionary of dictionaries where each dictionary describes a channel by which contacts can be formed. More information can be found in Contact Models.

  • duration (Optional[Dict[str, Any]]) – A dictionary which contains keys and values suited to be passed to pandas.date_range(). Only the first three arguments, "start", "end", and "periods", are allowed.

  • events (Optional[Dict[str, Any]]) – Dictionary of events which cause infections.

  • contact_policies (Optional[Dict[str, Any]]) – Dict of dicts with contact. See Policies.

  • testing_demand_models (Optional[Dict[str, Any]]) – Dict of dicts with demand models for tests. See Demand models for more information.

  • testing_allocation_models (Optional[Dict[str, Any]]) – Dict of dicts with allocation models for tests. See Allocation models for more information.

  • testing_processing_models (Optional[Dict[str, Any]]) – Dict of dicts with processing models for tests. See Processing models for more information.

  • seed (Optional[int]) – The seed is used as the starting point for two seed sequences where one is used to set up the simulation function and the other seed sequence is used within the simulation and reset every parameter evaluation. If you pass None as a seed, an internal seed is sampled to set up the simulation function. The seed for the simulation is sampled at the beginning of the simulation function and can be influenced by setting numpy.random.seed right before the call.

  • path (Union[str, pathlib.Path, None]) – Path to the directory where the simulated data is stored.

  • saved_columns (Option[Dict[str, Union[bool, str, List[str]]]]) – Dictionary with categories of state columns. The corresponding values can be True, False or Lists with columns that should be saved. Typically, during estimation you only want to save exactly what you need to calculate moments to make the simulation and calculation of moments faster. The categories are “initial_states”, “disease_states”, “testing_states”, “countdowns”, “contacts”, “countdown_draws”, “group_codes” and “other”.

  • initial_conditions (Optional[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 (int): The number of periods over which infections are distributed and can progress. The default is one 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.

  • susceptibility_factor_model (Optional[Callable]) – A function which takes the states and parameters and returns an infection probability multiplier for each individual.

  • virus_strains (Optional[List[str]]) – A list of names indicating the different virus strains used in the model. Their different contagiousness factors are looked up in the params DataFrame. By default, only one virus strain is used.

  • 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.

  • (Optional[Dict[str (rapid_test_models) – A dictionary of dictionaries containing models for rapid tests. Each model for rapid tests can have a "start" and "end" date. It must have a function under "model" which accepts states, params, receives_rapid_test, "contacts" and seed and returns a boolean series indicating individuals who received a rapid test. The difference to other test models is that rapid tests are performed after planned contacts are calculated (i.e. contact models and policies are evaluated) but before they actually take place. This allows people to use more rapid tests on days with many planned contacts and to react to the test outcome in rapid_test_reaction_models.

  • Dict[str – A dictionary of dictionaries containing models for rapid tests. Each model for rapid tests can have a "start" and "end" date. It must have a function under "model" which accepts states, params, receives_rapid_test, "contacts" and seed and returns a boolean series indicating individuals who received a rapid test. The difference to other test models is that rapid tests are performed after planned contacts are calculated (i.e. contact models and policies are evaluated) but before they actually take place. This allows people to use more rapid tests on days with many planned contacts and to react to the test outcome in rapid_test_reaction_models.

  • Any]]] – A dictionary of dictionaries containing models for rapid tests. Each model for rapid tests can have a "start" and "end" date. It must have a function under "model" which accepts states, params, receives_rapid_test, "contacts" and seed and returns a boolean series indicating individuals who received a rapid test. The difference to other test models is that rapid tests are performed after planned contacts are calculated (i.e. contact models and policies are evaluated) but before they actually take place. This allows people to use more rapid tests on days with many planned contacts and to react to the test outcome in rapid_test_reaction_models.

  • rapid_test_reaction_models (Optional[Dict[str, Dict[str, Any]]]) – A dictionary holding rapid tests reaction models which allow to change calculated contacts based on the results of rapid tests. Each model can have a "start" and "end" date. It must have a function under "model" which accepts states, params, "contacts" and seed and returns a modified copy of contacts.

  • seasonality_factor_model (Optional[Callable]) – A model which takes in and params and dates signaling the whole duration of the simulation and returns a DataFrame with a factor for each day and contact model which scales the corresponding infection probability. If seasonality patterns are the same for all contact models, the model can return a Series instead of a DataFrame.

  • derived_state_variables (Optional[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.

  • period_outputs (Optional[Dict[str, Callable]]) – A dictionary of functions that are called with the states DataFrame at the end of each period. Their results are stored in a dictionary of lists inside the results dictionary of the simulate function.

  • return_time_series (Optional[bool])) – Whether the full time searies is stored on disk and returned as dask.DataFrame in the results dictionary of the simulate function.

  • return_last_states (Optional[bool])) – Whether the full states DataFrame of the last period are returned in the results dictionary of the simulate function.

Returns

Simulates dataset based on parameters.

Return type

Callable

get_date(states)[source]

Get date from states.

sid_period_to_timestamp[source]
timestamp_to_sid_period[source]
__version__ = unknown[source]