Deterministic simulations¶

Deterministic simulations with compartment models and age structure

A list of methods for deterministic simulations of age-structured compartment models along with link to notebook examples is given below.

Model¶

class pyross.deterministic.Model¶

Generic user-defined epidemic model.

…

Parameters:

model_spec (dict) – A dictionary specifying the model. See Examples.
parameters (dict) – Contains the values for the parameters given in the model specification. All parameters can be float if not age-dependent, and np.array(M,) if age-dependent
M (int) – Number of compartments of individual for each class. I.e len(contactMatrix)
Ni (np.array(M, )) – Initial number in each compartment and class
time_dep_param_mapping (python function, optional) – A user-defined function that takes a dictionary of time-independent parameters and time as an argument, and returns a dictionary of the parameters of model_spec. Default: Identical mapping of the dictionary at all times.

Examples

An example of model_spec and parameters for SIR class with a constant influx

>>> model_spec = {
        "classes" : ["S", "I"],
        "S" : {
            "constant"  : [ ["k"] ],
            "infection" : [ ["I", "S", "-beta"] ]
        },
        "I" : {
            "linear"    : [ ["I", "-gamma"] ],
            "infection" : [ ["I", "S", "beta"] ]
        }
    }
>>> parameters = {
        'beta': 0.1,
        'gamma': 0.1,
        'k': 1,
    }

model_class_data()¶

Parameters:	data (dict) – The object returned by simulate.
Returns:
Return type:	The population of class model_class_key as a time series

simulate()¶

Simulates a compartment model given initial conditions, choice of integrator and other parameters. Returns the time series data and parameters in a dict. Internally calls the method ‘simulator’ of CommonMethods

…

Parameters:	x0 (np.array or dict) – Initial conditions. If it is an array it should have length M(model_dimension-1), where x0[i + jM] should be the initial value of model class i of age group j. The removed R class must be left out. If it is a dict then it should have a key corresponding to each model class, with a 1D array containing the initial condition for each age group as value. One of the classes may be left out, in which case its initial values will be inferred from the others. contactMatrix (python function(t)) – The social contact matrix C_{ij} denotes the average number of contacts made per day by an individual in class i with an individual in class j Tf (float) – Final time of integrator Nf (Int) – Number of time points to evaluate. Ti (float, optional) – Start time of integrator. The default is 0. integrator (TYPE, optional) – Integrator to use either from scipy.integrate or odespy. The default is ‘odeint’. maxNumSteps (int, optional) – maximum number of steps the integrator can take. The default is 100000. *kwargs (kwargs for integrator*) –
Returns:	data – X: output path from integrator, t : time points evaluated at, ‘param’: input param to integrator.
Return type:	dict

Link to example notebook

Spp¶

class pyross.deterministic.Spp¶

This is a slightly more specific version of the class Model.

Spp is still supported for backward compatibility.

Model class is recommended over Spp for new users.

The Spp class works like Model but infection terms use a single class S

…

Parameters:

model_spec (dict) – A dictionary specifying the model. See Examples.
parameters (dict) – Contains the values for the parameters given in the model specification. All parameters can be float if not age-dependent, and np.array(M,) if age-dependent
M (int) – Number of compartments of individual for each class. I.e len(contactMatrix)
Ni (np.array(M, )) – Initial number in each compartment and class
time_dep_param_mapping (python function, optional) – A user-defined function that takes a dictionary of time-independent parameters and time as an argument, and returns a dictionary of the parameters of model_spec. Default: Identical mapping of the dictionary at all times.

Examples

An example of model_spec and parameters for SIR class with a constant influx

>>> model_spec = {
        "classes" : ["S", "I"],
        "S" : {
            "constant"  : [ ["k"] ],
            "infection" : [ ["I", "-beta"] ]
        },
        "I" : {
            "linear"    : [ ["I", "-gamma"] ],
            "infection" : [ ["I", "beta"] ]
        }
    }
>>> parameters = {
        'beta': 0.1,
        'gamma': 0.1,
        'k': 1,
    }

Link to example notebook

SppQ¶

class pyross.deterministic.SppQ¶

User-defined epidemic model with quarantine stage.

This is a slightly more specific version of the class Model.

