Contacts

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.

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

aggregate_populationDF_by_age(population_df::DataFrame, interval_steps::Int64)::Matrix

Helper function (it's not intended for direct use, its's rather called by other functions), to aggregate a populationDF by age. interval_steps describes the size of each age group to aggregate. The aggregated populationDF will be returned as a Matrix.

aggregate_populationDF_by_age(population_df::DataFrame, interval_steps::Int64, max_age::Int64)::Vector

Helper function (it's not intended for direct use, its's rather called by other functions, to aggregate a populationDF by age. interval_steps describes the size of each age group to aggregate. max_age sets a maximum age until which the matrix should be aggregated.

Returns

The aggregated populationDF will be returned as a Matrix.

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.

calculate_absolute_error(matrix1::Matrix{T}, matrix2::Matrix{T})::Matrix{T} where T <: Number

Calculate the absolute difference between matrix1 and matrix2.

Example

julia> m1 = [2 2; 2 2]
2×2 Matrix{Int64}:
 2  2
 2  2

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

calculate_absolute_error(m1,m2)
2×2 Matrix{Int64}:
 1  1
 2  0

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::DataType, include_non_contacts::Bool)::DataFrame

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.

mean_contacts_per_age_group(post_processor::PostProcessor, settingtype::DataType, interval_steps::Int64)::ContactMatrix{Float64}

Calculates the mean number of contacts between two age groups. The age gropus are defined by the size of interval_steps. The population data is accessed via the postProcessor object to get the number of individuals per age group.

Returns

Returns a ContactMatrix object containing the calculated mean contacts per age group and the interval steps.

mean_contacts_per_age_group(post_processor::PostProcessor, settingtype::DataType, interval_steps::Int64, max_age::Int64)::ContactMatrix{Float64}

Calculates the mean number of contacts between two age groups. The age gropus are defined by the size of interval_steps. The population data is accessed via the postProcessor object to get the number of individuals per age group.

max_age sets a maximum age until which the matrix should be aggregated.

Returns

Returns a ContactMatrix object containing the calculated mean contacts per age group and the interval steps and max age for aggregation.

sample_contacts(contact_sampling_method::ContactSamplingMethod, setting::Setting, individual::Individual, tick::Int16)::ErrorException

Abstract function as Fallback if no specific method is available.

sample_contacts(random_sampling_method::RandomSampling, setting::Setting, individual::Individual, tick::Int16)::Vector{Individual}

Sample exactly 1 random contact from the individuals in setting.

sample_contacts(contactparameter_sampling::ContactparameterSampling, setting::Setting, individual::Individual, tick::Int16)::Vector{Individual}

Sample random contacts based on a Poisson-Distribution spread around contactparameter_sampling.contactparameter.

setting_age_contacts(postProcessor::PostProcessor, settingtype::DataType)

Returns an age X age matrix containing sampled contacts for a provided settingtype (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.

setting_age_contacts(batchProcessor::BatchProcessor, settingtype::DataType)

Returns a {String, DataFrame} dictionary containing an age X age matrix with sampled contacts for a provided settingtype (i.e. Households) for each population files of this batch.