Contacts

AgeBasedContactSampling <: ContactSamplingMethod

Sample random contacts based on a Poissoin-Distribution spread around contactparameter_sampling.contactparameter with weighted sampling based on age distance. We sample according to formula pi = e * wi * qi * mi / N where e - expected number of contacts, wi - normalization factor, qi - age group probability based on the age pyramid, mi - mixing factor between age groups, N - number of agents Normalization factor is required to normalize the sampling ditribution in order to get expected number of contacts in the end. We use two fold approach. Firstly, we sample uniformly with probability pi = e * wi * qi * mmax / N mmax - maximal mixing factor between age groups Secondly, we sample with adapted probability mi = mi / m_max

Parameters

• contactparameter::Float64: Expected value of a Poisson-Distribution used to draw the number of contacts
• contact_matrix_file::String: String path to a file with an NxN contact probability matrix
• interval::Int64: Year-intervals of contact matrix (e.g., 5 means, the data contains age-age-couplings for 5-year age groups)

AgeContactDistribution

Wrapper for a 'Age x Age Contact Distribution'.

Attributes

• distribution_data::Vector{Int64}: Vector containing the numbers of contacts from each individual of ego_age with individuals of age contact_age.
• ego_age::Int8: Age of the "Ego" individual.
• contact_age::Int8: Age of the "Contact" individual

AgeGroupContactDistribution

Wrapper for a 'AgeGroup x AgeGroup Contact Distribution'.

Attributes

• distribution_data::Vector{Int64}: Vector containing the numbers of contacts from each individual of ego_age_group with individuals of contact_age_group.
• ego_age_group::Tuple{Int8, Int8}: Lower and Upper bound of the Age Group of "Ego" individuals. The upper bound is excluded (ego_age_group=(0,5) corresponds to the ages 0 till 4).
• contact_age_group::Tuple{Int8, Int8}: Lower and Upper bound of the Age Group of "Contact" individuals. The upper bound is excluded (ego_age_group=(0,5) corresponds to the ages 0 till 4).

ContactMatrix{T <: Number}

Interface for epidemiologic contact matrices. Contact Matrices are important for simulation models of infectious diseases, as they contain information about contact behavior of individuals inside a population. Contact matrices are symmetric matrices that show the aggregated number of contacts of individuals. The aggregation of ContactMatrix in GEMS is "by age". By providing interval_steps = 1, the matrix isn't aggregated and represents contacts between two ages.

Fields

• data::Matrix{T}: Raw data of the contact matrix. Each cell has to represent an age group with the same step size as interval_steps
• interval_steps::Int64: Steps size of each age group
• aggregation_bound::Int64: Maximum age up to which the contact matrix is aggregated. This is often used if the last age group is smaller than interval_steps. This parameter is optional.
• _size::Int64: Internal attribute. Defines the size of one matrix dimension.

Example

In this example, we create a 3x3 matrix where each column/row represents an age group of 10 but the last age group only goes until 26 (these numbers are made up!), so we cap it at 20 (see "[0-10), [10-20), 20+").

Here [1 4 7] represent age group [0-10), [2 5 8] age group [10-20) and [3 6 9] age group 20+.

julia> matrix = [1 2 3; 4 5 6; 7 8 9]
3×3 Matrix{Int64}:
 1  2  3
 4  5  6
 7  8  9

julia> ContactMatrix{Int64}(matrix, 10, 20)
ContactMatrix{Int64}([1 2 3; 4 5 6; 7 8 9], 10, 20, 3)

ContactSamplingMethod

Supertype for all contact sampling methods. This type is intended to be extended by providing different sampling methods suitable for the structure of the simulation model.

ContactparameterSampling <: ContactSamplingMethod

Sample random contacts based on a Poisson-Distribution spread around contactparameter. If provided with no parameter, 0 contacts are assumed.

RandomSampling <: ContactSamplingMethod

Sample exactly one contact per individual inside a Setting. The sampling will be random.

AgeContactDistribution(distribution_data::Vector{Int64}, ego_age::Int8, contact_age::Int8)

Default constructor for AgeContactDistribution.

Parameters

• distribution_data::Vector{Int64}: Vector containing the numbers of contacts from each individual of ego_age with individuals of age contact_age.
• ego_age::Int8: Age of the "Ego" individual.
• contact_age::Int8: Age of the "Contact" individual

AgeGroupContactDistribution(distribution_data::Vector{Int64}, ego_age_group::Tuple{Int8, Int8}, contact_age_group::Tuple{Int8, Int8})

Default constructor for AgeGroupContactDistribution.

Parameters

