Design Principles

This vignette outlines the design decisions that have been taken during the development of the contactmatrix R package, and provides some of the reasoning, and possible pros and cons of each decision.

This document is primarily intended to be read by those interested in understanding the code within the package and for potential package contributors.

Scope

This package aims to provide a standardised way of dealing with empirical and synthetic social contacts data, such as data from the socialmixr, contactdata, and conmat R packages. The main rationale is to allow downstream analysis and modelling packages to seamlessly switch from one package to the other without having to reformat the input data. This new contact matrix package will provide a shared, basic, contact matrix class. It is expected that some packages will use this class as an single element in a more complex list output (e.g., socialmixr also includes a citation element)

Classes

contactmatrix

• Inherits from array (matrix for 2D) to leverage existing methods, and utility functions (e.g., t())
  • ✓ used in socialmixr
  • ✓ used in contactdata
  • ✓ used in conmat
• Puts survey participants in rows:
  • ✓ used in socialmixr
  • ✓ used in contactdata
  • ✗ transposed in conmat
• Levels are ordered lexicographically (using C locale)
• Boolean attr(cm, “symmetric”) to determine if $c_{ij}N_i == c_{ji}N_j$
• Standardized notation to denote age-bins ([low, high)):
  • ✓ used in socialmixr
  • ✓ used in conmat plots
  • ✓ used in Epiverse-TRACE plots

Special case of multiple groupings

Although currently rare, we can theoretically consider contact matrices with multiple groupings (e.g. age & gender). To ensure forward-compatibility if this ever becomes more common practice, we allow multiple groupings in the form or multi-dimensional arrays.

• Groupings are ordered lexicographically (using C locale) with the first being the most external.

contactmatrix_list

A list of contactmatrix from different settings, or just different runs of the socialmixr algorithm to convert survey data to a contact matrix.

Functions and methods

Class infrastructure

• a new_<class>() function to “manually” construct a new object of the given class
• two validation functions based on the checkmate package terminology:
  • an assert_<class>(x) function which returns an error or x invisibly
  • a test_<class>(x) function which returns a boolean
• an is_<class>() function to check if an object is of the given class, without checking its validity
• as_contactmatrix() generic

Custom methods

• plot() method for visualisation
• print() method for human-readable output:
  • Show levels

Helpers

• Helper to convert to long format;
• Helper to transform and interpolate between ages in bins of various sizes.
• Helper to summarise a contactmatrix_list into a contactmatrix (aggregate_contactmatrix_list())
• Helper to make the contact matrix symmetric (cm_make_symmetric())
• Helper to obtain the age bins and breaks (if present) in terms of a vector with min or max ages, but also a text-format for figure labels etc.

Dependencies

This package is placed at the low position in the dependency stack, and should therefore depend itself on as few packages as possible.