epicontacts: Handling, visualisation and analysis of epidemiological contacts

Operation

epicontacts is released as an open-source R package. A stable release is available for Windows, Mac and Linux operating systems via the CRAN repository. The latest development version of the package is available through the RECON Github organization. At minimum users must have R installed. No other system dependencies are required.

# install from CRAN
install.packages("epicontacts")

# install from Github
install.packages("devtools")
devtools::install_github("reconhub/epicontacts")

# load and attach the package
library(epicontacts)

Implementation

Data handling. epicontacts includes a novel data structure to accommodate line list and contact list datasets in a single object. This object is constructed with the make_epiconctacts() function and includes attributes from the original datasets. Once combined, these are mapped internally in a graph paradigm as nodes and edges. The epicontacts data structure also includes a logical attribute for whether or not this resulting network is directed.

The package takes advantage of R’s generic functions, which call specific methods depending on the class of an object. This is implemented in several places, including the summary.epicontacts() and print.epicontacts() methods, both of which are respectively called when the summary() or print() functions are used on an epicontacts object. The package does not include built-in data, as exemplary contact and line list datasets are available in the outbreaks package¹⁶.

# install the outbreaks package for data
install.packages("outbreaks")

# load the outbreaks package
library(outbreaks)

# construct an epicontacts object
x <- make_epicontacts(linelist=mers_korea_2015[[1]],
                         contacts = mers_korea_2015[[2]],
                         directed=TRUE)

# print the object
x

## 
## /// Epidemiological Contacts // 
## 
##   // class: epicontacts 
##   // 162 cases in linelist; 98 contacts;  directed 
## 
##   // linelist 
## 
## # A tibble: 162 x 15 
##    id      age age_class sex    place_infect  reporting_ctry loc_hosp 
##  * <chr> <int> <chr>     <fct>  <fct>         <fct>          <fct> 
##  1 SK_1     68 60-69     M      Middle East   South Korea    Pyeongtaek St˜
##  2 SK_2     63 60-69     F      Outside Midd˜ South Korea    Pyeongtaek St˜ 
##  3 SK_3     76 70-79     M      Outside Midd˜ South Korea    Pyeongtaek St˜ 
##  4 SK_4     46 40-49     F      Outside Midd˜ South Korea    Pyeongtaek St˜ 
##  5 SK_5     50 50-59     M      Outside Midd˜ South Korea    365 Yeollin C˜ 
##  6 SK_6     71 70-79     M      Outside Midd˜ South Korea    Pyeongtaek St˜ 
##  7 SK_7     28 20-29     F      Outside Midd˜ South Korea    Pyeongtaek St˜ 
##  8 SK_8     46 40-49     F      Outside Midd˜ South Korea    Seoul Clinic,˜ 
##  9 SK_9     56 50-59     M      Outside Midd˜ South Korea    Pyeongtaek St˜ 
## 10 SK_10    44 40-49     M      Outside Midd˜ China          Pyeongtaek St˜ 
## # ... with 152 more rows, and 8 more variables: dt_onset <date>,  dt_report
## #   <date>, week_report <fct>, dt_start_exp <date>, dt_end_exp  <date>,
## #   dt_diag <date>, outcome <fct>, dt_death <date>
##
##   // contacts
##
## # A tibble: 98 x 4
##    from  to     exposure      diff_dt_onset
##    <chr> <chr>  <fct>                 <int>
##  1 SK_14 SK_113 Emergency room           10
##  2 SK_14 SK_116 Emergency room           13
##  3 SK_14 SK_41  Emergency room           14
##  4 SK_14 SK_112 Emergency room           14
##  5 SK_14 SK_100 Emergency room           15
##  6 SK_14 SK_114 Emergency room           15
##  7 SK_14 SK_136 Emergency room           15
##  8 SK_14 SK_47  Emergency room           16
##  9 SK_14 SK_110 Emergency room           16
## 10 SK_14 SK_122 Emergency room           16
## # ... with 88 more rows

# view a summary of the object 
summary(x)