• distribution_data::Vector{Int64}: Vector containing the numbers of contacts from each individual of ego_age_group with individuals of contact_age_group.
• ego_age_group::Tuple{Int8, Int8}: Lower and Upper bound of the Age Group of "Ego" individuals. The upper bound is excluded (ego_age_group=(0,5) corresponds to the ages 0 till 4).
• contact_age_group::Tuple{Int8, Int8}: Lower and Upper bound of the Age Group of "Contact" individuals. The upper bound is excluded (contact_age_group=(0,5) corresponds to the ages 0 till 4).

aggregate_matrix(matrix::Matrix, interval_steps::Int64)

Calculate an aggregated matrix by providing the length of the interval to aggregate. Each interval will have the same length. If the dimension of the given matrix isn't divisible by interval_steps, the last interval will contain the rest of the values (this causes the last interval to be shorter than every other interval).

Assumptions:

• The input matrix has to be of shape n x n, where n is an Int64.

Example:

julia> matrix = [1 1  2 2 3 ; 1 1  2 2 3 ; 3 3 4 4 3; 3 3 4 4 3; 3 3 3 3 3]
5×5 Matrix{Int64}:
 1  1  2  2  3
 1  1  2  2  3
 3  3  4  4  3
 3  3  4  4  3
 3  3  3  3  3

julia> aggregate_matrix(matrix,2) # intervals would be [1:3), [3:5), [5:5]
3×3 Matrix{Int64}:
  4   8  6
 12  16  6
  6   6  3

aggregate_matrix(vector::Vector, interval_steps::Int64)::Matrix

Aggregate values in a Vector by a given interval (defined by interval_steps). If the dimension of the given Vector isn't divisible by interval_steps, the last interval will contain the rest of the values (this causes the last interval to be shorter than every other interval).

Example

julia> vector = [1, 1, 8, 5, 3]
5-element Vector{Int64}:
 1
 1
 8
 5
 3

# intervals would be [1:3), [3:5), [5:5]
julia> aggregate_matrix(vector,2)
3×1 Matrix{Int64}:
  2
 13
  3

aggregate_matrix(matrix::Matrix, interval_steps::Int64, aggregation_bound::Int64)

Aggregate values in a matrix by a given interval (defined by interval_steps). aggregation_bound sets a upper boundary. In the interval [1:aggregation_bound), values are aggregated in sub-intervals defined by interval_steps. In the interval [aggregation_bound:length(matrix[1,:])] all values will be summed up.

Assumptions:

• The input matrix has to be of shape n x n, where n is an Int64.

Example:

julia> matrix = [1 1  2 2 3 ; 1 1  2 2 3 ; 3 3 4 4 3; 3 3 4 4 3; 3 3 3 3 3]
5×5 Matrix{Int64}:
 1  1  2  2  3
 1  1  2  2  3
 3  3  4  4  3
 3  3  4  4  3
 3  3  3  3  3

# intervals would be [1:3), 3+
julia> aggregate_matrix(matrix, 2, 3)
2×2 Matrix{Int64}:
  4  14
 18  31

aggregate_matrix(vector::Vector, interval_steps::Int64, aggregation_bound::Int64)::Matrix

Aggregate values in a Vector by a given interval (defined by interval_steps). aggregation_bound sets a upper boundary. In the interval [1:aggregation_bound), values are aggregated in sub-intervals, defined by interval_steps. In the interval [aggregation_bound:length(vector)] all values will be summed up.

Example

julia> vector = [1, 1, 8, 5, 3, 5, 8, 7 ,9]
9-element Vector{Int64}:
 1
 1
 8
 5
 3
 5
 8
 7
 9

# intervals would be [1:3), [3:5), 5+
julia> aggregate_matrix(vector, 2, 5)
3×1 Matrix{Int64}:
  2
 13
 32

aggregated_setting_age_contacts(rd::ResultData)

Returns an age group X age group contact matrix for the specified settingtype (e.g. Households) based on sampled data Returns an empty dictionary if the data is not available in the input ResultData object.

aggregated_setting_age_contacts(rd::ResultData, settingtype::DataType)

Returns an age group X age group contact matrix for the specified settingtype (e.g. Households) based on sampled data Returns an empty dictionary if the data is not available in the input ResultData object.

Utitility function. Calculates the number of contacts an individuals in the age group ego_age_group have with individuals in the age group contact_age_group. Each entry is the number of contacts one individual in the age group ego_age_group has with individuals in the age group contact_age_group.

Parameters

• contactdata: DataFrame containing data about contacts between an 'ego' and a 'contact'.
• ego_age_group::Tuple{Int,Int}: Defines the age interval that should be aggregated for the "ego age group". The upper age bound (the second entry of the Tuple) will be excluded like "[egolowerbound, egoupperbound)"
• contact_age_group::Tuple{Int,Int}: Defines the age interval that should be aggregated for the "contact age group". The upper age bound (the second entry of the Tuple) will be excluded like "[contactlowerbound, contactupperbound)"
• ego_id_column: Index indicating which column of contactdata stores information about each ego's id.
• ego_age_column: Index indicating which column of contactdata stores information about each ego's age.
• contact_age_column: Index indicating which column of contactdata stores information about each contact's age.

