Numeric Matrix-Based Models

Provides an API to define Matrix epidemiological models.

class epipack.numeric_matrix_epi_models.MatrixEpiModel(compartments, initial_population_size=1, correct_for_dynamical_population_size=False)[source]

Bases: IntegrationMixin

A general class to define standard mean-field compartmental epidemiological model.

Parameters: compartments (list of string) -- A list containing compartment strings.

compartments

A list containing strings that describe each compartment, (e.g. "S", "I", etc.).

Type: list of string

N_comp

Number of compartments (including population number)

Type: int

linear_rates

Sparse matrix containing transition rates of the linear processes.

Type: scipy.sparse.csr_matrix

quadratic_rates

List of sparse matrices that contain transition rates of the quadratic processes for each compartment.

Type: scipy.sparse.csr_matrix

affected_by_quadratic_process

List of integer compartment IDs, collecting compartments that are affected by the quadratic processes

Type: list of int

Example

>>> epi = MatrixEpiModel(["S","I","R"])
>>> print(epi.compartments)
[ "S", "I", "R" ]

add_fission_processes(process_list)[source]

Define linear fission processes between compartments.

Parameters

process_list (list of tuple) --

A list of tuples that contains fission rates in the following format:

[
    ("source_compartment", rate, "target_compartment_0", "target_compartment_1" ),
    ...
]

Example

For pure exponential growth of compartment B.

epi.add_fission_processes([
    ("B", growth_rate, "B", "B" ),
])

add_fusion_processes(process_list)[source]

Define fusion processes between compartments.

Parameters

process_list (list of tuple) --

A list of tuples that contains fission rates in the following format:

[
    ("coupling_compartment_0", "coupling_compartment_1", rate, "target_compartment_0" ),
    ...
]

Example

Fusion of reactants "A", and "B" to form "C".

epi.add_fusion_processes([
    ("A", "B", reaction_rate, "C" ),
])

add_linear_rates(rate_list, reset_rates=True, allow_nonzero_column_sums=False)[source]: Add linear rates without resetting the existing rate terms. See _tacoma.set_linear_rates() for docstring.

add_quadratic_rates(rate_list, reset_rates=True, allow_nonzero_column_sums=False)[source]: Add quadratic rates without resetting the existing rate terms. See _tacoma.set_quadratic_rates() for docstring.

add_transition_processes(process_list)[source]

Define the linear transition processes between compartments.

Parameters

process_list (list of tuple) --

A list of tuples that contains transitions rates in the following format:

[
    ( source_compartment, rate, target_compartment ),
    ...
]

Example

For an SEIR model.

epi.add_transition_processes([
    ("E", symptomatic_rate, "I" ),
    ("I", recovery_rate, "R" ),
])

add_transmission_processes(process_list)[source]

A wrapper to define quadratic process rates through transmission reaction equations. Note that in stochastic network/agent simulations, the transmission rate is equal to a rate per link. For the mean-field ODEs, the rates provided to this function will just be equal to the prefactor of the respective quadratic terms.

For instance, if you analyze an SIR system and simulate on a network of mean degree \(k_0\), a basic reproduction number \(R_0\), and a recovery rate \(\mu\), you would define the single link transmission process as

("I", "S", R_0/k_0 * mu, "I", "I")

For the mean-field system here, the corresponding reaction equation would read

("I", "S", R_0 * mu, "I", "I")

Parameters

process_list (list of tuple) --

A list of tuples that contains transitions rates in the following format:

[
    ("source_compartment",
     "target_compartment_initial",
     rate,
     "source_compartment",
     "target_compartment_final",
     ),
    ...
]

Example

For an SEIR model.

epi.add_transmission_processes([
    ("I", "S", +1, "I", "E" ),
])

dydt(t, y)[source]

Compute the current momenta of the epidemiological model.

Parameters

t (float) -- Current time
y (numpy.ndarray) -- The first entry is equal to the population size. The remaining entries are equal to the current fractions of the population of the respective compartments

get_compartment(iC)[source]: Get the compartment, given an integer ID iC

get_compartment_id(C)[source]: Get the integer ID of a compartment C

get_jacobian_leading_eigenvalue(y0=None, returntype='complex')[source]: Return leading eigenvalue of Jacobian at point y0. Will use self.y0 if argument y0 is None. Use argument returntype='real' to only obtain the real part of the eigenvalue.

get_next_generation_matrix(y0=None)[source]: Return next generation matrix at point y0. Will use self.y0 if argument y0 is None.

get_next_generation_matrix_leading_eigenvalue(y0=None, returntype='real')[source]

Return the leading eigenvalue of the next generation matrix at point y0. Will use self.y0 if argument y0 is None. When y0 is equal to the initial disease-free state, this function will return the basic reproduction number \(R_0\).

