Subset epicontacts objects based on case identifiers

Description

The "[" operator can be used to subset epicontacts objects, retaining a specified set of case identifiers (i for the linelist, j for contacts). Note that unlike most classical R objects, there is no replacement method for epicontacts objects, i.e. no operations such as foo[i] <- bar.

Usage

## S3 method for class 'epicontacts'

  x[
  i,
  j,
  k = TRUE,
  l = TRUE,
  contacts = c("both", "either", "from", "to"),
  ...
]

Arguments

Details

Details on the 'contacts' argument; possible values are:

• 'both': contacts are retained only if both cases are in j

• 'either': contacts are retained if at least one of the cases is in j

• 'from': contacts are retained only if the source ('from') is in j

• 'to': contacts are retained only if the recipient ('to') is in j

Author(s)

Thibaut Jombart (thibautjombart@gmail.com)

See Also

thin to retain matching cases in linelist or contacts.

Examples

if (require(outbreaks)) {
## build data
x <- make_epicontacts(ebola_sim$linelist, ebola_sim$contacts,
                       id = "case_id", to = "case_id", from = "infector",
                       directed = TRUE)

## subset first 10 linelist cases
x[1:10]

## same, remove contacts
x[1:10, j = FALSE]

## subset first 10 contacts
x[j = 1:10]

## remove the metadata
x[k = FALSE, j = FALSE]

## keep contacts where both cases are in linelist
x[j = get_id(x, "linelist"), contacts = "both"]

## keep contacts from a specific case '916d0a'
x[j = "916d0a", contacts = "from"]

## more complex: keep all cases and contacts with > 4 secondary contacts
## i) find cases to keep
temp <- table(x$contacts$from)
temp[temp > 4]
to.keep <- names(temp)[temp > 4]
to.keep

## subset the contacts
y <- x[j = to.keep, contacts = "either"]
y

## keep only relevant entries in the linelist
y <- thin(y)

## visualise result
plot(y)
}

Create igraph object from contact data

Description

This function creates an igraph object from a given epicontacts object containing a 'contacts' dataframe.

Usage

## S3 method for class 'epicontacts'
as.igraph(x, ...)

Arguments

Value

An igraph object (from the igraph package). Note: any column called "name" in the original linelist will be stored as a new vertex attribute in the igraph object named 'epicontacts_name'. This is due to the inherent behaviour of igraph creating its own 'name' vertex attribute.

Author(s)

Nistara Randhawa (nrandhawa@ucdavis.edu)

Examples

if (require(outbreaks) && require(igraph)) {
## build data

x <- make_epicontacts(ebola_sim$linelist, ebola_sim$contacts,
                      id = "case_id", to = "case_id", from ="infector",
                      directed = TRUE)


## subset data - keep 50 cases from linelist with contacts

ids <- get_id(x, "common")[1:50]
ids
x <- x[ids, ids]


## make igraph object with associated attributes from epicontacts object

net <- as.igraph(x)
net
plot(net, vertex.label = "", vertex.size = 10,
     vertex.color = cases_pal(50))
}

Reference codes for fontawesome

Description

The object codeawesome is a character vector of fontawesome codes, named after their aliases.

Usage

codeawesome

Format

An object of class character of length 519.

Author(s)

Thibaut Jombart

Assign cluster IDs to epicontacts data

Description

This function identifies transitive clusters (i.e. connected components) as well as the number of members in each cluster, and adds this information to the linelist data.

Usage

get_clusters(
  x,
  output = c("epicontacts", "data.frame"),
  member_col = "cluster_member",
  size_col = "cluster_size",
  override = FALSE
)

Arguments

Value

An epicontacts object whose 'linelist' dataframe contains new columns corresponding to cluster membership and size, or a data.frame containing member ids, cluster memberships as factors, and associated cluster sizes. All ids that were originally in the 'contacts' dataframe but not in the linelist will also be added to the linelist.

Author(s)

Nistara Randhawa (nrandhawa@ucdavis.edu)

Examples