SppQ is still supported for backward compatibility.

Model class is recommended over SppQ for new users.

To initialise the SppQ model, …

Parameters:

model_spec (dict) – A dictionary specifying the model. See Examples.
parameters (dict) – Contains the values for the parameters given in the model specification. All parameters can be float if not age-dependent, and np.array(M,) if age-dependent
M (int) – Number of compartments of individual for each class. I.e len(contactMatrix)
Ni (np.array(M, )) – Initial number in each compartment and class
time_dep_param_mapping (python function, optional) – A user-defined function that takes a dictionary of time-independent parameters and time as an argument, and returns a dictionary of the parameters of model_spec. Default: Identical mapping of the dictionary at all times.

Examples

An example of model_spec and parameters for SIR class with random testing (without false positives/negatives) and quarantine

>>> model_spec = {
        "classes" : ["S", "I"],
        "S" : {
            "infection" : [ ["I", "-beta"] ]
        },
        "I" : {
            "linear"    : [ ["I", "-gamma"] ],
            "infection" : [ ["I", "beta"] ]
        },
        "test_pos"  : [ "p_falsepos", "p_truepos", "p_falsepos"] ,
        "test_freq" : [ "tf", "tf", "tf"]
    }
>>> parameters = {
        'beta': 0.1,
        'gamma': 0.1,
        'p_falsepos': 0
        'p_truepos': 1
        'tf': 1
    }

model_class_data()¶

Parameters:	data (dict) – The object returned by simulate.
Returns:
Return type:	The population of class model_class_key as a time series

simulate()¶

Simulates a compartment model given initial conditions, choice of integrator and other parameters. Returns the time series data and parameters in a dict. Internally calls the method ‘simulator’ of CommonMethods

…

Parameters:	x0 (np.array or dict) – Initial conditions. If it is an array it should have length M(model_dimension-1), where x0[i + jM] should be the initial value of model class i of age group j. The removed R class must be left out. If it is a dict then it should have a key corresponding to each model class, with a 1D array containing the initial condition for each age group as value. One of the classes may be left out, in which case its initial values will be inferred from the others. contactMatrix (python function(t)) – The social contact matrix C_{ij} denotes the average number of contacts made per day by an individual in class i with an individual in class j testRate (python function(t)) – The total number of PCR tests performed per day Tf (float) – Final time of integrator Nf (Int) – Number of time points to evaluate. Ti (float, optional) – Start time of integrator. The default is 0. integrator (TYPE, optional) – Integrator to use either from scipy.integrate or odespy. The default is ‘odeint’. maxNumSteps (int, optional) – maximum number of steps the integrator can take. The default value is 100000. *kwargs (kwargs for integrator*) –
Returns:	data – X: output path from integrator, t : time points evaluated at, ‘param’: input param to integrator.
Return type:	dict

Link to example notebook

SIR¶

class pyross.deterministic.SIR¶

Susceptible, Infected, Removed (SIR)

Ia: asymptomatic
Is: symptomatic

\[\dot{S_{i}}=-\lambda_{i}(t)S_{i}\]

\[\dot{I}_{i}^{a} = \alpha_{i}\lambda_{i}(t)S_{i}-\gamma_{I^{a}}I_{i}^{a},\]

\[\dot{I}_{i}^{s}= \bar{\alpha_{i}}\lambda_{i}(t)S_{i}-\gamma_{I^{s}}I_{i}^{s},\]

\[\dot{R}_{i}=\gamma_{I^{a}}I_{i}^{a}+\gamma_{I^{s}}I_{i}^{s}.\]

\[\lambda_{i}(t)=\beta\sum_{j=1}^{M}\left(C_{ij}^{a}(t)\frac{I_{j}^{a}}{N_{j}}+C_{ij}^{s}(t) \frac{I_{j}^{s}}{N_{j}}\right),\quad i,j=1,\ldots M\]

…

Parameters:

parameters (dict) –
Contains the following keys:

alpha: float, np.array (M,)

Fraction of infected who are asymptomatic.

beta: float, np.array (M,)

Rate of spread of infection.

gIa: float, np.array (M,)

Rate of removal from asymptomatic individuals.