##
## /// Overview //
##   // number of unique IDs in linelist: 162
##   // number of unique IDs in contacts: 97
##   // number of unique IDs in both: 97
##   // number of contacts: 98
##   // contacts with both cases in linelist: 100 %
##
## /// Degrees of the network //
##   // in-degree summary:
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
##    0.00    1.00    1.00    1.01    1.00    3.00
##
##   // out-degree summary:
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
##    0.00    0.00    0.00    1.01    0.00   38.00
##
##   // in and out degree summary:
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
##   1.000   1.000   1.000   2.021   1.000  39.000
##
## /// Attributes //
##   // attributes in linelist:
##  age age_class sex place_infect reporting_ctry loc_hosp dt_onset dt_report week_report dt_start_exp dt_end_exp dt_diag outcome dt_death
##
##   // attributes in contacts:
##  exposure diff_dt_onset

Data visualisation. epicontacts implements two interactive network visualisation packages: visNetwork and threejs^17,18. These frameworks provide R interfaces to the vis.js and three.js JavaScript libraries respectively. Their functionality is incorporated in the generic plot() method (Figure 1) for an epicontacts object, which can be toggled between either with the “type” parameter. Alternatively, the visNetwork interactivity is accessible via vis_epicontacts() (Figure 2), and threejs through graph3D() (Figure 3). Each function has a series of arguments that can also be passed through plot(). Both share a color palette, and users can specify node, edge and background colors. However, vis_epicontacts() includes a specification for “node_shape” by a line list attribute as well as a customization of that shape with an icon from the Font Awesome icon library. The principal distinction between the two is that graph3D() is a three-dimensional visualisation, allowing users to rotate clusters of nodes to better inspect their relationships.

Figure 1. The generic plot() method for an epicontacts object will use the visNetwork method by default.

Figure 2. The vis_epicontacts() function explicitly calls visNetwork to make an interactive plot of the contact network.

Figure 3. The graph3D() function generates a three-dimensional network plot.

plot(x)

vis_epicontacts(x,
		  node_shape = "sex",
		  shapes = c(F = "female", M = "male"),
		  edge_label = "exposure")

graph3D(x, bg_col = "black")

Data analysis. Subsetting is a typical preliminary step in data analysis. epicontacts leverages a customized subset method to filter line list or contacts based on values of particular attributes from nodes, edges or both. If users are interested in returning only contacts that appear in the line list (or vice versa), the thin() function implements such logic.

# subset for males
subset(x, node_attribute = list("sex" = "M"))

# subset for exposure in emergency room
subset(x, edge_attribute = list("exposure" = "Emergency room"))

# subset for males who survived and were exposed in emergency room
subset(x,
        node_attribute = list("sex" = "M", "outcome" = "Alive"),
        edge_attribute = list("exposure" = "Emergency room"))

thin(x, "contacts")
thin(x, "linelist")

For analysis of pairwise contact between individuals, the get_pairwise() feature searches the line list based on the specified attribute. If the given column is a numeric or date object, the function will return a vector containing the difference of the values of the corresponding “from” and “to” contacts. This can be particularly useful, for example, if the line list includes the date of onset of each case. The subtracted value of the contacts would approximate the serial interval for the outbreak¹⁹. For factors, character vectors and other non-numeric attributes, the default behavior is to print the associated line list attribute for each pair of contacts. The function includes a further parameter to pass an arbitrary function to process the specified attributes. In the case of a character vector, this can be helpful for tabulating information about different contact pairings with table().

# find interval between date onset in cases
get_pairwise(x, "dt_onset")

# find pairs of age category contacts
get_pairwise(x, "age_class")

# tabulate the pairs of age category contacts
get_pairwise(x, "age_class", f = table)

Benefits

While there are software packages available for epidemiological contact visualisation and analysis, none aim to accommodate line list and contact data as purposively as epicontacts^20–22. Furthermore, this package strives to solve a problem of plotting dense graphs by implementing interactive network visualisation tools. A static plot of a network with many nodes and edges may be difficult to interpret. However, by rotating or hovering over an epicontacts visualisation, a user may better understand the data.

Future considerations

The maintainers of epicontacts anticipate new features and functionality. Future development could involve performance optimization for visualising large networks, as generating these interactive plots is resource intensive. Additionally, attention may be directed towards inclusion of alternative visualisation methods.