if (require(outbreaks)) {
## build data
x <- make_epicontacts(ebola_sim$linelist, ebola_sim$contacts,
                       id = "case_id",
                       to = "case_id",
                       from = "infector",
                       directed = TRUE)


## add cluster membership and sizes to epicontacts 'linelist'
y <- get_clusters(x, output = "epicontacts")
y

## return a data.frame with linelist member ids and cluster memberships as
## factors
z <- get_clusters(x, output = "data.frame")
head(z)

}

Find node degree for epicontacts objects

Description

This function computes the number of contacts per cases in a epicontacts dataset. Whenever contacts are directed, the argument 'type' can be used to specify which kind of contact should be considered: 'in' (towards the case), 'out' (from the case), or 'both'.

Usage

get_degree(x, type = c("in", "out", "both"), only_linelist = FALSE)

Arguments

Author(s)

Thibaut Jombart (thibautjombart@gmail.com)

Examples

## make epicontacts object
if (require(outbreaks)) {
x <- make_epicontacts(ebola_sim$linelist, ebola_sim$contacts,
                       id="case_id", to="case_id", from="infector",
                       directed=TRUE)
x

## compute in-degree
deg_in <- get_degree(x)
table(deg_in)

## compute out-degree
deg_out <- get_degree(x, "out")
barplot(table(deg_out), main = "Reproduction number distribution")
mtext(side = 3, "(based on case out-degree)")

}

Access unique identifiers in epicontacts objects

Description

This accessor is used to extract unique identifiers from epicontacts objects. The argument 'which' can be used to specify if IDs should include: linelist only ('linelist'), contacts only ('contacts'), the union of both ('all'), or the intersection of both ('common'); two additional options are 'from' (ID 'giving' contacts) and 'to' (ID 'receiving' contacts).

Usage

get_id(
  x,
  which = c("linelist", "contacts", "all", "common", "from", "to"),
  na.rm = TRUE
)

Arguments

Value

x a character vector of unique identifiers

Author(s)

Thibaut Jombart (thibautjombart@gmail.com)

Examples

if (require(outbreaks)) {
## build data
x <- make_epicontacts(ebola_sim$linelist, ebola_sim$contacts,
                       id="case_id", to="case_id", from="infector",
                       directed=TRUE)

## get identifiers
id1 <- get_id(x, "linelist")
id2 <- get_id(x, "contacts")
id3 <- get_id(x, "all")
id4 <- get_id(x, "common")

## check intersections and unions
all.equal(union(id1, id2), id3)
all.equal(intersect(id1, id2), id4)

}

Characterise contacts by comparing case attributes

Description

This function extract attributes of cases involved in contacts using case information provided in the linelist of an epicontacts dataset. If not provided, the function used to process attributes will adjust to the type of attribute selected (see details).

Usage

get_pairwise(x, attribute, f = NULL, hard_NA = TRUE)

Arguments

Author(s)

Thibaut Jombart (thibautjombart@gmail.com) Tom Crellen (tomcrellen@gmail.com)

Examples

if (require(outbreaks)) {
## example using MERS outbreak in Korea, 2014
head(mers_korea_2015[[1]])
head(mers_korea_2015[[2]])

x <- make_epicontacts(linelist=mers_korea_2015[[1]],
contacts=mers_korea_2015[[2]], directed=TRUE)

## estimate serial interval (onset->onset)
SI <- get_pairwise(x, "dt_onset")
SI
summary(SI)
hist(SI, col="grey", border="white", xlab="Days after symptoms",
     main="MERS Korea 2014 - Serial Interval")

## check gender mixing:
get_pairwise(x, "sex") # not good, we want 2-way table

get_pairwise(x, "sex", f=table) # use custom function
fisher.test(get_pairwise(x, "sex", f=table)) # test association
}

Interactive 3D Force-directed graph from epicontacts object

Description

This function creates a 3D graph from an epicontacts object

Usage

graph3D(
  x,
  node_color = "id",
  annot = TRUE,
  col_pal = cases_pal,
  NA_col = "lightgrey",
  g_title = "",
  bg_col = "white",
  label_col = "darkgrey",
  node_size = 1,
  edge_size = 0.5
)

