Setup Matrices¶
This page contains information about the different classes used for setting up regional and contact matrices for the models included in epimodels.
Overview:
Contact Population Matrix¶
- class epimodels.ContactMatrix(age_groups, data_matrix)[source]¶
ContactMatrix Class: Base class for constructing a contact matrix to be used in the modelling of epidemics. These matrices indicate the number of people a person in a given age group (\(i\)) will interact on average with people in a different age group (\(j\)) at a given time point (\(t_k\)).
\[C^{t_k} = \{C_{ij}^{t_k}\}\]- Parameters:
age_groups (list) – List of the different age intervals according to which the population is split when constructing the contact matrix.
data_matrix (numpy.array) – Data matrix which will populate the contact matrix. Element \((i, j)\) represents the average number of people in age group \(j\) a person in age group \(i\) interact with.
- change_age_groups(new_age_groups)[source]¶
Modifies current age structure of the contact matrix.
- Parameters:
new_age_groups (list) – List of the new age intervals according to which the population is split when constructing the contact matrix.
Region-specific Susceptibility Matrix¶
- class epimodels.RegionMatrix(region_name, age_groups, data_matrix)[source]¶
RegionMatrix Class: Base class for constructing a region matrix to be used in the modelling of epidemics. These matrices indicate the region-specific relative susceptibility of someone in a given age group (\(i\)) will get infected from somebody else in a different age group (\(j\)) at a given time point (\(t_k\)), assuming contact.
\[M_{r}^{t_k} = \{M_{r, ij}^{t_k}\}\]- Parameters:
region_name (str) – Name of the region to which the region matrix refers to.
age_groups (list) – List of the different age intervals according to which the population is split when constructing the region matrix.
data_matrix (numpy.array) – Data array which will populate the region matrix. Element \((i, j)\) represents the relative susceptibility of someone in age group \(j\) to be infected by a person in age group \(i\), if they come into contact.
- change_age_groups(new_age_groups)[source]¶
Modifies current age structure of the contact matrix.
- Parameters:
new_age_groups (list) – List of the new age intervals according to which the population is split when constructing the contact matrix.
Mono Time&Region-specific New Infections Matrix¶
- class epimodels.UniNextGenMatrix(pop_size, contact_matrix, region_matrix, dI)[source]¶
Class for generator matrices. They are used to determine the evolution of number of infectives as time goes on according to the following formulae, at fixed time \(t_k\) and in specific region \(r\):
\begin{eqnarray} \Lambda_{k, r} & = & (\Lambda_{k, r, ij}) \\ \widetilde{C}_{r, ij}^{t_k} & = & C_{ij}^{t_k} M_{r, ij}^{t_k} \\ \Lambda_{k, r, ij} & = & S_{r, t_k, i} \widetilde{C}_{r, ij}^{t_k} d_{I} \end{eqnarray}- Parameters:
pop_size (list) – List of number of susceptibles in the population, split according to their corresponding age group.
contact_matrix (ContactMatrix) – Matrix which encodes the expected number of contacts in different age groups a person can have, dependent of which age group they falls into.
region_matrix (RegionMatrix) – Matrix which encodes the relative susceptibility to infection a person can have, depending of which age group they falls into, if they come into contact with people from various age groups.
dI (float) – Average duration of infection.
Multi Time&Region-specific Contact Matrix¶
- class epimodels.MultiTimesContacts(matrices_contact, time_changes_contact, regions, matrices_region, time_changes_region)[source]¶
MultiTimesContacts Class: Base class for storing the contact matrices for the population at multiple time points.
- Parameters:
matrices_contact (list of ContactMatrix) – Time-dependent contact matrices used for the modelling.
time_changes_contact (list) – Times at which the next contact matrix recorded starts to be used. In increasing order. Start with 1.
regions (list) – List of region names for the region-specific relative susceptibility matrices.
matrices_region (list of lists of RegionMatrix) – Time-dependent and region-specific relative susceptibility matrices used for the modelling.
time_changes_region (list) – Times at which the next instances of region-specific relative susceptibility matrices recorded start to be used. In increasing order. Start with 1.
- identify_current_contacts(r, t_k)[source]¶
Computes the current regional contact matrices at a specified time point and region. Element \((i, j)\) refers to the expected number of new infections in age group \(i\) caused by an infectious in age group \(j\).
- Parameters:
r (int) – Index of the region at which the regional contact matrix is evaluated.
t_k (int or float) – Time of evaluation of the regional contact matrix.
- Returns:
Unnormalised next generation matrix.
- Return type:
numpy.array
Mono Time&Region-specific Infectivity Matrix and Reproduction Number Computer¶
- class epimodels.UniInfectivityMatrix(initial_r, initial_nextgen_matrix)[source]¶
UniInfectivityMatrix Class: Base class to compute the probability of susceptible individuals in a given region and specified time point of getting infected as well as the reproduction number for subsequent time points.
Both quantities are computed using \(\beta_{t_k, r}\), which is the further temporal correction term, linked to fluctuations in transmission, the initial reproduction number in region \(r\) \(R_{0, r}\) and the dominant eigenvalue of the initial next generation matrix for region \(r\) \(R^{\star}_{0, r}\).
- Parameters:
initial_r (float) – Initial value of the reproduction number in the specified region.
initial_nextgen_matrix (UniNextGenMatrix) – Next generation matrix at time of beginning of the epidemic.
- compute_prob_infectivity_matrix(temp_variation, later_nextgen_matrix)[source]¶
Computes the matrix of probabilities of susceptible individuals in a given region and specified time point of getting infected. The \((i, j)\) element of the matrix refers to the probability of people in age group \(i\) to be infected by those in age group \(j\).
The matrix is computed using this formula:
\[b^{t_k}_{r, ij} = \beta_{t_k, r} R_{0, r} \frac{ \widetilde{C}_{r, ij}^{t_k}}{R^{\star}_{0, r}}\]where \(\beta_{t_k, r}\) is the further temporal correction term, linked to fluctuations in transmission, \(R_{0, r}\) is the initial reproduction number in region \(r\) and \(R^{\star}_{0, r}\) is the dominant eigenvalue of the initial next generation matrix for region \(r\).
- Parameters:
temp_variation (float) – Further temporal correction term, linked to fluctuations in transmission.
later_nextgen_matrix (UniNextGenMatrix) – Next generation matrix at given time during the epidemic.
- Returns:
Probability matrix of susceptible individuals in a given region and specified time point of getting infected.
- Return type:
numpy.array
- compute_reproduction_number(temp_variation, later_nextgen_matrix)[source]¶
Computes the reproduction number in a given region and at a specified timepoint of getting infected. The reproduction number is computed using this formula:
\[R_{t_k, r} = \beta_{t_k, r} R_{0, r} \frac{ R^{\star}_{t_k, r}}{R^{\star}_{0, r}}\]where \(\beta_{t_k, r}\) is the further temporal correction term, linked to fluctuations in transmission, \(R_{0, r}\) is the initial reproduction number in region \(r\) and \(R^{\star}_{0, r}\) is the dominant eigenvalue of the initial next generation matrix for region \(r\).
The \(R^{\star}_{t_k, r}\) is the dominant eigenvalue of the current time next generation matrix for region \(r\):
\[\Lambda_{k, r, ij} = S_{r, t_k, i} \widetilde{C}_{r, ij}^{t_k} d_{I}\]- Parameters:
temp_variation (float) – Further temporal correction term, linked to fluctuations in transmission.
later_nextgen_matrix (UniNextGenMatrix) – Next generation matrix at given time during the epidemic.
- Returns:
Reproduction number in a given region and at a specified timepoint.
- Return type:
int or float
Multi Time&Region-specific Infectivity Matrix and Reproduction Number Computer¶
- class epimodels.MultiTimesInfectivity(matrices_contact, time_changes_contact, regions, matrices_region, time_changes_region, initial_r, dI, susceptibles)[source]¶
MultiTimesInfectivity Class: Base class to compute the probabilities of susceptible individuals in a given region and specified time point of getting infected as well as the reproduction number for subsequent time points, evaluating at multiple time points and in multiple regions.
In the computation of both quantities time-dependent progressions of contact matrices and region matrices, accompanied by vectors of the times at which the changes occur.
- Parameters:
matrices_contact (list of ContactMatrix) – Time-dependent contact matrices used for the modelling.
time_changes_contact (list) – Times at which the next contact matrix recorded starts to be used. In increasing order. Start with 1.
regions (list) – List of region names for the region-specific relative susceptibility matrices.
matrices_region (list of lists of RegionMatrix) – Time-dependent and region-specific relative susceptibility matrices used for the modelling.
time_changes_region (list) – Times at which the next instances of region-specific relative susceptibility matrices recorded start to be used. In increasing order. Start with 1.
initial_r (list) – List of initial values of the reproduction number by region.
dI (float) – Average duration of infection.
susceptibles (numpy.array) – Matrix of initial number of susceptibles by region and age-group.
- compute_prob_infectivity_matrix(r, t_k, susceptibles, temp_variation=1)[source]¶
Computes the matrix of probabilities of susceptible individuals in a given region and specified time point of getting infected. The \((i, j)\) element of the matrix refer to the probability of people in age group \(i\) to be infected by those in age group \(j\).
The matrix is computed using this formula:
\[b^{t_k}_{r, ij} = \beta_{t_k, r} R_{0, r} \frac{ \widetilde{C}_{r, ij}^{t_k}}{R^{\star}_{0, r}}\]where \(\beta_{t_k, r}\) is the further temporal correction term, linked to fluctuations in transmission, \(R_{0, r}\) is the initial reproduction number in region \(r\) and \(R^{\star}_{0, r}\) is the dominant eigenvalue of the initial next generation matrix for region \(r\).
- Parameters:
r (int) – Index of the region at which the next generation matrix is evaluated.
t_k (int or float) – Time at which the next generation matrix is evaluated.
temp_variation (int or float) – Further temporal correction term, linked to fluctuations in transmission.
susceptibles (numpy.array) – Matrix of current number of susceptibles by region and age-group.
- Returns:
Probability matrix of susceptible individuals in a given region and specified time point of getting infected.
- Return type:
numpy.array
- compute_reproduction_number(r, t_k, susceptibles, temp_variation=1)[source]¶
Computes the reproduction number in a given region and at a specified timepoint of getting infected. The reproduction number is computed using this formula:
\[R_{t_k, r} = \beta_{t_k, r} R_{0, r} \frac{ R^{\star}_{t_k, r}}{R^{\star}_{0, r}}\]where \(\beta_{t_k, r}\) is the further temporal correction term, linked to fluctuations in transmission, \(R_{0, r}\) is the initial reproduction number in region \(r\) and \(R^{\star}_{0, r}\) is the dominant eigenvalue of the initial next generation matrix for region \(r\).
The \(R^{\star}_{t_k, r}\) is the dominant eigenvalue of the current time next generation matrix for region \(r\):
\[\Lambda_{k, r, ij} = S_{r, t_k, i} \widetilde{C}_{r, ij}^{t_k} d_{I}\]- Parameters:
r (int) – Index of the region at which the next generation matrix is evaluated.
t_k (int or float) – Time at which the next generation matrix is evaluated.
temp_variation (int or float) – Further temporal correction term, linked to fluctuations in transmission.
susceptibles (numpy.array) – Matrix of current number of susceptibles by region and age-group.
- Returns:
Reproduction number in a given region and at a specified timepoint.
- Return type:
int or float