sid
¶
Submodules¶
sid._version
sid.colors
sid.config
sid.contacts
sid.countdowns
sid.events
sid.initial_conditions
sid.matching_probabilities
sid.msm
sid.parse_model
sid.pathogenesis
sid.plotting
sid.policies
sid.rapid_tests
sid.seasonality
sid.shared
sid.simulate
sid.statistics
sid.susceptibility
sid.testing
sid.testing_allocation
sid.testing_demand
sid.testing_processing
sid.time
sid.update_states
sid.vaccination
sid.validation
sid.virus_strains
sid.visualize_simulation_results
Package Contents¶
Functions¶
|
Return a list with hex codes representing a color palette. |
|
Create indicator for initially immune people. |
|
Create a |
|
Get the msm function. |
Load epidemiological_parameters. |
|
|
Get a function that simulates the spread of an infectious disease. |
|
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:
Infected individuals are always treated as being immune and reduce the number of additional immune individuals.
If immunity is given as an integer or float, additional immune individuals are sampled randomly.
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)
- 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 settingnumpy.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 byassort_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 apandas.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 apandas.Series
which indicates whether an individuals is infected. If initial infections are apandas.DataFrame
, then, the index is the same asstates
, 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 betweenassort_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 argumentsstates
,params
, and aseed
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 acceptsstates
,params
,receives_rapid_test
,"contacts"
andseed
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 inrapid_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 acceptsstates
,params
,receives_rapid_test
,"contacts"
andseed
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 inrapid_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 acceptsstates
,params
,receives_rapid_test
,"contacts"
andseed
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 inrapid_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 acceptsstates
,params
,"contacts"
andseed
and returns a modified copy of contacts.seasonality_factor_model (Optional[Callable]) – A model which takes in and
params
anddates
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