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 )

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.

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)

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.

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.