gIs: float, np.array (M,)

Rate of removal from symptomatic individuals.

fsa: float, np.array (M,)

Fraction by which symptomatic individuals do not self-isolate.
M (int) – Number of compartments of individual for each class. I.e len(contactMatrix)
Ni (np.array(M, )) – Initial number in each compartment and class

Examples

An example of the SIR class

>>> M = 1                   # SIR model with no age structure
>>> Ni = 1000*np.ones(M)    # only one age group
>>> N = np.sum(Ni)          # total population
>>>
>>> beta  = 0.2             # Infection rate
>>> gIa   = 0.1             # Removal rate of asymptomatic infectives
>>> gIs   = 0.1             # Removal rate of symptomatic infectives
>>> alpha = 0               # Fraction of asymptomatic infectives
>>> fsa   = 1               # self-isolation of symtomatic infectives
>>>
>>> Ia0 = np.array([0])     # Intial asymptomatic infectives
>>> Is0 = np.array([1])     # Initial symptomatic
>>> R0  = np.array([0])     # No removed individuals initially
>>> S0  = N-(Ia0+Is0+R0)    # S + Ia + Is + R = N
>>>
>>> # there is no contact structure
>>> def contactMatrix(t):
>>>     return np.identity(M)
>>>
>>> # duration of simulation and data file
>>> Tf = 160;  Nt=160;
>>>
>>> # instantiate model
>>> parameters = {'alpha':alpha, 'beta':beta, 'gIa':gIa, 'gIs':gIs,'fsa':fsa}
>>> model = pyross.deterministic.SIR(parameters, M, Ni)
>>>
>>> # simulate model using two possible ways
>>> data1 = model.simulate(S0, Ia0, Is0, contactMatrix, Tf, Nt)
>>> data2 = model.simulator(np.concatenate((S0, Ia0, Is0)), contactMatrix, Tf, Nt)

simulate()¶

Simulates a compartment model given initial conditions, choice of integrator and other parameters. Returns the time series data and parameters in a dict. Internally calls the method ‘simulator’ of CommonMethods

…

Parameters:	S0 (np.array) – Initial number of susceptables. Ia0 (np.array) – Initial number of asymptomatic infectives. Is0 (np.array) – Initial number of symptomatic infectives. contactMatrix (python function(t)) – The social contact matrix C_{ij} denotes the average number of contacts made per day by an individual in class i with an individual in class j Tf (float) – Final time of integrator Nf (Int) – Number of time points to evaluate. Ti (float, optional) – Start time of integrator. The default is 0. integrator (TYPE, optional) – Integrator to use either from scipy.integrate or odespy. The default is ‘odeint’. maxNumSteps (int, optional) – maximum number of steps the integrator can take. The default is 100000. *kwargs (kwargs for integrator*) –
Returns:	X: output path from integrator, t : time points evaluated at, ‘param’: input param to integrator.
Return type:	dict

Link to example notebook

SIkR¶

class pyross.deterministic.SIkR¶

Susceptible, Infected, Removed (SIkR). Method of k-stages of I

\[\dot{S_{i}}=-\lambda_{i}(t)S_{i},\]

\[\dot{I}_{i}^{1}=k_{E}\gamma_{E}E_{i}^{k}-k_{I}\gamma_{I}I_{i}^{1},\]

\[\dot{I}_{i}^{k}=k_{I}\gamma_{I}I_{i}^{(k-1)}-k_{I}\gamma_{I}I_{i}^{k},\]

\[\dot{R}_{i}=k_{I}\gamma_{I}I_{i}^{k}.\]

\[\lambda_{i}(t)=\beta\sum_{j=1}^{M}\sum_{n=1}^{k}C_{ij}(t)\frac{I_{j}^{n}}{N_{j}},\]

…

Parameters:	parameters (dict) – Contains the following keys: beta: float Rate of spread of infection. gI: float Rate of removal from infectives. kI: int number of stages of infection. M (int) – Number of compartments of individual for each class. I.e len(contactMatrix) Ni (np.array(M, )) – Initial number in each compartment and class

simulate()¶

Simulates a compartment model given initial conditions, choice of integrator and other parameters. Returns the time series data and parameters in a dict. Internally calls the method ‘simulator’ of CommonMethods