Arguments

Value

An htmlwidget object that is displayed using the object's show or print method. (If you don't see your widget plot, try printing it with the print function.)

Note

All colors must be specified as color names like "red", "blue", etc. or as hexadecimal color values without opacity channel, for example "#FF0000", "#0a3e55" (upper or lower case hex digits are allowed).

Double-click or tap on the plot to reset the view.

Author(s)

Nistara Randhawa (nrandhawa@ucdavis.edu) Thibaut Jombart (thibautjombart@gmail.com) VP Nagraj (vpnagraj@virginia.edu)

References

Original rthreejs code by B. W. Lewis: https://github.com/bwlewis/rthreejs.

Examples

if (require(outbreaks)) {

## example using MERS outbreak in Korea, 2014
head(mers_korea_2015[[1]])
head(mers_korea_2015[[2]])

x <- make_epicontacts(linelist = mers_korea_2015$linelist,
                      contacts = mers_korea_2015$contacts,
                      directed = FALSE)

## Not run: 
graph3D(x)
graph3D(x, annot = FALSE)
graph3D(x, node_color = "sex", g_title = "MERS Korea 2014")
graph3D(x, node_color = "sex", annot = c("sex", "age"),
        g_title = "MERS Korea 2014")

## End(Not run)
}

Read linelist and contact data

Description

This function reads data stored as data.frame containing linelist (case information, where each row corresponds to a unique patient), and contacts between patients. Common identifiers should be used in the two data sources for matching to be achieved.

Usage

make_epicontacts(
  linelist,
  contacts,
  id = 1L,
  from = 1L,
  to = 2L,
  directed = FALSE
)

Arguments

Details

An epicontacts object can be created from two components:

• a linelist provided as a data.frame where columns are different variables describing cases, and where each row is a different case. and a contact list.

• a contact list provided as a data.frame where each row contains unique pairs of contacts with unique features of contact in columns. The line list and contact list should share an identification scheme for individuals.

Value

An epicontacts object in list format with three elements:

• linelist: data.frame of cases with first column 'id' containing character vector of unique identifiers

• contacts: data.frame of contacts with first two columns named 'from' and 'to' indicating unique pairs of contact between individuals

• directed: indicator as to whether or not the contacts are to be considered directed or not

Author(s)

Thibaut Jombart (thibautjombart@gmail.com)

Examples

if (require(outbreaks)) {
## make epicontacts object from simulated Ebola data
x <- make_epicontacts(ebola_sim$linelist, ebola_sim$contacts)

## test reordering of columns
linelist <- ebola_sim$linelist[,rev(seq_len(ncol(ebola_sim$linelist)))]
contacts <- ebola_sim$contacts[,rev(seq_len(ncol(ebola_sim$contacts)))]
head(linelist)
head(contacts)

## make object
x <- make_epicontacts(linelist, contacts, id = "case_id",
                       to = "case_id", from = "infector")
head(x$linelist)
head(x$contacts)
}

Plot epicontacts objects

Description

This function plots epicontacts objects using various approaches. The default method uses vis_epicontacts.

Usage

## S3 method for class 'epicontacts'
plot(
  x,
  node_color = "id",
  method = c("visNetwork", "graph3D"),
  thin = TRUE,
  ...
)

Arguments

Details

This function is merely a wrapper for other plotting functions in the package, depending on the value of method:

• visNetwork: calls the function vis_epicontacts

• graph3D: calls the function graph3D

Author(s)

Thibaut Jombart (thibautjombart@gmail.com)

See Also

vis_epicontacts, which uses the package visNetwork, and codeawesome for icon codes.

Examples

if (require(outbreaks)) {
## example using MERS outbreak in Korea, 2014
head(mers_korea_2015[[1]])
head(mers_korea_2015[[2]])

x <- make_epicontacts(linelist = mers_korea_2015[[1]],
                      contacts = mers_korea_2015[[2]], directed=TRUE)

## Not run: 
plot(x)
plot(x, "place_infect")
plot(x, "loc_hosp", legend_max = 20, annot = TRUE)
plot(x, "place_infect", node_shape = "sex",
     shapes = c(M = "male", F = "female"))
plot(x, 4)
plot(x, 4, method = "graph3D")

## End(Not run)
}

