:py:mod:`metacast` ================== .. py:module:: metacast .. autoapi-nested-parse:: Creation: Author: Martin Grunnill Date: 2024-02-08 Description: Subpackages ----------- .. toctree:: :titlesonly: :maxdepth: 3 event_handling/index.rst sensitivity_analyses/index.rst Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 infection_seeding/index.rst metacaster/index.rst Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: metacast.MetaCaster metacast.MultinomialSeeder .. py:class:: 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 ----------------------- dimensions : int, 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. parameter : string Name given to parameter that is responsible for flow of hosts transferring between subpopulations. subpop_model : callable 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'. states : list of strings States used in model. observed_states : string or list of strings , optional Observed states. Useful for obtaining results or fitting (e.g. Cumulative incidence). infected_states : list of strings , optional Infected states (not necessarily infectious). infectious_states : string 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_states : string 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_prefix : string, default 'beta' Prefix of subpopulation term used in calculating forces of infection, default term is 'beta' (see method calculate_fois). population_term_prefix : string, default 'N' Prefix of subpopulation term used as denominator in calculating force of infection (see method calculate_fois). subpop_interaction_prefix : string 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_modifier : string 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_params : list of strings A list of all the parameters that are NOT: - directly to do with transmission - subpopulation specific (sub_pop_params). subpop_params : list 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_focus : string 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). .. attribute:: parameter_names The names of all the parameters. :type: list of strings .. attribute:: population_terms Subpopulation population terms used in calculating force of infection (see method calculate_fois). :type: list of strings .. attribute:: transmission_terms The transmission terms for each subpopulation (see method calculate_fois). :type: list of strings .. attribute:: subpop_interaction_terms The terms for each interaction between subpopulations used when calculating force of infection (see method calculate_fois). :type: list of strings .. attribute:: total_subpops Total number of subpopulations. :type: int .. attribute:: total_parameters Total number of parameters in model. :type: int .. attribute:: dimensions Dimensions of metapopulation. :type: list of sets of ints/strings .. attribute:: 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} .. attribute:: subpop_transition_params_dict Each entry outlines parameters responsible for flows between subpopulations. :type: dictionary {string: list of dictionaries} .. attribute:: all_states_index Keys are all the states values are the associated indexes for use with numpy.arrays. :type: dictionary .. attribute:: 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}} .. attribute:: 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]} .. attribute:: 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]} .. attribute:: 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]} .. attribute:: 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]} .. attribute:: infectious_and_symptomatic_states A list of infectious and symptomatic states. :type: list of stings .. attribute:: infectious_and_asymptomatic_states A list of infectious and asymptomatic states. :type: list of stings .. attribute:: total_states Total number of states in model. :type: int .. attribute:: subpop_coordinates Coordinates of all subpopulations. :type: list [tuples of ints/strings] .. attribute:: subpop_suffixes Suffixes to appended to parameters specific to subpopulations. :type: list of stings .. method:: set_structure(self, scaffold, foi_population_focus=None) Set metapopulation structure using scaffold. .. method:: ode(self, y, t, \*parameters): Evaluate the ODE given states (y), time (t) and parameters .. method:: 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 :mod:`odeint ` giving ode method to odeint. .. method:: get_state_index_dict_of_coordinate(self, coordinate, axis=0): Fetch state index dictionaries for given coordinate on an axis. .. method:: get_indexes_of_coordinate(self, coordinate, axis=0): Fetch a list of indices for all states for given coordinate on axis. .. rubric:: 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. .. py:property:: dimensions .. py:property:: foi_population_focus .. py:property:: subpop_model .. py:property:: parameters returns: A dictionary of parameter values. :rtype: Dictionary .. py:property:: shape Number of entries in each axis of the metapopulation model. :rtype: tuple of ints .. py:attribute:: _dimensions :value: [] .. py:attribute:: _subpop_model .. py:attribute:: _foi_population_focus .. py:method:: subpop_transfer(y, y_deltas, t, from_coordinates, parameters) Calculates the transfers of people from a subpopulation to all other subpopulations. :param y: Values of variables at time t. :type y: numpy.array :param y_deltas: Store of delta (derivative at t) of variables in y which this method adds/subtracts to. :type y_deltas: numpy.Array :param t: Time t for which derivative is being calculated. :type t: float :param from_coordinates: Coordinates for subpopulation being transferred. :type from_coordinates: tuple or list of strings :param parameters: Dictionary of parameter values used in calculating derivative. :type parameters: dictionary {keys are strings: values are numeric} :returns: **y_deltas** -- Store of delta (derivative) of variables in y which this method adds/subtracts to. :rtype: numpy.array .. py:method:: ode(y, t, *parameters) Evaluate the ODE given states (y), time (t) and parameters :param y: State variables. :type y: numpy.array :param t: Time. :type t: float :param parameters: Parameter values. **NOTE* these values must be given in the same order as the instance attribute parameter_names. :type parameters: floats :returns: **y_delta** -- Deltas of state variables at time point t. :rtype: `numpy.ndarray` .. py:method:: calculate_fois(y, parameters, t) Calculates the Forces of Infection (FOIs) experienced by each subpopulation. :param y: Values of state variables at current time. :type y: numpy.array :param parameters: Dictionary of parameter values used in calculating derivative. :type parameters: dictionary {strings: numeric} :param t: Time. :type t: float :returns: **fois** -- Dictionary of the FOIs experienced at each coordinate. :rtype: dictionary {tupple of strings or ints: float} .. py:method:: _subpop_infected_interaction(y, coordinates_i, coordinates_j, parameters, asymptomatic_transmission_modifier, t) .. py:method:: get_state_index_dict_of_coordinate(coordinate, axis=0) Fetch state index dictionaries for given coordinate on an axis. :param coordinate: Coordinate of :type coordinate: int or str :param axis: Axis on which coordinate is found. :type axis: int default = 0 :returns: **nested dict** :rtype: {tuple of int/str: {str: int}} .. py:method:: get_indexes_of_coordinate(coordinate, axis=0) Fetch a list of indices for all states for given coordinate on axis. :param coordinate: Coordinate of :type coordinate: int or str :param axis: Axis on which coordinate is found. :type axis: int default = 0 :rtype: list of ints .. py:method:: coordinates_to_subpop_suffix(coordinates) :staticmethod: Transform coordinates to subpopulation suffix appended to subpopulation specific parameters. :param coordinates: Coordinate of subpopulation :type coordinates: list/tuple of ints or strings :rtype: string .. py:method:: _instantaneous_transfer(population_transitioning, population, t=None) .. py:method:: 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 :mod:`odeint `, giving ode method to odeint. Modified method from the pygom method `DeterministicOde `. :param x0: Initial values of states. :type x0: array like :param t: Timeframe over which model is to be simulated. :type t: array like :param full_output: If additional information from the integration is required :type full_output: bool, optional :param kwargs_to_pass_to_odeint: Key word arguments to pass to scipy.integrate.odeint. :type kwargs_to_pass_to_odeint: dictionary :returns: **solution** -- Multi-index columns are clusters by vaccine groups by states. :rtype: pandas.DataFrame .. py:method:: results_array_to_df(results, t) Converts array of results into a dataframe with multi-index columns reflecting meta-population structure. :param results: Results from simulations of model. :type results: np.array :param t: Time over which model was simulated. :type t: np.array :returns: **results_df** -- Results with multi-index columns reflecting meta-population structure. :rtype: pandas.DataFrame .. py:method:: __len__() Number of axis/dimensions of the metapopulation model. :rtype: int .. py:class:: MultinomialSeeder(branch_info) Makes multinomial draws selecting an infectious hosts branch and then state. :param branch_info: 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). :type branch_info: nested dict .. attribute:: branches Infection branches that a host can be placed upon. :type: dict {str: InfectionBranch} .. attribute:: parameters Parameters (outflows) given in branch_info. :type: set of strings .. method:: seed_infections(n, branch_probability, parameters) Draw selection of states to place infected hosts. .. py:method:: set_seed(seed) Sets random number generator seed. :param seed: :type seed: int (>0) .. py:method:: _seed_branches(n, branch_probability) .. py:method:: seed_infections(n, branch_probability, parameters) Draw selection of states to place infected hosts. :param n: Number of infections to seed. :type n: int :param branch_probability: Probability of being on each infection branch. :type branch_probability: dict {string, float} :param parameters: Dictionary of parameter values. :type parameters: dict {str: Number} :returns: **infections_draw** -- Keys are infected states values are number of hosts in state. :rtype: dict {str: int}