metacast

Creation:

Author: Martin Grunnill Date: 2024-02-08

Description:

Subpackages

• metacast.event_handling
  • metacast.event_handling.event_queue
  • metacast.event_handling.events
• metacast.sensitivity_analyses
  • metacast.sensitivity_analyses.asses_lh_sample_size
  • metacast.sensitivity_analyses.lhs_and_prcc

Submodules

• metacast.infection_seeding
• metacast.metacaster

Package Contents

Classes

MetaCaster	Class for setting up and simulating multidimensional metapopulation models.
MultinomialSeeder	Makes multinomial draws selecting an infectious hosts branch and then state.

class metacast.MetaCaster(dimensions, subpop_model, states, infected_states=None, infectious_states=None, symptomatic_states=None, observed_states=None, universal_params=None, subpop_params=None, foi_population_focus=None, transmission_term_prefix='beta', subpop_interaction_prefix='rho', population_term_prefix='N', asymptomatic_transmission_modifier=None)

Class for setting up and simulating multidimensional metapopulation models.

Can simulate models on its own if given model_attributes and subpop_model arguments at initialisation. Alternatively these can be defined as attributes of MetaCaster subclass.

Parameters & Attributes

dimensionsint, collection of unique strings, list/tuple of ints, list/tuple of collections of unique strings OR list/tuple of dictionaries (transfer dictionaries)

If int :

This creates a one dimension metapopulation structure with range(scaffold) used to label subpopulations in dimensions attribute.

If list/tuple/set of unique strings:

This creates a one dimension metapopulation structure with entries used to label subpopulations

in dimensions attribute.

If list/tuple of ints:

This creates a multidimensional metapopulation structure with range(each int entry) used to generate

labels on an axis of the subpopulations in dimensions attribute.

If list/tuple of list/tuple/set of unique strings:

This creates a multidimensional metapopulation structure with each sub-list/tuple/set entries used as

labels in am axis of dimensions attribute.

If list/tuple of dictionaries (transfer dictionaries):

Transfer dictionaries outlines the transfer of one subpopulation to another subpopulation. Each transfer dictionary must have the key values pairs:

from_coordinates: string/int or list/tuple of strings/ints

Subpopulation coordinates from which hosts are leaving. All of these entries should be of the same

length.

to_coordinates: string/int or list/tuple of strings/ints

Subpopulation coordinates from which hosts are leaving.All of these entries should be of the same

length and the same length as the from_coordinates entries.

states: list of strings or string

Host states which will transition between subpopulations. Single entry of ‘all’ value means all the available model states transition between subpopulations. Alternatively a list of specific states can be given.

parameterstring

Name given to parameter that is responsible for flow of hosts transferring between subpopulations.

subpop_modelcallable function/class method

Method used to model subpopulation:

Required arguments: ‘y’, ‘y_deltas’, ‘parameters’ and ‘states_index’. Possible additional arguments: ‘coordinates’, ‘subpop_suffix’, ‘foi’ or ‘t’.

stateslist of strings

States used in model.

observed_statesstring or list of strings , optional

Observed states. Useful for obtaining results or fitting (e.g. Cumulative incidence).

infected_stateslist of strings , optional

Infected states (not necessarily infectious).

infectious_statesstring or list of strings , optional if not given value(s) for infected_states used

Infectious states. These states contribute to force of infection. If None no force of infection is caluculated when running model (within ode method).

symptomatic_statesstring or list of strings , optional if not given value(s) for infected_states used

Symptomatic states. NOTE any state in the list self.infectious_states but NOT in this list has its transmission modified by self.asymptomatic_transmission_modifier (see method calculate_fois).

transmission_term_prefixstring, default ‘beta’

Prefix of subpopulation term used in calculating forces of infection, default term is ‘beta’ (see method calculate_fois).

population_term_prefixstring, default ‘N’

Prefix of subpopulation term used as denominator in calculating force of infection (see method calculate_fois).

subpop_interaction_prefixstring default is ‘rho’

Prefix of subpopulation term used to denote level of interaction between subpopulations when calculating force

of infection (see method calculate_fois).

asymptomatic_transmission_modifierstring or None

Factor used to modify transmission from infectious but asymptomatic states. If None a factor of 1 is used in the asymptomatic_transmission_modifier’s place when using method calculating_fois.

universal_paramslist of strings

A list of all the parameters that are NOT: - directly to do with transmission - subpopulation specific (sub_pop_params).

