model

This module contains the main disease modelling class.

class summer.model.BackendType

Bases: object

REFERENCE = 'reference'
VECTORIZED = 'vectorized'
class summer.model.CompartmentalModel(times: Tuple[int, int], compartments: List[str], infectious_compartments: List[str], timestep: float = 1.0)

Bases: object

A compartmental disease model

This model defines a set of compartments which each contain a population. Disease dynamics are defined by a set of flows which link the compartments together. The model is run over a period of time, starting from some initial conditions to predict the future state of a disease.

Parameters
  • times – The start and end times. ***

  • compartments – The compartments to simulate.

  • infectious_compartments – The compartments which are counted as infectious.

  • time_step (optional) – The timesteps to return results for. This request does not affect the ODE solver, but is used for the stochastic solver. Defaults to 1.

times

The times that the model will simulate.

Type

np.ndarray

compartments

The model’s compartments.

Type

List[Compartment]

initial_population

The model’s starting population. The indices of this array match to the compartments attribute. This is zero by default, but should be set with the set_initial_population method.

Type

np.ndarray

outputs

The values of each compartment for each requested timestep. For C compartments and T timesteps this will be a TxC matrix. The column indices of this array will match up with compartments and the row indices will match up with times.

Type

np.ndarray

derived_outputs

Additional results that are calculated from outputs for each timestep.

Type

Dict[str, np.ndarray]

add_crude_birth_flow(name: str, birth_rate: Union[float, Callable[float, float]], dest: str, dest_strata: Optional[Dict[str, str]] = None, expected_flow_count: Optional[int] = None)

Adds a crude birth rate flow to the model. The number of births will be determined by the product of the birth rate and total population.

Parameters
  • name – The name of the new flow.

  • birth_rate – The fractional crude birth rate per timestep.

  • dest – The name of the destination compartment.

  • dest_strata (optional) – A whitelist of strata to filter the destination compartments.

  • expected_flow_count (optional) – Used to assert that a particular number of flows are created.

add_death_flow(name: str, death_rate: Union[float, Callable[float, float]], source: str, source_strata: Optional[Dict[str, str]] = None, expected_flow_count: Optional[int] = None)

Adds a flow where people die and leave the compartment, reducing the total population.

Parameters
  • name – The name of the new flow.

  • death_rate – The fractional death rate per timestep.

  • source – The name of the source compartment.

  • source_strata (optional) – A whitelist of strata to filter the source compartments.

  • expected_flow_count (optional) – Used to assert that a particular number of flows are created.

add_derived_value_process(name: str, processor: summer.compute.DerivedValueProcessor)

Calculate (at runtime) values derived from the compartment values and flow rates; these can be used by function flows

Parameters
  • name (str) – Name (key) of derived value

  • processor (DerivedValueProcessor) – Object providing computation

add_function_flow(name: str, flow_rate_func: Callable[[List[summer.compartment.Compartment], numpy.ndarray, numpy.ndarray, float], numpy.ndarray], source: str, dest: str, source_strata: Optional[Dict[str, str]] = None, dest_strata: Optional[Dict[str, str]] = None, expected_flow_count: Optional[int] = None)

A flow that transfers people from a source to a destination based on a user-defined function. This can be used to define more complex flows if required. See flows.FunctionFlow for more details on the arguments to the function.

Parameters
  • name – The name of the new flow.

  • flow_rate_func – A function that returns the flow rate, before adjustments.

  • source – The name of the source compartment.

  • dest – The name of the destination compartment.

  • source_strata (optional) – A whitelist of strata to filter the source compartments.

  • dest_strata (optional) – A whitelist of strata to filter the destination compartments.

  • expected_flow_count (optional) – Used to assert that a particular number of flows are created.

add_importation_flow(name: str, num_imported: Union[float, Callable[float, float]], dest: str, dest_strata: Optional[Dict[str, str]] = None, expected_flow_count: Optional[int] = None)

Adds an importation flow to the model, where people enter the destination compartment from outside the system. The number of people imported per timestep is completely determined by num_imported.

Parameters
  • name – The name of the new flow.

  • num_imported – The number of people arriving per timestep.

  • dest – The name of the destination compartment.

  • dest_strata (optional) – A whitelist of strata to filter the destination compartments.

  • expected_flow_count (optional) – Used to assert that a particular number of flows are created.