The function will return only the real part by default. Use returntype='complex' to change this.

get_numerical_dydt()[source]: Return a function that obtains t and y as an input and returns dydt of this system

get_transition_matrix()[source]: Return transition matrix.

get_transmission_matrix(y0=None)[source]: Return transmission matrix at point y0. Will use self.y0 if argument y0 is None.

jacobian(y0=None)[source]: Return Jacobian at point y0. Will use self.y0 if argument y0 is None.

set_linear_rates(rate_list, allow_nonzero_column_sums=False, reset_rates=True)[source]

Define the linear transition rates between compartments.

Parameters

rate_list (list of tuple) --
A list of tuples that contains transitions rates in the following format:
```
[
    ( acting_compartment, affected_compartment, rate ),
    ...
]
```
allow_nonzero_column_sums (bool, default : False) -- Traditionally, epidemiological models preserve the total population size. If that's not the case, switch off testing for this.
Example --
reset_rates (bool, default : True) -- Whether to reset all linear rates to zero before converting those.

set_processes(process_list, allow_nonzero_column_sums=False, reset_rates=True, ignore_rate_position_checks=False)[source]

Converts a list of reaction process tuples to rate tuples and sets the rates for this model.

Parameters

process_list (list of tuple) --

A list containing reaction processes in terms of tuples.

[
    # transition process
    ( source_compartment, rate, target_compartment),

    # transmission process
    ( coupling_compartment_0, coupling_compartment_1, rate, target_compartment_0, target_ccompartment_1),

    # fission process
    ( source_compartment, rate, target_compartment_0, target_ccompartment_1),

    # fusion process
    ( source_compartment_0, source_compartment_1, rate, target_compartment),

    # death process
    ( source_compartment, rate, None),

    # birth process
    ( None, rate, target_compartment),
]

allow_nonzero_column_sums (bool, default : False) -- Traditionally, epidemiological models preserve the total population size. If that's not the case, switch off testing for this.
reset_rates (bool, default : True) -- If this is True, reset all rates to zero before setting the new ones.
ignore_rate_position_checks (bool, default = False) -- This function usually checks whether the rate of a reaction is positioned correctly. You can turn this behavior off for transition, birth, death, and transmission processes. (Useful if you want to define symbolic transmission processes that are compartment-dependent).

set_quadratic_rates(rate_list, reset_rates=True, allow_nonzero_column_sums=False)[source]

Define the quadratic transition processes between compartments.

Parameters

rate_list (list of tuple) --

A list of tuples that contains transitions rates in the following format:

[
    (
      "coupling_compartment_0",
      "coupling_compartment_1",
      "affected_compartment",
      rate
     ),
    ...
]

allow_nonzero_column_sums (bool, default : False) -- Traditionally, epidemiological models preserve the total population size. If that's not the case, switch off testing for this.

Example

For an SEIR model.

epi.set_quadratic_rates([
    ("S", "I", "S", -1 ),
    ("S", "I", "E", +1 )
])

Read as

"Coupling of S and I leads to a reduction in "S" proportional to \(S\times I\) and rate -1/time_unit. Furthermore, coupling of S and I leads to an increase in "E" proportional to \(S\times I\) and rate +1/time_unit."

class epipack.numeric_matrix_epi_models.MatrixSEIRModel(R0, recovery_rate, symptomatic_rate, initial_population_size=1.0)[source]

Bases: MatrixEpiModel

An SEIR model derived from epipack.numeric_matrix_based_epi_models.MatrixEpiModel.

class epipack.numeric_matrix_epi_models.MatrixSIModel(infection_rate, initial_population_size=1.0)[source]

Bases: MatrixEpiModel

An SI model derived from epipack.numeric_matrix_based_epi_models.MatrixEpiModel.

class epipack.numeric_matrix_epi_models.MatrixSIRModel(R0, recovery_rate, initial_population_size=1.0)[source]

Bases: MatrixEpiModel

An SIR model derived from epipack.numeric_matrix_based_epi_models.MatrixEpiModel.

class epipack.numeric_matrix_epi_models.MatrixSIRSModel(R0, recovery_rate, waning_immunity_rate, initial_population_size=1.0)[source]

Bases: MatrixEpiModel

An SIRS model derived from epipack.numeric_matrix_based_epi_models.MatrixEpiModel.

class epipack.numeric_matrix_epi_models.MatrixSISModel(R0, recovery_rate, initial_population_size=1.0)[source]

Bases: MatrixEpiModel

An SIS model derived from epipack.numeric_matrix_based_epi_models.MatrixEpiModel.

Parameters

R0 (float) -- The basic reproduction number. From this, the infection rate is computed as infection_rate = R0 * recovery_rate
recovery_rate (float) -- Recovery rate
population_size (float, default = 1.0) -- Number of people in the population.