subpop_paramslist of strings, or if axis/dimensions > 1 a dictionary {int: lists of strings}

A list of all the parameters that axis/dimensions specific but NOT directly to do with transmission.

foi_population_focusstring or None (default None)

If None a subpopulations force of infection is not divided by the total population of a subpopulation. If ‘i’ a subpopulations force of infection is divided by the total population of subpopulation ‘i’, i.e. its own population (the population that is being transmitted to). If ‘j’ a subpopulations force of infection for each interacting subpopulation is divided by the total population of subpopulation ‘j’, i.e. the subpopulation it is interacting with (the population that is being transmitted from).

parameter_names

The names of all the parameters.

Type:

list of strings

population_terms

Subpopulation population terms used in calculating force of infection (see method calculate_fois).

Type:

list of strings

transmission_terms

The transmission terms for each subpopulation (see method calculate_fois).

Type:

list of strings

subpop_interaction_terms

The terms for each interaction between subpopulations used when calculating force of infection (see method calculate_fois).

Type:

list of strings

total_subpops

Total number of subpopulations.

Type:

int

total_parameters

Total number of parameters in model.

Type:

int

dimensions

Dimensions of metapopulation.

Type:

list of sets of ints/strings

subpop_transfer_dict

Each entry outlines all the outflows from a subpopulation to other subpopulation. For use with subpop_transfer method.

Type:

dictionary {tuple of ints or strings: list of dictionaries}

subpop_transition_params_dict

Each entry outlines parameters responsible for flows between subpopulations.

Type:

dictionary {string: list of dictionaries}

all_states_index

Keys are all the states values are the associated indexes for use with numpy.arrays.

Type:

dictionary

state_index

First level: keys are the subpopulation coordinates are another dictionary.

Second level: keys are the states and values (ints) are the associated indexes for use with

numpy.arrays.

Type:

dictionary {tuple of strings or ints: {string : int}}

infected_states_indexes

Keys are the subpopulation coordinates values are a list of indexes for infected states.

Type:

dictionary {tuple of strings or ints: [int]}

exposed_states_indexes

Keys are the subpopulation coordinates values are a list of indexes for infected but not infectious states.

Type:

dictionary {tuple of strings or ints: [int]}

infectious_symptomatic_indexes

Keys are the subpopulation coordinates values are a list of indexes for infectious and symptomatic states.

Type:

dictionary {tuple of strings or ints: [int]}

infectious_asymptomatic_indexes

Keys are the subpopulation coordinates values are a list of indexes for infectious and asymptomatic states.

Type:

dictionary {tuple of strings or ints: [int]}

infectious_and_symptomatic_states

A list of infectious and symptomatic states.

Type:

list of stings

infectious_and_asymptomatic_states

A list of infectious and asymptomatic states.

Type:

list of stings

total_states

Total number of states in model.

Type:

int

subpop_coordinates

Coordinates of all subpopulations.

Type:

list [tuples of ints/strings]

subpop_suffixes

Suffixes to appended to parameters specific to subpopulations.

Type:

list of stings

set_structure(self, scaffold, foi_population_focus=None)

Set metapopulation structure using scaffold.

ode(self, y, t, \*parameters):

Evaluate the ODE given states (y), time (t) and parameters

integrate(x0, t, full_output=False, \*\*kwargs_to_pass_to_odeint)

Simulate model via integration using initial values x0 of time range t. A wrapper on top of odeint giving ode method to odeint.

get_state_index_dict_of_coordinate(self, coordinate, axis=0):

Fetch state index dictionaries for given coordinate on an axis.

get_indexes_of_coordinate(self, coordinate, axis=0):

Fetch a list of indices for all states for given coordinate on axis.

Notes

I have tried to use notation find in:

Keeling, M. J., & Rohani, P. (2008). Metapopulations. In Modeling Infectious Diseases in Humans and Animals (pp. 237–240). Princeton University Press.

property dimensions

property foi_population_focus

property subpop_model

property parameters

returns: A dictionary of parameter values. :rtype: Dictionary

property shape

Number of entries in each axis of the metapopulation model.

Return type:

tuple of ints

_dimensions = []

_subpop_model

_foi_population_focus

subpop_transfer(y, y_deltas, t, from_coordinates, parameters)

Calculates the transfers of people from a subpopulation to all other subpopulations.

Parameters:

• y (numpy.array) – Values of variables at time t.