…

Parameters:	S0 (np.array) – Initial number of susceptables. I0 (np.array) – Initial number of infectives. contactMatrix (python function(t)) – The social contact matrix C_{ij} denotes the average number of contacts made per day by an individual in class i with an individual in class j Tf (float) – Final time of integrator Nf (Int) – Number of time points to evaluate. Ti (float, optional) – Start time of integrator. The default is 0. integrator (TYPE, optional) – Integrator to use either from scipy.integrate or odespy. The default is ‘odeint’. maxNumSteps (int, optional) – maximum number of steps the integrator can take. The default is 100000. *kwargs (kwargs for integrator*) –
Returns:	X: output path from integrator, t : time points evaluated at, ‘param’: input param to integrator.
Return type:	dict

Link to example notebook

SEIR¶

class pyross.deterministic.SEIR¶

Susceptible, Exposed, Infected, Removed (SEIR)

Ia: asymptomatic
Is: symptomatic

\[\dot{S_{i}}=-\lambda_{i}(t)S_{i}\]

\[\dot{E}_{i}=\lambda_{i}(t)S_{i}-\gamma_{E}E_{i}\]

\[\dot{I}_{i}^{a} = \alpha_{i}\gamma_{E}^{i}E_{i}-\gamma_{I^{a}}I_{i}^{a},\]

\[\dot{I}_{i}^{s}= \bar{\alpha_{i}}\gamma_{E}^{i}E_{i}-\gamma_{I^{s}}I_{i}^{s},\]

\[\dot{R}_{i}=\gamma_{I^{a}}I_{i}^{a}+\gamma_{I^{s}}I_{i}^{s}.\]

\[\lambda_{i}(t)=\beta\sum_{j=1}^{M}\left(C_{ij}^{a}(t)\frac{I_{j}^{a}}{N_{j}}+C_{ij}^{s}(t) \frac{I_{j}^{s}}{N_{j}}\right),\quad i,j=1,\ldots M\]

…

Parameters:

parameters (dict) –
Contains the following keys:

alpha: float, np.array (M,)

Fraction of infected who are asymptomatic.

beta: float, np.array (M,)

Rate of spread of infection.

gE: float, np.array (M,)

Rate of removal from exposed individuals.

gIa: float, np.array (M,)

Rate of removal from asymptomatic individuals.

gIs: float, np.array (M,)

Rate of removal from symptomatic individuals.

fsa: float, np.array (M,)

Fraction by which symptomatic individuals do not self-isolate.
M (int) – Number of compartments of individual for each class. I.e len(contactMatrix)
Ni (np.array(M, )) – Initial number in each compartment and class

simulate()¶

Simulates a compartment model given initial conditions, choice of integrator and other parameters. Returns the time series data and parameters in a dict. Internally calls the method ‘simulator’ of CommonMethods

…

Parameters:	S0 (np.array) – Initial number of susceptables. E0 (np.array) – Initial number of exposed. Ia0 (np.array) – Initial number of asymptomatic infectives. Is0 (np.array) – Initial number of symptomatic infectives. contactMatrix (python function(t)) – The social contact matrix C_{ij} denotes the average number of contacts made per day by an individual in class i with an individual in class j Tf (float) – Final time of integrator Nf (Int) – Number of time points to evaluate. Ti (float, optional) – Start time of integrator. The default is 0. integrator (TYPE, optional) – Integrator to use either from scipy.integrate or odespy. The default is ‘odeint’. maxNumSteps (int, optional) – maximum number of steps the integrator can take. The default is 100000. *kwargs (kwargs for integrator*) –
Returns:	X: output path from integrator, t : time points evaluated at, ‘param’: input param to integrator.
Return type:	dict

Link to example notebook

SEkIkR¶

class pyross.deterministic.SEkIkR¶

Susceptible, Exposed, Infected, Removed (SEkIkR). Method of k-stages of E and I

\[\dot{S_{i}}=-\lambda_{i}(t)S_{i},\]

\[\dot{E}_{i}^{1}=\lambda_{i}(t)S_{i}-k_{E}\gamma_{E}E_{i}^{1}\]

