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:
epipack.integrators.IntegrationMixin
A general class to define standard mean-field compartmental epidemiological model.
-
compartments
¶ A list containing strings that describe each compartment, (e.g. "S", "I", etc.).
-
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
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
oftuple
) --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
oftuple
) --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
oftuple
) --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
oftuple
) --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 timey (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_jacobian_leading_eigenvalue
(y0=None, returntype='complex')[source]¶ Return leading eigenvalue of Jacobian at point
y0
. Will useself.y0
if argumenty0
isNone
. Use argumentreturntype='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 argumenty0
isNone
.
-
get_next_generation_matrix_leading_eigenvalue
(y0=None, returntype='real')[source]¶ Return the leading eigenvalue of the next generation matrix at point
y0
. Will useself.y0
if argumenty0
isNone
. Wheny0
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_transmission_matrix
(y0=None)[source]¶ Return transmission matrix at point
y0
. Will useself.y0
if argumenty0
isNone
.
-
set_linear_rates
(rate_list, allow_nonzero_column_sums=False, reset_rates=True)[source]¶ Define the linear transition rates between compartments.
- Parameters
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
oftuple
) --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
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:
epipack.numeric_matrix_epi_models.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:
epipack.numeric_matrix_epi_models.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:
epipack.numeric_matrix_epi_models.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:
epipack.numeric_matrix_epi_models.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:
epipack.numeric_matrix_epi_models.MatrixEpiModel
An SIS model derived from
epipack.numeric_matrix_based_epi_models.MatrixEpiModel
.