add_infection_density_flow(name: str, contact_rate: Union[float, Callable[float, float]], source: str, dest: str, source_strata: Optional[Dict[str, str]] = None, dest_strata: Optional[Dict[str, str]] = None, expected_flow_count: Optional[int] = None)

Adds a flow that infects people using an “infection density” contact rate, which is when the infectious multiplier is determined by the number of infectious people.

Parameters
  • name – The name of the new flow.

  • contact_rate – The contact rate.

  • source – The name of the source compartment.

  • dest – The name of the destination compartment.

  • source_strata (optional) – A whitelist of strata to filter the source compartments.

  • dest_strata (optional) – A whitelist of strata to filter the destination compartments.

  • expected_flow_count (optional) – Used to assert that a particular number of flows are created.

add_infection_frequency_flow(name: str, contact_rate: Union[float, Callable[float, float]], source: str, dest: str, source_strata: Optional[Dict[str, str]] = None, dest_strata: Optional[Dict[str, str]] = None, expected_flow_count: Optional[int] = None)

Adds a flow that infects people using an “infection frequency” contact rate, which is when the infectious multiplier is determined by the proportion of infectious people to the total population.

Parameters
  • name – The name of the new flow.

  • contact_rate – The effective contact rate.

  • source – The name of the source compartment.

  • dest – The name of the destination compartment.

  • source_strata (optional) – A whitelist of strata to filter the source compartments.

  • dest_strata (optional) – A whitelist of strata to filter the destination compartments.

  • expected_flow_count (optional) – Used to assert that a particular number of flows are created.

add_replacement_birth_flow(name: str, dest: str, dest_strata: Optional[Dict[str, str]] = None, expected_flow_count: Optional[int] = None)

Adds a death-replacing birth flow to the model. The number of births will replace the total number of deaths each year

Parameters
  • name – The name of the new flow.

  • dest – The name of the destination compartment.

  • dest_strata (optional) – A whitelist of strata to filter the destination compartments.

  • expected_flow_count (optional) – Used to assert that a particular number of flows are created.

add_transition_flow(name: str, fractional_rate: Union[float, Callable[float, float]], source: str, dest: str, source_strata: Optional[Dict[str, str]] = None, dest_strata: Optional[Dict[str, str]] = None, expected_flow_count: Optional[int] = None)

Adds a flow transfers people from a source to a destination based on the population of the source compartment and the fractional flow rate.

Parameters
  • name – The name of the new flow.

  • fractional_rate – The fraction of people that transfer per timestep.

  • source – The name of the source compartment.

  • dest – The name of the destination compartment.

  • source_strata (optional) – A whitelist of strata to filter the source compartments.

  • dest_strata (optional) – A whitelist of strata to filter the destination compartments.

  • expected_flow_count (optional) – Used to assert that a particular number of flows are created.

add_universal_death_flows(base_name: str, death_rate: Union[float, Callable[float, float]])

Adds a universal death rate flow to every compartment in the model. The number of deaths per compartment will be determined by the product of the death rate and the compartment population.

The base name will be used to create the name of each flow. For example a base name of “universal_death” applied to the “S” compartment will result in a flow called “universal_death_for_S”.

Parameters
  • base_name – The base name for each new flow.

  • death_rate – The fractional death rate per timestep.

Returns

The names of the flows added.

Return type

List[str]

request_aggregate_output(name: str, sources: List[str], save_results: bool = True)

Adds a derived output to the model’s results. The output will be the aggregate of other derived outputs.

Parameters
  • name – The name of the derived output.

  • sources – The names of the derived outputs to aggregate.

  • save_results (optional) – Whether to save or discard the results.

request_cumulative_output(name: str, source: str, start_time: Optional[int] = None, save_results: bool = True)

Adds a derived output to the model’s results. The output will be the accumulated values of another derived output over the model’s time period.

Parameters
  • name – The name of the derived output.

  • source – The name of the derived outputs to accumulate.

  • start_time (optional) – The time to start accumulating from, defaults to model start time.

  • save_results (optional) – Whether to save or discard the results.

request_derived_value_output(name: str, save_results: bool = True)

Save a derived value process output to derived outputs

Parameters
  • name (str) – Name (key) of derived value process

  • save_results (bool, optional) – Save outputs (or discard if False)