\[\dot{E}_{i}^{k}=k_{E}\gamma_{E}E_{i}^{k-1}-k_{E}\gamma_{E}E_{i}^{k}\]

\[\dot{I}_{i}^{1}=k_{E}\gamma_{E}E_{i}^{k}-k_{I}\gamma_{I}I_{i}^{1},\]

\[\dot{I}_{i}^{k}=k_{I}\gamma_{I}I_{i}^{(k-1)}-k_{I}\gamma_{I}I_{i}^{k},\]

\[\dot{R}_{i}=k_{I}\gamma_{I}I_{i}^{k}.\]

\[\lambda_{i}(t)=\beta\sum_{j=1}^{M}\sum_{n=1}^{k}C_{ij}(t)\frac{I_{j}^{n}}{N_{j}},\]

… :param parameters: Contains the following keys:

beta: float

Rate of spread of infection.

gI: float

Rate of removal from infected individuals.

gE: float

Rate of removal from exposed individuals.

kI: int

number of stages of infectives.

kE: int

number of stages of exposed.

Parameters:	M (int) – Number of compartments of individual for each class. I.e len(contactMatrix) Ni (np.array(M, )) – Initial number in each compartment and class

simulate()¶

Simulates a compartment model given initial conditions, choice of integrator and other parameters. Returns the time series data and parameters in a dict. Internally calls the method ‘simulator’ of CommonMethods

… :param S0: Initial number of susceptables. :type S0: np.array :param E0: Initial number of exposeds. :type E0: np.array :param I0: Initial number of infectives. :type I0: np.array :param contactMatrix: The social contact matrix C_{ij} denotes the

average number of contacts made per day by an individual in class i with an individual in class j

Parameters:	Tf (float) – Final time of integrator Nf (Int) – Number of time points to evaluate. Ti (float, optional) – Start time of integrator. The default is 0. integrator (TYPE, optional) – Integrator to use either from scipy.integrate or odespy. The default is ‘odeint’. maxNumSteps (int, optional) – maximum number of steps the integrator can take. The default is 100000. *kwargs (kwargs for integrator*) –
Returns:	X: output path from integrator, t : time points evaluated at, ‘param’: input param to integrator.
Return type:	dict

Link to example notebook

SEAIRQ¶

class pyross.deterministic.SEAIRQ¶

Susceptible, Exposed, Asymptomatic and infected, Infected, Removed, Quarantined (SEAIRQ)

Ia: asymptomatic
Is: symptomatic
E: exposed
A: asymptomatic and infectious
Q: quarantined

\[\dot{S_{i}}=-\lambda_{i}(t)S_{i}\]

\[\dot{E}_{i}=\lambda_{i}(t)S_{i}-(\gamma_{E}+\tau_{E})A_{i}\]

\[\dot{A}_{i}=\gamma_{E}E_{i}-(\gamma_{A}+\tau_{A})A_{i}\]

\[\dot{I}_{i}^{a}=\alpha_{i}\gamma_{A}A_{i}-(\gamma_{I^{a}}+\tau_{I^a})I_{i}^{a},\]

\[\dot{I}_{i}^{s}=\bar{\alpha_{i}}\gamma_{A}A_{i}-(\gamma_{I^{s}}+\tau_{I^a})I_{i}^{s},\]

\[\dot{R}_{i}=\gamma_{I^{a}}I_{i}^{a}+\gamma_{I^{s}}I_{i}^{s}.\]

\[\dot{Q}_{i}=\tau_{S}S_{i}+\tau_{E}E_{i}+\tau_{A}A_{i}+\tau_{I^{s}}I_{i}^{s}+\tau_{I^{a}}I_{i}^{a}\]

\[\lambda_{i}(t)=\beta\sum_{j=1}^{M}\left(C_{ij}^{a}\frac{I_{j}^{a}}{N_{j}}+C_{ij}^{a} \frac{A_{j}}{N_{j}}+C_{ij}^{s}\frac{I_{j}^{s}}{N_{j}}\right),\]

…

Parameters:

parameters (dict) –
Contains the following keys:

alpha: float

Fraction of infected who are asymptomatic.

beta: float, np.array (M,)