Print method for epicontacts objects

Description

This method prints the content of epicontacts objects, giving a brief summary of the reported cases and contacts.

Usage

## S3 method for class 'epicontacts'
print(x, ...)

Arguments

Author(s)

Thibaut Jombart (thibautjombart@gmail.com)

Print method for summary_epicontacts objects

Description

This method outputs a printed summary of the content of summary_epicontacts objects.

Usage

## S3 method for class 'summary_epicontacts'
print(x, ...)

Arguments

Author(s)

VP Nagraj (vpnagraj@virginia.edu)

Subset an epicontact object by factors

Description

This function subsets an epicontacts object based on node, edge and/or cluster attributes. Specifying node attributes will return an epicontacts object containing only individuals with these given attributes in the linelist. Specifying edge attributes will return contacts with the attributes provided. Specifying cluster attributes will return clusters of connected cases, and can be defined by ids (returning clusters of cases connected to specified cases) or cluster sizes (returning cluster of a specific, minimum or maximum size).

Usage

## S3 method for class 'epicontacts'
subset(
  x,
  node_attribute = NULL,
  edge_attribute = NULL,
  cluster_id = NULL,
  cs = NULL,
  cs_min = NULL,
  cs_max = NULL,
  ...
)

Arguments

Author(s)

Finlay Campbell (f.campbell15@imperial.ac.uk), Nistara Randhawa (nrandhawa@ucdavis.edu)

Examples

if (require(outbreaks)) {
## build data

x <- make_epicontacts(ebola_sim$linelist, ebola_sim$contacts,
                      id = "case_id", to = "case_id",
                      from = "infector", directed = FALSE)

## subset based on node and edge attributes
x_subset <- subset(x, node_attribute = list("gender" = "f"),
                   edge_attribute = list("source" = "funeral"))


## subset a cluster connected to a given id
## (can be a vector of ids as well)
## here picking node with highest out-degree

id <- names(which.max(get_degree(x, "out")))
x_subset <- thin(subset(x, cluster_id = id), 2)
x_subset
plot(x_subset)


## subset based on cluster size range

x_subset <- subset(x, cs_min = 12, cs_max = 15)


## subset based on single cluster size

x_subset <- subset(x, cs = 12)


## subset based on minimum cluster size

x_subset <- subset(x, cs_min = 10)


## subset based on maximum cluster size

x_subset <- subset(x, cs_max = 9)


}

Subset epicontacts by case-specified clusters

Description

This function subsets an epicontacts object by identifying clusters of cases connected to specified cases.

Usage

subset_clusters_by_id(x, id)

Arguments

Value

An epicontacts object whose contact dataframe corresponds to all clusters containing specified case id.

Author(s)

Nistara Randhawa (nrandhawa@ucdavis.edu)

Examples

if (require(outbreaks)) {
## build data
x <- make_epicontacts(ebola_sim$linelist, ebola_sim$contacts,
                       id="case_id", to="case_id", from="infector",
                       directed=TRUE)


id <- "cac51e" ## it can be a vector of id as well


## subset based on cluster to which "cac51e" belongs
x_subset <- subset_clusters_by_id(x, id)

}

Subset clusters from epicontacts object by cluster size

Description

This function subsets an epicontacts object based on defined size(s) of clusters (clusters being groups of connected individuals/nodes). Subsetting may be done by specifying a particular cluster size of interest, minimum cluster size, maximum cluster size, or a range (minimum and maximum) of cluster sizes.

Usage

subset_clusters_by_size(x, cs = NULL, cs_min = NULL, cs_max = NULL)

Arguments

Value

An epicontacts object whose contact dataframe corresponds to all clusters of specified cluster sizes.

Author(s)

Nistara Randhawa (nrandhawa@ucdavis.edu)

Examples