Utitility function. Calculates the number of contacts an individual of age ego_age has with an individual of age contact_age. Each entry is the number of contacts one individual of age ego_age has.

Parameters

• contactdata: DataFrame containing data about contacts between an 'ego' and a 'contact'.
• ego_age: Age of the 'Ego', that should be included in this distribution.
• contact_age: Age of the 'Contact', that should be included in this distribution.
• ego_id_column: Index indicating which column of contactdata stores information about each ego's id.
• ego_age_column: Index indicating which column of contactdata stores information about each ego's age.
• contact_age_column: Index indicating which column of contactdata stores information about each contact's age.

Utitility function. Get how many individuals of a specific age have no contact. An Individiual with no contact, has an entry in contactdata where the columns for data about the contact are "-1".

Parameters

• contactdata: DataFrame containing data about contacts between an 'ego' and a 'contact'.
• ego_age: Age of the 'Ego', that should be included in this distribution.
• ego_id_column: Index indicating which column of contactdata stores information about each ego's id.
• ego_age_column: Index indicating which column of contactdata stores information about each ego's age.
• contact_age_column: Index indicating which column of contactdata stores information about each contact's age.

ContactMatrix{T}(data::Matrix{T}, interval_steps::Int64, aggregation_bound::Union{Int64, Nothing}) where T <: Number

Create a ContactMatrix with interval_steps and aggregation_bound. _size will be derived from data.

ContactMatrix{T}(data::Matrix{T}, interval_steps::Int64) where T <: Number

Create a ContactMatrix with interval_steps. _size will be derived from data.

contact_samples(simulation::Simulation, settingtype::Type{T}, include_non_contacts::Bool)::DataFrame  where {T <: Setting}

Returns a dataframe with data on two individuals per row (contact). The contacts are sampled for a provided setting type according to the ContactSamplingMethod of the desired setting. This also defines, how many contacts will be sampled per individual. If include_non_contacts is true, also the number of "non-contacts" (individuals for which the number of sampled contacts is zero) will be included in this dataframe. In this case, b_id, b_age and b_sex will have the value -1. The number of sampled contacts is limited by the global CONTACT_SAMPLES flag in the constants.jl file. It default is 100_000. If you need more samples, change the flag using GEMS.CONTACT_SAMPLES = your_new_int_value.

Columns

Returns

Dataframe containing the sampled contacts for the given settingstype.

If no settings exist for settingtype, an empty DataFrame with the Columns defined above is returned.

If no contacts are sampled in GEMS.CONTACT_SAMPLES many iterations, an empty DataFrame with the Columns defined above is returned.

get_ageGroup_contact_distribution(contact_distribution_matrix::Matrix{AgeContactDistribution}; ego_age_group::Tuple{Int,Int}, contact_age_group::Tuple{Int,Int})::AgeGroupContactDistribution

Aggregates a number of 'Age x Age Contact Distribution's to one new 'AgeGroup x AgeGroup Contact Distribution'.

Parameters

• contact_distribution_matrix::Matrix: Contains "Age x Age Contact Distributions".
• ego_age_group::Tuple{Int,Int}: Defines the age interval that should be aggregated for the "ego age group". The upper age bound (the second entry of the Tuple) will be excluded like "[ego_lower_bound, ego_upper_bound)"
• contact_age_group::Tuple{Int,Int}: Defines the age interval that should be aggregated for the "contact age group". The upper age bound (the second entry of the Tuple) will be excluded like "[contact_lower_bound, contact_upper_bound)"

Returns

'AgeGroup x AgeGroup Contact Distribution'

get_ageGroup_contact_distribution(contactdata::DataFrame; ego_age_group::Tuple{Int,Int}, contact_age_group::Tuple{Int,Int}, ego_id_column::Int64, ego_age_column::Int64, contact_age_column::Int64)::AgeGroupContactDistribution

Calculate a 'AgeGroup x AgeGroup' contact distribution for two given age groups defined by ego_age_group and contact_age_group. The correct columns of the input dataframes can be defined by ego_id_column, ego_age_column and contact_age_column.

The dataframe must contain data of a (artificial) contact survey, where each row represents a contact between two individuals.

Parameters