Rate of spread of infection.

gIa: float, np.array (M,)

Rate of removal from asymptomatic individuals.

gIs: float, np.array (M,)

Rate of removal from symptomatic individuals.

gE: float, np.array (M,)

Rate of removal from exposed individuals.

gA: float, np.array (M,)

Rate of removal from activated individuals.

fsa: float, np.array (M,) tE: float, np.array (M,)

testing rate and contact tracing of exposeds

tA: float, np.array (M,)

testing rate and contact tracing of activateds

tIa: float, np.array (M,)

testing rate and contact tracing of asymptomatics

tIs: float, np.array (M,)

testing rate and contact tracing of symptomatics
M (int) – Number of compartments of individual for each class. I.e len(contactMatrix)
Ni (np.array(M, )) – Initial number in each compartment and class

simulate()¶

Simulates a compartment model given initial conditions, choice of integrator and other parameters. Returns the time series data and parameters in a dict. Internally calls the method ‘simulator’ of CommonMethods

…

Parameters:

S0 (np.array) – Initial number of susceptables.
E0 (np.array) – Initial number of exposeds.
A0 (np.array) – Initial number of activateds.
Ia0 (np.array) – Initial number of asymptomatic infectives.
Is0 (np.array) – Initial number of symptomatic infectives.
Q0 (np.array) – Initial number of quarantineds.
contactMatrix (python function(t)) – The social contact matrix C_{ij} denotes the average number of contacts made per day by an individual in class i with an individual in class j
Tf (float) – Final time of integrator
Nf (Int) – Number of time points to evaluate.
Ti (float, optional) – Start time of integrator. The default is 0.
integrator (TYPE, optional) – Integrator to use either from scipy.integrate or odespy. The default is ‘odeint’.
maxNumSteps (int, optional) – maximum number of steps the integrator can take. The default is 100000.
**kwargs (kwargs for integrator) –

Returns:

data – contains the following keys:

X : output path from integrator
t : time points evaluated at,
’param’: input param to integrator.

Return type:

dict

Link to example notebook

CommonMethods¶

class pyross.deterministic.CommonMethods¶

Parent class used for all classes listed below. It includes: a) Integrators used by various deterministic models listed below. b) Method to get time series of S, etc by passing a dict of data. c) Method to set the contactMatrix array, CM

A()¶

Parameters:	data (Data dict) –
Returns:	A
Return type:	Activated population time series

E()¶

Parameters:	data (Data dict) –
Returns:	E
Return type:	Exposed population time series

I()¶

Parameters:	data (Data dict) –
Returns:	Ia
Return type:	Asymptomatics population time series

Ia()¶

Parameters:	data (Data dict) –
Returns:	Ia
Return type:	Asymptomatics population time series

Is()¶

Parameters:	data (Data dict) –
Returns:	Is
Return type:	symptomatics population time series

R()¶

Parameters:	data (Data dict) –
Returns:	R
Return type:	Removed population time series

S()¶

Parameters:	data (Data dict) –
Returns:	S
Return type:	Susceptible population time series

Sx()¶

Parameters:	data (Data dict) –
Returns:
Return type:	Generic compartment Sx

simulator()¶

Simulates a compartment model given initial conditions, choice of integrator and other parameters. Returns the time series data and parameters in a dict.

…

Parameters:	x0 (np.array) – Initial state vector (number of compartment values). An array of size M(model_dimension-1), where x0[i+jM] should be the initial value of model class i of age group j. The removed R class must be left out. If Ni is dynamical, then the last M points store Ni. contactMatrix (python function(t)) – The social contact matrix C_{ij} denotes the average number of contacts made per day by an individual in class i with an individual in class j Tf (float) – Final time of integrator Nf (Int) – Number of time points to evaluate. Ti (float, optional) – Start time of integrator. The default is 0. integrator (TYPE, optional) – Integrator to use either from scipy.integrate or odespy. The default is ‘odeint’. maxNumSteps (int, optional) – maximum number of steps the integrator can take. The default is 100000. *kwargs (kwargs for integrator*) –
Returns:	data – X: output path from integrator, t : time points evaluated at, ‘param’: input param to integrator.
Return type:	dict