if (require(outbreaks)) {
## build data
x <- make_epicontacts(ebola_sim$linelist, ebola_sim$contacts,
                       id="case_id", to="case_id", from="infector",
                       directed=TRUE)


## subset based on cluster size range
x_subset <- subset_clusters_by_size(x, cs_min = 12, cs_max = 15)


## subset based on single cluster size
x_subset <- subset_clusters_by_size(x, cs = 12)


## subset based on minimum cluster size
x_subset <- subset_clusters_by_size(x, cs_min = 10)


## subset based on maximum cluster size
x_subset <- subset_clusters_by_size(x, cs_max = 9)
}

Summary method for epicontacts objects

Description

This method outputs a summary of the content of epicontacts objects.

Usage

## S3 method for class 'epicontacts'
summary(object, ...)

Arguments

Author(s)

VP Nagraj (vpnagraj@virginia.edu)

Thin data to retain matching linelist / contacts

Description

This function can be used to remove ('thin') data from epicontacts objects to ensure stricter matching of linelists and contacts. It has two behaviours, triggered by the argument what: either it thins data from $linelist, keeping only cases that are in $contacts (thin = "linelist", default), or the converse, i.e. removing contacts which are not fully documented in the linelist.

Usage

thin(x, what = "linelist")

Arguments

Author(s)

Thibaut Jombart (thibautjombart@gmail.com)

Examples

if (require(outbreaks)) {
## build data
x <- make_epicontacts(ebola_sim$linelist, ebola_sim$contacts,
                       id = "case_id", to = "case_id", from = "infector",
                       directed = TRUE)

## keep contacts from a specific case '916d0a'
x <- x[j = "916d0a", contacts = "from"]

}

Color tools and palettes for epicontacts

Description

These functions are used for defining palettes or colors in the epicontacts package. They include:

Usage

transp(col, alpha = 0.5)

edges_pal(n)

cases_pal(n)

spectral(n)

fac2col(x, pal = cases_pal, NA_col = "lightgrey", legend = FALSE)

Arguments

Details

• cases_pal: discrete color palette used for cases (comes from the dibbler package)

• spectral: continuous color palette (comes from the adegenet package)

• transp: makes colors transparent (comes from the adegenet package)

• fac2col: translates a character or a factor to a color using a palette (comes from the adegenet package)

Author(s)

Thibaut Jombart thibautjombart@gmail.com

Examples

barplot(1:5, col = cases_pal(5))
barplot(1:50, col = cases_pal(50))

Plot epicontacts objects using visNetwork

Description

This function plots epicontacts objects using the visNetwork package. The produced object is an htmlwidget which will need rendering within a web browser.

Usage

vis_epicontacts(
  x,
  thin = TRUE,
  node_color = "id",
  label = "id",
  annot = TRUE,
  node_shape = NULL,
  shapes = NULL,
  edge_label = NULL,
  edge_color = NULL,
  legend = TRUE,
  legend_max = 10,
  x_axis = NULL,
  col_pal = cases_pal,
  NA_col = "lightgrey",
  edge_col_pal = edges_pal,
  width = "90%",
  height = "700px",
  selector = TRUE,
  editor = FALSE,
  edge_width = 3,
  ...
)

Arguments

Value

The same output as visNetwork.

Author(s)

Thibaut Jombart (thibautjombart@gmail.com) VP Nagraj (vpnagraj@virginia.edu) Zhian N. Kamvar (zkamvar@gmail.com)

See Also

visNetwork in the package visNetwork. edges_pal and cases_pal for color palettes used

Examples

if (require(outbreaks)) {

## example using MERS outbreak in Korea, 2014
head(mers_korea_2015[[1]])
head(mers_korea_2015[[2]])

x <- make_epicontacts(linelist=mers_korea_2015[[1]],
                       contacts = mers_korea_2015[[2]],
                       directed=TRUE)

## Not run: 
plot(x)
plot(x, node_color = "place_infect")
# show transmission tree with time as the horizontal axis, showing all nodes
#' plot(x, node_color = "loc_hosp", legend_max=20, annot=TRUE)
#' plot(x, "place_infect", node_shape = "sex",
     shapes = c(M = "male", F = "female"))

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

## End(Not run)
}