Models

Overview:

Poisson Noise Branching Process Models

Branch Process model

class branchpro.BranchProModel(initial_r, serial_interval)[source]

BranchProModel Class: Class for the models following a Branching Processes behaviour. It inherits from the ForwardModel class.

In the branching process model, we track the number of cases registered each day, I_t, also known as the “incidence” at time t.

The incidence at time t is modelled by a random variable distributed according to a Poisson distribution with a mean that depends on previous number of cases, according to the following formula:

\[E(I_{t}^{\text(local)}|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = R_{t}\sum_{s=1}^{t}I_{t-s}w_{s}\]

Always apply method set_r_profile() before calling BranchProModel.simulate() for a change of R_t profile!

Parameters:

  • initial_r – (numeric) Value of the reproduction number at the beginning of the epidemic

  • serial_interval – (list) Unnormalised probability distribution of that the recipient first displays symptoms s days after the infector first displays symptoms.

get_r_profile()[source]

Returns R_t profile for the model.

get_serial_intervals()[source]

Returns serial intervals for the model.

set_r_profile(new_rs, start_times, last_time=None)[source]

Creates a new R_t profile for the model.

Parameters:

  • new_rs – sequence of new time-dependent values of the reproduction numbers.

  • start_times – sequence of the first time unit when the corresponding indexed value of R_t in new_rs is used. Must be an ordered sequence and without duplicates or negative values.

  • last_time – total evaluation time; optional.

set_serial_intervals(serial_intervals)[source]

Updates serial intervals for the model.

Parameters:

serial_intervals – New unnormalised probability distribution of that the recipient first displays symptoms s days after the infector first displays symptoms.

simulate(parameters, times)[source]

Runs a forward simulation with the given parameters and returns a time-series with incidence numbers corresponding to the given times .

Parameters:

  • parameters – Initial number of cases.

  • times – The times at which to evaluate. Must be an ordered sequence, without duplicates, and without negative values. All simulations are started at time 0, regardless of whether this value appears in times.

Local and Imported Branch Process model

class branchpro.LocImpBranchProModel(initial_r, serial_interval, epsilon)[source]

LocImpBranchProModel Class: Class for the models following a Branching Processes behaviour with local and imported cases. It inherits from the BranchProModel class.

In the branching process model, we track the number of cases registered each day, I_t, also known as the “incidence” at time t.

For the local & imported cases scenario, to the local incidences we add migration of cases from an external source. The conditions of this external environment may differ from the ones we are currently in through a change in the value of the R number.

To account for this difference, we assume that at all times the R number of the imported cases is proportional to the R number of the local incidences:

\[R_{t}^{\text(imported)} = \epsilon R_{t}^{\text(local)}\]

The local incidence at time t is modelled by a random variable distributed according to a Poisson distribution with a mean that depends on previous number of cases both local and imported, according to the following formula:

\[E(I_{t}^{\text(local)}|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = R_{t}^{\text(local)}\sum_{s=1}^{t}I_{t-s}^{\text(local)}w_{s} + R_{t}^{\text(imported)}\sum_{s=1}^{t}I_{t-s}^{\text(imported)}w_{s}\]

Always apply methods set_r_profile() and set_imported_cases() before calling LocImpBranchProModel.simulate() for a change of R_t profile and for loading the imported cases data!

Parameters:

  • initial_r – (numeric) Value of the reproduction number at the beginning of the epidemic

  • serial_interval – (list) Unnormalised probability distribution of that the recipient first displays symptoms s days after the infector first displays symptoms

  • epsilon – (numeric) Proportionality constant of the R number for imported cases with respect to its analog for local ones.

set_epsilon(new_epsilon)[source]

Updates proportionality constant of the R number for imported cases with respect to its analog for local ones.

Parameters:

new_epsilon – new value of constant of proportionality.

set_imported_cases(times, cases)[source]

Sets number of imported cases and when they occur.

Parameters:

  • times – times at which imported cases occur. Must be an ordered sequence, without duplicates, and without negative values.

  • cases – number of imported cases at that specified point.

simulate(parameters, times)[source]

Runs a forward simulation with the given parameters and returns a time-series with incidence numbers corresponding to the given times .

Parameters:

  • parameters – Initial number of cases.

  • times – The times at which to evaluate. Must be an ordered sequence, without duplicates, and without negative values. All simulations are started at time 0, regardless of whether this value appears in times.

Multiple categories Poisson Branch Process model

class branchpro.MultiCatPoissonBranchProModel(initial_r, serial_interval, num_cat, contact_matrix, transm, multipleSI=False)[source]

MultiCatPoissonBranchProModel Class: Class for the models following a Branching Processes behaviour with Poisson distribution noise and multiple population categories. It inherits from the BranchProModel class.

In the branching process model, we track the number of cases registered for each category and each day, I_{t,i}, also known as the “incidence” at time t.

The incidence at time t is modelled by a random variable distributed according to a Poisson distribution with a mean that depends on previous number of cases, according to the following formula:

\[E(I_{t, i}^{\text(local)}|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = \sum_{j}R_{t}C{i,j}T_{j}\sum_{s=1}^{t}I_{t-s,j}w_{s}\]

Always apply method set_r_profile() before calling NegBinBranchProModel.simulate() for a change of R_t profile!

Parameters:

  • initial_r – (list) List of reproduction numbers per category at the beginning of the epidemic.

  • serial_interval – (list) Unnormalised probability distribution of that the recipient first displays symptoms s days after the infector first displays symptoms for each category.

  • num_cat – (int) Number of categories in which the population is split.

  • contact_matrix – (array) Matrix of contacts between the different categories in which the population is split.

  • transm – (list) List of overall reductions in transmissibility per category.

  • multipleSI – (boolean) Different serial intervals used for categories.

get_contact_matrix()[source]

Returns contact matrix for the model.

get_serial_intervals()[source]

Returns serial intervals for the model.

get_transmissibility()[source]

Returns transmissibility vector for the model.

set_contact_matrix(contact_matrix)[source]

Updates contact matrix for the model.

Parameters:

contact_matrix – New matrix of contacts between the different categories in which the population is split.

set_serial_intervals(serial_intervals, multipleSI=False)[source]

Updates serial intervals for the model.

Parameters:

  • serial_intervals – New unnormalised probability distribution of that the recipient first displays symptoms s days after the infector first displays symptoms for each category.

  • multipleSI – (boolean) Different serial intervals used for categories.

set_transmissibility(transm)[source]

Updates transmissibility vector for the model.

Parameters:

transm – New list of overall reductions in transmissibility per category.

simulate(parameters, times, var_contacts=False, neg_binom=False, niu=0.1, interventions=None, time_interventions=None)[source]

Runs a forward simulation with the given parameters and returns a time-series with incidence numbers per population category corresponding to the given times.

Parameters:

  • parameters – Initial number of cases per population category.

  • times – The times at which to evaluate. Must be an ordered sequence, without duplicates, and without negative values. All simulations are started at time 0, regardless of whether this value appears in times.

  • var_contacts – (boolean) Wheteher there exists noise in number of contacts.

  • neg_binom – (boolean) Wheteher the noise in number of contacts is Negative Binomial distributed.

  • niu – (float) Accepance probability.

  • interventions – List of matrix multipliers describing interventions applied to reduce number of contacts.

  • time_interventions – Times of implementation of interventions to reduce contacts.

Local and Imported Multiple categories Poisson Branch Process model

class branchpro.LocImpMultiCatPoissonBranchProModel(initial_r, serial_interval, epsilon, num_cat, contact_matrix, transm, multipleSI=False)[source]

LocImpMultiCatPoissonBranchProModel Class: Class for the models following a Branching Processes behaviour with local and imported cases and Poisson distribution noise and multiple population categories. It inherits from the BranchProModel class.

In the branching process model, we track the number of cases registered for each category and each day, I_{t,i}, also known as the “incidence” at time t.

For the local & imported cases scenario, to the local incidences we add migration of cases from an external source. The conditions of this external environment may differ from the ones we are currently in through a change in the value of the R number.

To account for this difference, we assume that at all times the R number of the imported cases is proportional to the R number of the local incidences:

\[R_{t}^{\text(imported)} = \epsilon R_{t}^{\text(local)}\]

The local incidence at time t is modelled by a random variable distributed according to a negative binomial distribution with a mean that depends on previous number of cases both local and imported, according to the following formula:

\[E(I_{t, i}^{\text(local)}|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = \sum_{j}R_{t} C{i,j} T_j \sum_{s=1}^{t}I_{t-s,j}w_{s} + R_{t}^{\text(imported)}C{i,j}T_{j}\sum_{s=1}^{t} I_{t-s}^{\text(imported)}w_{s}\]

The total reproduction number at time t is computed as follows:

Always apply method set_r_profile() before calling NegBinBranchProModel.simulate() for a change of R_t profile!

Parameters:

  • initial_r – (list) List of reproduction numbers per category at the beginning of the epidemic.

  • serial_interval – (list) Unnormalised probability distribution of that the recipient first displays symptoms s days after the infector first displays symptoms for each category.

  • epsilon – (numeric) Proportionality constant of the R number for imported cases with respect to its analog for local ones.

  • num_cat – (int) Number of categories in which the population is split.

  • contact_matrix – (array) Matrix of contacts between the different categories in which the population is split.

  • transm – (list) List of overall reductions in transmissibility per category.

  • multipleSI – (boolean) Different serial intervals used for categories.

set_epsilon(new_epsilon)[source]

Updates proportionality constant of the R number for imported cases with respect to its analog for local ones.

Parameters:

new_epsilon – new value of constant of proportionality.

set_imported_cases(times, cases)[source]

Sets number of imported cases and when they occur.

Parameters:

  • times – times at which imported cases occur. Must be an ordered sequence, without duplicates, and without negative values.

  • cases – number of imported cases per category at that specified point.

simulate(parameters, times, var_contacts=False, neg_binom=False, niu=0.1, interventions=None, time_interventions=None)[source]

Runs a forward simulation with the given parameters and returns a time-series with incidence numbers per population category corresponding to the given times.

Parameters:

  • parameters – Initial number of cases per population category.

  • times – The times at which to evaluate. Must be an ordered sequence, without duplicates, and without negative values. All simulations are started at time 0, regardless of whether this value appears in times.

  • var_contacts – (boolean) Wheteher there exists noise in number of contacts.

  • neg_binom – (boolean) Wheteher the noise in number of contacts is Negative Binomial distributed.

  • niu – (float) Accepance probability.

  • interventions – List of matrix multipliers describing interventions applied to reduce number of contacts.

  • time_interventions – Times of implementation of interventions to reduce contacts.

Negative Binomial Noise Branching Process Models

Negative binomial Branch Process model

class branchpro.NegBinBranchProModel(initial_r, serial_interval, phi)[source]

NegBinBranchProModel Class: Class for the models following a Branching Processes behaviour with non-Poisson distribution noise. It inherits from the BranchProModel class.

In the branching process model, we track the number of cases registered each day, I_t, also known as the “incidence” at time t.

The incidence at time t is modelled by a random variable distributed according to a negative binomial distribution with a mean that depends on previous number of cases, according to the following formula:

\[E(I_{t}^{\text(local)}|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = R_{t}\sum_{s=1}^{t}I_{t-s}w_{s}\]

The probability mass function of the incidence at time t thus becomes:

\[P(I_{t}^{\text(local)}=k|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = \frac{\Gamma(k+\frac{1}{\phi})}{k!\Gamma(\frac{1}{\phi})} \Big(\frac{1}{1+\mu\phi}\Big)^{\frac{1}{\phi}} \Big(\frac{\mu\phi}{1+\mu\phi}\Big)^{k}\]

where \(\mu\) is mean of the distribution defined as above and \(\phi\) is the overdispersion parameter associated with the negative binomial noise distribution.

For the edge case, \(\phi = 0\), the incidence at time t becomes Poisson distributed, reducing to the simple BranchProModel class.

Always apply method set_r_profile() before calling NegBinBranchProModel.simulate() for a change of R_t profile!

Parameters:

  • initial_r – (numeric) Value of the reproduction number at the beginning of the epidemic

  • serial_interval – (list) Unnormalised probability distribution of that the recipient first displays symptoms s days after the infector first displays symptoms

  • phi – (numeric) Value of the overdispersion parameter for the negative binomial noise distribution.

get_overdispersion()[source]

Returns overdispersion noise parameter for the model.

set_overdispersion(phi)[source]

Updates overdispersion noise parameter for the model.

Parameters:

phi – New value of the overdispersion parameter for the negative binomial noise distribution.

simulate(parameters, times)[source]

Runs a forward simulation with the given parameters and returns a time-series with incidence numbers corresponding to the given times .

Parameters:

  • parameters – Initial number of cases.

  • times – The times at which to evaluate. Must be an ordered sequence, without duplicates, and without negative values. All simulations are started at time 0, regardless of whether this value appears in times.

Local and Imported negative binomial Branch Process model

class branchpro.LocImpNegBinBranchProModel(initial_r, serial_interval, epsilon, phi)[source]

LocImpNegBinBranchProModel Class: Class for the models following a Branching Processes behaviour with local and imported cases and non-Poisson distribution noise. It inherits from the NegBinBranchProModel class.

In the branching process model, we track the number of cases registered each day, I_t, also known as the “incidence” at time t.

For the local & imported cases scenario, to the local incidences we add migration of cases from an external source. The conditions of this external environment may differ from the ones we are currently in through a change in the value of the R number.

To account for this difference, we assume that at all times the R number of the imported cases is proportional to the R number of the local incidences:

\[R_{t}^{\text(imported)} = \epsilon R_{t}^{\text(local)}\]

The local incidence at time t is modelled by a random variable distributed according to a negative binomial distribution with a mean that depends on previous number of cases both local and imported, according to the following formula:

\[E(I_{t}^{\text(local)}|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = R_{t}^{\text(local)}\sum_{s=1}^{t}I_{t-s}^{\text(local)}w_{s} + R_{t}^{\text(imported)}\sum_{s=1}^{t}I_{t-s}^{\text(imported)}w_{s}\]

The probability mass function of the incidence at time t thus becomes:

\[P(I_{t}^{\text(local)}=k|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = \frac{\Gamma(k+\frac{1}{\phi})}{k!\Gamma(\frac{1}{\phi})} \Big(\frac{1}{1+\mu\phi}\Big)^{\frac{1}{\phi}} \Big(\frac{\mu\phi}{1+\mu\phi}\Big)^{k}\]

where \(\mu\) is mean of the distribution defined as above and \(\phi\) is the overdispersion parameter associated with the negative binomial noise distribution.

For the edge case, \(\phi = 0\), the incidence at time t becomes Poisson distributed, reducing to the simple LocImpBranchProModel class.

Always apply methods set_r_profile() and set_imported_cases() before calling LocImpNegBinBranchProModel.simulate() for a change of R_t profile and for loading the imported cases data!

Parameters:

  • initial_r – (numeric) Value of the reproduction number at the beginning of the epidemic

  • serial_interval – (list) Unnormalised probability distribution of that the recipient first displays symptoms s days after the infector first displays symptoms

  • epsilon – (numeric) Proportionality constant of the R number for imported cases with respect to its analog for local ones

  • phi – (numeric) Value of the overdispersion parameter for the negative binomial noise distribution.

get_overdispersion()[source]

Returns overdispersion noise parameter for the model.

set_overdispersion(phi)[source]

Updates overdispersion noise parameter for the model.

Parameters:

phi – New value of the overdispersion parameter for the negative binomial noise distribution.

simulate(parameters, times)[source]

Runs a forward simulation with the given parameters and returns a time-series with incidence numbers corresponding to the given times .

Parameters:

  • parameters – Initial number of cases.

  • times – The times at which to evaluate. Must be an ordered sequence, without duplicates, and without negative values. All simulations are started at time 0, regardless of whether this value appears in times.

Stochastic Negative binomial Branch Process model

class branchpro.StochasticNegBinBranchProModel(initial_r, serial_interval, phi)[source]

NegBinBranchProModel Class: Class for the models following a Branching Processes behaviour with non-Poisson distribution noise and individual variation in the reproduction number. It inherits from the NegBinBranchProModel class.

In the branching process model, we track the number of cases registered each day, I_t, also known as the “incidence” at time t.

The incidence at time t is modelled by a random variable distributed according to a negative binomial distribution with a mean that depends on previous number of cases, according to the following formula:

\[E(I_{t}^{\text(local)}|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = R_{t}\sum_{s=1}^{t}I_{t-s}w_{s}\]

The probability mass function of the incidence at time t thus becomes:

\[P(I_{t}^{\text(local)}=k|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = \frac{\Gamma(k+\frac{1}{\phi})}{k!\Gamma(\frac{1}{\phi})} \Big(\frac{1}{1+\mu\phi}\Big)^{\frac{1}{\phi}} \Big(\frac{\mu\phi}{1+\mu\phi}\Big)^{k}\]

where \(\mu\) is mean of the distribution defined as above and \(\phi\) is the overdispersion parameter associated with the negative binomial noise distribution.

For the edge case, \(\phi = 0\), the incidence at time t becomes Poisson distributed, reducing to the simple BranchProModel class.

Always apply method set_r_profile() before calling NegBinBranchProModel.simulate() for a change of R_t profile!

Parameters:

  • initial_r – (numeric) Value of the reproduction number at the beginning of the epidemic

  • serial_interval – (list) Unnormalised probability distribution of that the recipient first displays symptoms s days after the infector first displays symptoms

  • phi – (numeric) Value of the overdispersion parameter for the negative binomial noise distribution.

simulate(parameters, times)[source]

Runs a forward simulation with the given parameters and returns a time-series with incidence numbers corresponding to the given times .

Parameters:

  • parameters – Initial number of cases.

  • times – The times at which to evaluate. Must be an ordered sequence, without duplicates, and without negative values. All simulations are started at time 0, regardless of whether this value appears in times.

Local and Imported Stochastic negative binomial Branch Process model

class branchpro.StochasticLocImpNegBinBranchProModel(initial_r, serial_interval, epsilon, phi)[source]

StochasticLocImpNegBinBranchProModel Class: Class for the models following a Branching Processes behaviour with local and imported cases, non-Poisson distribution noise and individual variation in the reproduction number. It inherits from the LocImpNegBinBranchProModel class.

In the branching process model, we track the number of cases registered each day, I_t, also known as the “incidence” at time t.

For the local & imported cases scenario, to the local incidences we add migration of cases from an external source. The conditions of this external environment may differ from the ones we are currently in through a change in the value of the R number.

To account for this difference, we assume that at all times the R number of the imported cases is proportional to the R number of the local incidences:

\[R_{t}^{\text(imported)} = \epsilon R_{t}^{\text(local)}\]

The local incidence at time t is modelled by a random variable distributed according to a negative binomial distribution with a mean that depends on previous number of cases both local and imported, according to the following formula:

\[E(I_{t}^{\text(local)}|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = R_{t}^{\text(local)}\sum_{s=1}^{t}I_{t-s}^{\text(local)}w_{s} + R_{t}^{\text(imported)}\sum_{s=1}^{t}I_{t-s}^{\text(imported)}w_{s}\]

The probability mass function of the incidence at time t thus becomes:

\[P(I_{t}^{\text(local)}=k|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = \frac{\Gamma(k+\frac{1}{\phi})}{k!\Gamma(\frac{1}{\phi})} \Big(\frac{1}{1+\mu\phi}\Big)^{\frac{1}{\phi}} \Big(\frac{\mu\phi}{1+\mu\phi}\Big)^{k}\]

where \(\mu\) is mean of the distribution defined as above and \(\phi\) is the overdispersion parameter associated with the negative binomial noise distribution.

For the edge case, \(\phi = 0\), the incidence at time t becomes Poisson distributed, reducing to the simple LocImpBranchProModel class.

Always apply methods set_r_profile() and set_imported_cases() before calling LocImpNegBinBranchProModel.simulate() for a change of R_t profile and for loading the imported cases data!

Parameters:

  • initial_r – (numeric) Value of the reproduction number at the beginning of the epidemic

  • serial_interval – (list) Unnormalised probability distribution of that the recipient first displays symptoms s days after the infector first displays symptoms

  • epsilon – (numeric) Proportionality constant of the R number for imported cases with respect to its analog for local ones

  • phi – (numeric) Value of the overdispersion parameter for the negative binomial noise distribution.

simulate(parameters, times)[source]

Runs a forward simulation with the given parameters and returns a time-series with incidence numbers corresponding to the given times .

Parameters:

  • parameters – Initial number of cases.

  • times – The times at which to evaluate. Must be an ordered sequence, without duplicates, and without negative values. All simulations are started at time 0, regardless of whether this value appears in times.

Poisson-Binomial Noise Branching Process Models

Poisson-Binomial Branch Process model

class branchpro.PoiBinBranchProModel(initial_mu, next_gen)[source]

PoiBinBranchProModel Class: Class for the models following a Branching Processes behaviour with Poisson distribution noise and multiple population categories. It inherits from the BranchProModel class.

In the branching process model, we track the number of cases registered for each category and each day, I_{t,i}, also known as the “incidence” at time t.

The incidence at time t is modelled by a random variable distributed according to a Poisson distribution with a mean that depends on previous number of cases, according to the following formula:

\[E(I_{t, i}^{\text(local)}|I_0, I_1, \dots I_{t-1}, w_{s}, R_{t}) = \sum_{j}R_{t, j}\sum_{s=1}^{t}I_{t-s,j}w_{s}\]

The total reproduction number at time t is computed as follows:

\[R_{t} = \sum_{j}R_{t, j}\]

Always apply method set_r_profile() before calling NegBinBranchProModel.simulate() for a change of R_t profile!

Parameters:

  • initial_mu – (numeric) Value of the mean number of contacts of an individual at the beginning of the epidemic.

  • next_gen – (list) Unnormalised probability distribution of that the infector infects a contact s days after they first displays symptoms.

get_mean_contact()[source]

Returns the profile of the time-dependent mean number of contacts of an individual for the model.

get_next_gen()[source]

Returns next generation probability distribution for the model.

set_mean_contact(new_mus, start_times, last_time=None)[source]

Creates a new profile of the time-dependent mean number of contacts of an individual for the model.

Parameters:

  • new_mus – sequence of new time-dependent values of the mean number of contacts of an individual.

  • start_times – sequence of the first time unit when the corresponding indexed value of mu_t in new_mus is used. Must be an ordered sequence and without duplicates or negative values.

  • last_time – total evaluation time; optional.

set_next_gen(new_next_gen)[source]

Updates next generation probability distribution for the model.

Parameters:

new_next_gen – New unnormalised probability distribution of that the infector infects a contact s days after they first displays symptoms

simulate(parameters, times)[source]

Runs a forward simulation with the given parameters and returns a time-series with incidence numbers per population category corresponding to the given times.

Parameters:

  • parameters – Initial number of cases per population category.

  • times – The times at which to evaluate. Must be an ordered sequence, without duplicates, and without negative values. All simulations are started at time 0, regardless of whether this value appears in times.