• contactdata: DataFrame containing data about contacts between a 'ego' and 'contacts'.
• ego_age_group::Tuple{Int,Int}: Defines the age interval that should be aggregated for the "ego age group". The upper age bound (the second entry of the Tuple) will be excluded like "[ego_lower_bound, ego_upper_bound)"
• contact_age_group::Tuple{Int,Int}: Defines the age interval that should be aggregated for the "contact age group". The upper age bound (the second entry of the Tuple) will be excluded like "[contact_lower_bound, contact_upper_bound)"
• ego_id_column::Int64: Index indicating which column of contactdata stores information about each ego's id.
• ego_age_column::Int64: Index indicating which column of contactdata stores information about each ego's age.
• contact_age_column::Int64: Index indicating which column of contactdata stores information about each contact's age.

Returns

'AgeGroup x AgeGroup Contact Distribution'

get_age_contact_distribution(contactdata::DataFrame; ego_age::Int64, contact_age::Int64, ego_id_column::Int64, ego_age_column::Int64, contact_age_column::Int64)::AgeContactDistribution

Calculate a 'Age x Age' contact distribution for two given ages defined by ego_age and contact_age. The correct columns of the input dataframes can be defined by ego_id_column, ego_age_column and contact_age_column.

The dataframe must contain data of a (artificial) contact survey, where each row represents a contact between two individuals.

Parameters

• contactdata: DataFrame containing data about contacts between an 'ego' and a 'contact'.
• ego_age: Age of the 'Ego', that should be included in this distribution.
• contact_age: Age of the 'Contact', that should be included in this distribution.
• ego_id_column: Index indicating which column of contactdata stores information about each ego's id.
• ego_age_column: Index indicating which column of contactdata stores information about each ego's age.
• contact_age_column: Index indicating which column of contactdata stores information about each contact's age.

Returns

A Distribution of contacts between individuals of age "Ego Age" and "Contact Age"

get_age_contact_distribution_matrix(contactdata::DataFrame)::Matrix{AgeContactDistribution}

Create a matrix of contact distributions between individuals of two ages until a given maximum age maxage.

get_contacts(contact_matrix::ContactMatrix{T}, individual::Individual)::T where T <: Number

Get the number of contacts an Individual has, based on its age and an associated contact matrix containing the numbers of contacts per age group.

The number of contacts is based on a vector of contacts an individual of the age group of individual would have. The concrete number of contacts is then derived by taking the mean of this vector.

membership_changed!(csm::ContactSamplingMethod, setting::Setting)

Signals that setting's member list changed, so a sampling method can drop state derived from it. Called by add! and remove!. No-op by default.

membership_changed!(csm::AgeBasedContactSampling, setting::Setting)

Drops the cached age pyramid; sample_contacts! refills it lazily.

sample_contacts!(indivs::Vector{Individual}, contact_sampling_method::ContactSamplingMethod, setting::Setting, individual_index::Int, present_inds::Vector{Individual}, tick::Int16, replace::Bool, rng::Xoshiro)

Fallback: determine which keyword-based method  a user defined (mutating or non-mutating) and routes the internal positional call accordingly.

sample_contacts!(indivs::Vector{Individual}, random_sampling_method::RandomSampling, setting::Setting, individual_index::Int, present_inds::Vector{Individual}, tick::Int16, replace::Bool, rng::Xoshiro)

Sample exactly 1 random contact from the individuals in setting. The indivs buffer is expected to be empty on entry and will be filled with the sampled contacts in-place.

sample_contacts!(indivs::Vector{Individual}, contactparameter_sampling::ContactparameterSampling, setting::Setting, individual_index::Int, present_inds::Vector{Individual}, tick::Int16, replace::Bool, rng::Xoshiro)

Sample random contacts based on a Poisson-Distribution spread around contactparameter_sampling.contactparameter. The replace parameter determines whether contacts are sampled with replacement (true) or without replacement (false). The indivs buffer is expected to be empty on entry and will be filled with the sampled contacts in-place.

sample_contacts!(indivs::Vector{Individual}, contactparameter_sampling::AgeBasedContactSampling, setting::Setting, individual_index::Int, present_inds::Vector{Individual}, tick::Int16, replace::Bool, rng::Xoshiro)

Sample random contacts based on a spread around contactparameter_sampling.contactparameter with weighted sampling based on age distance. The indivs buffer is expected to be empty on entry and will be filled with the sampled contacts in-place.

setting_age_contacts(postProcessor::PostProcessor, settingtype::Type{T}) where {T <: Setting}

Returns an age X age matrix containing sampled contacts for a provided settingtype T (i.e. Households)

Returns

• Matrix{Int32}: Sampled contacts in age-age matrix

setting_age_contacts(rd::ResultData)

Returns the settingagecontacts dictionary from the ResultData object. Returns an empty dictionary if the data is not available in the input ResultData object.

setting_age_contacts(rd::ResultData, settingtype::DataType)

Returns an age X age contact matrix for the specified settingtype (e.g. Households) based on sampled data. Returns an empty dictionary if the data is not available in the input ResultData object.