• y_deltas (numpy.Array) – Store of delta (derivative at t) of variables in y which this method adds/subtracts to.

• t (float) – Time t for which derivative is being calculated.

• from_coordinates (tuple or list of strings) – Coordinates for subpopulation being transferred.

• parameters (dictionary {keys are strings: values are numeric}) – Dictionary of parameter values used in calculating derivative.

Returns:

y_deltas – Store of delta (derivative) of variables in y which this method adds/subtracts to.

Return type:

numpy.array

ode(y, t, *parameters)

Evaluate the ODE given states (y), time (t) and parameters

Parameters:

• y (numpy.array) – State variables.

• t (float) – Time.

• parameters (floats) – Parameter values. **NOTE* these values must be given in the same order as the instance attribute parameter_names.

Returns:

y_delta – Deltas of state variables at time point t.

Return type:

numpy.ndarray

calculate_fois(y, parameters, t)

Calculates the Forces of Infection (FOIs) experienced by each subpopulation.

Parameters:

• y (numpy.array) – Values of state variables at current time.

• parameters (dictionary {strings: numeric}) – Dictionary of parameter values used in calculating derivative.

• t (float) – Time.

Returns:

fois – Dictionary of the FOIs experienced at each coordinate.

Return type:

dictionary {tupple of strings or ints: float}

_subpop_infected_interaction(y, coordinates_i, coordinates_j, parameters, asymptomatic_transmission_modifier, t)

get_state_index_dict_of_coordinate(coordinate, axis=0)

Fetch state index dictionaries for given coordinate on an axis.

Parameters:

• coordinate (int or str) – Coordinate of

• axis (int default = 0) – Axis on which coordinate is found.

Returns:

nested dict

Return type:

{tuple of int/str: {str: int}}

get_indexes_of_coordinate(coordinate, axis=0)

Fetch a list of indices for all states for given coordinate on axis.

Parameters:

• coordinate (int or str) – Coordinate of

• axis (int default = 0) – Axis on which coordinate is found.

Return type:

list of ints

static coordinates_to_subpop_suffix(coordinates)

Transform coordinates to subpopulation suffix appended to subpopulation specific parameters.

Parameters:

coordinates (list/tuple of ints or strings) – Coordinate of subpopulation

Return type:

string

_instantaneous_transfer(population_transitioning, population, t=None)

integrate(x0, t, full_output=False, **kwargs_to_pass_to_odeint)

Simulate model via integration using initial values x0 of time range t.

A wrapper on top of odeint, giving ode method to odeint. Modified method from the pygom method DeterministicOde <pygom.model.DeterministicOde>.

Parameters:

• x0 (array like) – Initial values of states.

• t (array like) – Timeframe over which model is to be simulated.

• full_output (bool, optional) – If additional information from the integration is required

• kwargs_to_pass_to_odeint (dictionary) – Key word arguments to pass to scipy.integrate.odeint.

Returns:

solution – Multi-index columns are clusters by vaccine groups by states.

Return type:

pandas.DataFrame

results_array_to_df(results, t)

Converts array of results into a dataframe with multi-index columns reflecting meta-population structure.

Parameters:

• results (np.array) – Results from simulations of model.

• t (np.array) – Time over which model was simulated.

Returns:

results_df – Results with multi-index columns reflecting meta-population structure.

Return type:

pandas.DataFrame

__len__()

Number of axis/dimensions of the metapopulation model.

Return type:

int

class metacast.MultinomialSeeder(branch_info)

Makes multinomial draws selecting an infectious hosts branch and then state.

Parameters:

branch_info (nested dict) –

First level keys are branches (str).

Second level keys are states (str or ints) and values are the names of parameters controlling outflows for those states (str).

branches

Infection branches that a host can be placed upon.

Type:

dict {str: InfectionBranch}

parameters

Parameters (outflows) given in branch_info.

Type:

set of strings

seed_infections(n, branch_probability, parameters)

Draw selection of states to place infected hosts.

set_seed(seed)

Sets random number generator seed.

Parameters:

seed (int (>0)) –

_seed_branches(n, branch_probability)

seed_infections(n, branch_probability, parameters)

Draw selection of states to place infected hosts.

Parameters:

• n (int) – Number of infections to seed.

• branch_probability (dict {string, float}) – Probability of being on each infection branch.

• parameters (dict {str: Number}) – Dictionary of parameter values.

Returns:

infections_draw – Keys are infected states values are number of hosts in state.

Return type:

dict {str: int}