request_function_output(name: str, func: Callable[numpy.ndarray, numpy.ndarray], sources: List[str], save_results: bool = True)

Adds a derived output to the model’s results. The output will be the result of a function which takes a list of sources as an input.

Parameters
  • name – The name of the derived output.

  • func – A function used to calculate the derived ouput.

  • sources – The derived ouputs to input into the function.

  • save_results (optional) – Whether to save or discard the results.

Example

Request a function-based derived output:

model.request_output_for_compartments(

compartments=[“S”, “E”, “I”, “R”], name=”total_population”, save_results=False

) model.request_output_for_compartments(

compartments=[“R”], name=”recovered_population”, save_results=False

)

def calculate_proportion_seropositive(recovered_pop, total_pop):

return recovered_pop / total_pop

model.request_function_output(

name=”proportion_seropositive”, func=calculate_proportion_seropositive, sources=[“recovered_population”, “total_population”],

)

request_output_for_compartments(name: str, compartments: List[str], strata: Optional[Dict[str, str]] = None, save_results: bool = True)

Adds a derived output to the model’s results. The output will be the aggregate population of the requested compartments at the at each timestep.

Parameters
  • name – The name of the derived output.

  • compartments – The name of the compartments to track.

  • strata (optional) – A whitelist of strata to filter the compartments.

  • save_results (optional) – Whether to save or discard the results.

request_output_for_flow(name: str, flow_name: str, source_strata: Optional[Dict[str, str]] = None, dest_strata: Optional[Dict[str, str]] = None, save_results: bool = True, raw_results: bool = False)

Adds a derived output to the model’s results. The output will be the value of the requested flow at each timestep.

Parameters
  • name – The name of the derived output.

  • flow_name – The name of the flow to track.

  • source_strata (optional) – A whitelist of strata to filter the source compartments.

  • dest_strata (optional) – A whitelist of strata to filter the destination compartments.

  • save_results (optional) – Whether to save or discard the results. Defaults to True.

  • raw_results (optional) – Whether to use raw interpolated flow rates, or post-process them so that they’re more represenative of the changes in compartment sizes. Defaults to False.

run(solver: str = 'solve_ivp', backend: str = 'vectorized', backend_args: Optional[dict] = None, **kwargs)

Runs the model over the provided time span, calculating the outputs and the derived outputs. The model calculates the outputs by solving an ODE which is defined by the initial population and the inter-compartmental flows.

Note: The default ODE solver used to produce the model’s outputs does not necessarily evaluate every requested timestep. This adaptive solver can skip over times, or double back when trying to characterize the ODE. The final results are produced by interpolating the solution produced by the ODE solver. This means that model dynamics that only occur in short time periods may not be reflected in the outputs.

Parameters
  • solver (optional) – The ODE solver to use, defaults to SciPy’s IVP solver.

  • **kwargs (optional) – Extra arguments to supplied to the solver, see summer.solver for details.

run_stochastic(seed: Optional[int] = None, backend: str = 'vectorized', backend_args: Optional[dict] = None)

Runs the model over the provided time span, calculating the outputs and the derived outputs. Uses an stochastic interpretation of flow rates.

set_baseline(baseline)

Set a baseline model to be used for this (scenario) run Sets initial population values to the baseline values for this model’s start time Cumulative and relative outputs will refer to the baseline

Parameters

baseline (CompartmentalModel) – The baseline model to be used as reference

set_derived_outputs_whitelist(whitelist: List[str])

Request that we should only calculate a subset of the model’s derived outputs. This can be useful when you only care about some results and you want to cut down on runtime. For example, we may only need some derived outputs for calibration, but may need more later when we want to know all the dyanmics that the model actually showed.

Parameters

whitelist – A list of the derived output names to calculate, ignoring all others.

set_hacking_function(hfunc: Callable)

Set a function to interact with model internals; will be called after model backend is instantiated (but before run) :param hfunc: Function taking model as argument :type hfunc: Callable[CompartmentalModel]

set_initial_population(distribution: Dict[str, float])

Sets the initial population of the model, which is zero by default.

Parameters

distribution – A map of populations to be assigned to compartments.

stratify_with(strat: summer.stratification.Stratification)

Apply the stratification to the model’s flows and compartments.

Parameters

strat – The stratification to apply.