Quick Start - MultIS

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

set.seed(42)

require(MultIS)

Purpose

With MultIS, we present a bioinformatical approach to detect the multiple integration of viral vectors within the same clone. These integrations result in multiple integration sites (IS) that can be detected using sequencing methods and traced in time series data. Our method is based on the idea that read outs of IS within the same clone appear in similar relative frequencies to each other over different measurements, while IS from different clones will change their relative mutual frequency according to the relative clone sizes to which they belong. We calculate the correlation of these frequencies for all pairs of IS to quantify their similarity and subsequently use clustering algorithms to identify sets of IS with high internal correlation, suggesting the same clonal origin.

# Example was generated using the following code
simData <- simulate(ro_compartments = 1,
                    tps = seq(1, 2*365, 60),
                    nr_clones = 7,
                    target_vcn = 6,
                    clonal_variability = 0.4,
                    measurement_noise = 0.2,
                    use_amplification = FALSE,
                    simulate_clones_params = list(
                      nr_clones = 7, tps = seq(0, 2 * 365, 60),
                      prolif = list(type = "nDistributedFixed", n_distributed_mean = 0.3,
                                    n_distributed_sigma = 0, with_lf = TRUE, cc = 10000),
                      diff = list(type = "nDistributedFixed", n_distributed_mean = 0.2,
                                  n_distributed_sigma = 0, with_lf = FALSE),
                      initdist = list(type = "equal", equal_equc = (0.3/0.2) * 100))
)
save(simData, file = 'example.RData', version = 2)
write.table(simData$is_readouts, file = 'example_readouts.csv', sep = ',')

MultIS with biological data

When using "MultIS" with biological data, the clonal data should be stored in a matrix data structure. To have easy access to the included plotting routines, simply assign this matrix the additional class "timeseries". The class is the used to dispatch to the correct function.

For example, one can load a data set like this:

dat <- read.table(file = "example_readouts.csv",
                  sep = ",", header = TRUE, row.names = 1, check.names = FALSE)
dat <- as.matrix(dat)
class(dat) <- c(class(dat), "timeseries")

The rows in this matrix represent individual IS (or unique clonal identifiers, barcodes), while the columns represent the different measurements. Values in the matrix show the read count for the respective IS and measurement.

Within our package, measurement refers not only to different time points, but can also refer to measurements of different cell types.

Here, 13 consecutive measurements for ten IS of our example are shown:

knitr::kable(dat[1:10,], row.names = TRUE, digits = 2)

Visualize a time course

Stacked area plots are implemented as a visual representation of the IS abundance over different measurements. Here, we show the relative readouts of the integration sites originating from the time course data.

plot(dat)

Apply filtering strategies

Optionally, the data can be filtered. This step is recommended to avoid the detection of spurious correlations. There are several filter functions:

Here, we demonstrate how to apply a filter that selects for the 10 most abundant IS at the final timepoint.

filteredDat <- MultIS::filter_at_tp_biggest_n(dat, at = "720", n = 10L)
plot(filteredDat)

Calculate similarities between integration sites

similarityMatrix <- MultIS::get_similarity_matrix(dat, parallel = FALSE)

is1 = which.max(unlist(
  lapply(1:(ncol(similarityMatrix) - 2),
         function(i) {
           similarityMatrix[i, i + 1] +           # maximize
             (1 - similarityMatrix[i + 1, i + 2]) # minimize
         })
  ))
is2 = is1 + 1
is3 = is1 + 2

Next, we can determine similarities between different IS. Here, we show the similarity based on $R^2$ illustrated by two integration sites (r is1, r is2) originating from the same clone. They present a high $R^2$ similarity score. Two integration sites originating from different clones (r is2, r is3) do not show this characteristic correlation:

r2 = round(summary(stats::lm(y ~ 0 + x, data = data.frame(
    x = dat[is1, ], y = dat[is2, ])))$r.squared, 3)

p1 <- MultIS::plot_rsquare(dat, is1, is2) +
  ggplot2::ggtitle(label = bquote(R^2 == .(r2))) +
  ggplot2::theme(plot.title = ggplot2::element_text(hjust = 0.5))


r2 = round(summary(stats::lm(y ~ 0 + x, data = data.frame(
    x = dat[is2, ], y = dat[is3, ])))$r.squared, 3)

p2 <- MultIS::plot_rsquare(dat, is2, is3) +
  ggplot2::ggtitle(label = bquote(R^2 == .(r2))) +
  ggplot2::theme(plot.title = ggplot2::element_text(hjust = 0.5))

gridExtra::grid.arrange(p1, p2, ncol = 2)

Next, we calculate the similarity of all pairs of integration sites, which gives us the similarity matrix.

similarityMatrix <- MultIS::get_similarity_matrix(dat, parallel = FALSE)

The similarity matrix is conveniently visualized using a heatmap, where clusters of similar integration sites can already be seen:

plot(similarityMatrix)

Clustering of similar integration sites

To represent the clusterings produced by the k-Medoids clustering algorithm, we visualize them for a defined number of clusters ($k = 2$ and $k = 4$):

clusterObjC2 <- MultIS::reconstruct(readouts = dat,
                                    target_communities = 2,
                                    method = "kmedoids",
                                    cluster_obj = TRUE,
                                    sim = similarityMatrix)
clusterObjC4 <- MultIS::reconstruct(readouts = dat,
                                    target_communities = 4,
                                    method = "kmedoids",
                                    cluster_obj = TRUE,
                                    sim = similarityMatrix)
p1 <- plot(clusterObjC2)
p2 <- plot(clusterObjC4)

gridExtra::grid.arrange(p1, p2, ncol = 2)

Automatically find the best number of clusters

To find the global optimum for the number of clusters $k$, we can next create clusterings for all sensible number of clusters (from 2 to the number of IS - 1). For each $k$ we calculate a quality score, which is show in the following plot as a function of the number of target clusters. The best number of clusters is indicated in red:

bestNrCluster <- MultIS::find_best_nr_cluster(
  data = dat,
  sim = similarityMatrix,
  method_reconstruction = "kmedoids",
  method_evaluation = "silhouette",
  return_all = TRUE)
plotDf <- data.frame(
  k = as.numeric(names(bestNrCluster)),
  score = as.numeric(bestNrCluster)
)
ggplot2::ggplot(plotDf, ggplot2::aes(x = k, y = score, group = 1)) +
  ggplot2::geom_line() +
  ggplot2::geom_point(ggplot2::aes(col = (score == max(score)))) +
  ggplot2::scale_color_manual(values = c("TRUE" = "#FF0000", "FALSE" = "#000000")) +
  ggplot2::theme_bw() +
  ggplot2::theme(legend.position = "none")

The clustering for the optimal value of $k$ can either be obtained by selecting it from all evaluations of clusterings in the step beforehand, or we can just re-run the method and tell it to only give us the best number of clusters:

bestNrCluster <- MultIS::find_best_nr_cluster(
  data = dat,
  sim = similarityMatrix,
  method_reconstruction = "kmedoids",
  method_evaluation = "silhouette",
  return_all = FALSE)

We then use this number $k$ to create a clustering and plot it. For the portrayed example, the data is best explained for $k = 7$ clusters:

clusterObjBest <- MultIS::reconstruct(
  readouts = dat,
  target_communities = bestNrCluster,
  method = "kmedoids",
  cluster_obj = TRUE,
  sim = similarityMatrix)
plot(clusterObjBest)

MultIS with known ground truth

For certain settings, such as model simulations or validation experiments, the true association between IS and clones is known. "MultIS" provides methods to integrate this information for benchmarking purposes.

Here, we use an illustrative example that was prepared with a simulation routine, which comprises the following steps:

  1. Run a clonal simulation.
  2. Add a multiplicative clonal variability to account for different cell types. This variability is beneficial to the reconstruction process.
  3. Superimposed IS to the clones. The number of IS per clone is drawn from a Poisson distribution around a specified mean, estimating the average vector copy number (VCN).
  4. Add Measurement noise multiplicatively to the IS counts to account for noise during the PCR and sequencing steps.

Each step in this analysis produces a time course that is the basis for the following step. In a real-world scenario, only the time course from the last step would be available, but as we use a simulation, we can use the known ground truth for validation and estimation of the accuracy of our methods.

First, the prepared example is loaded:

load("example.RData")

The loaded named list contains the steps of the simulation and further information. Its structure is the following:

str(simData, max.level = 1)

Time course representations

The general structure for the time courses is again a table with the serial measurements at different time points in the columns and the different integration sites in the rows. The following is a small selection of simData$barcodeReadouts contained within the simData object:

knitr::kable(simData$barcodeReadouts[1:10,], digits = 2, row.names = TRUE)

Due to this data stemming from a simulation, we can look at all steps in the simulation, from the simulated clones to the integration sites:

p1 <- plot(simData$clone_counts) + ggplot2::ggtitle("Basic clonal simulation")
p2 <- plot(simData$clone_readouts) + ggplot2:: ggtitle("Added clonal differences")
p3 <- plot(simData$is_counts) + ggplot2::ggtitle("Superimposition of integration sites")
p4 <- plot(simData$is_readouts) + ggplot2::ggtitle("Added measurement noise")
gridExtra::grid.arrange(p1, p2, p3, p4, ncol = 2, nrow = 2)

Mappings from integration sites to clones

For the data from our simulation, the true association between IS and clones is known:

mapping <- data.frame(Clone = unique(simData$mapping[,"Clone"]))
mapping$IS <- sapply(mapping$Clone, function(e) {
                      paste(summary(simData$mapping[simData$mapping[, "Clone"] == e, "IS"])[c("Min.", "Max.")], collapse = " - ")
                    })
knitr::kable(mapping)

Evaluation of different clusterings

In case the ground truth is known, we can apply the adjusted rand index (ARI) to calculate the pipeline's accuracy. Here, we apply the ARI function from the package "mclust" to compare the found clusterings for different values of $k$ to the ground truth. Additionally, we highlight the optimal match as a red point. An ARI value of $1$ for the optimum corresponds to a perfect match, i.e. except for labels, the found clustering is identical to the known ground truth.

similarityMatrix <- MultIS::get_similarity_matrix(simData$is_readouts,
                                                  parallel = FALSE)
aris <- sapply(3:12, function(k) {
  clusterObj <- MultIS::reconstruct(simData$is_readouts,
                                    target_communities = k,
                                    cluster_obj = TRUE,
                                    sim = similarityMatrix)
  mclust::adjustedRandIndex(clusterObj$mapping[,"Clone"], 
                            simData$mapping[,"Clone"])  
})
arisDF <- data.frame(
  k = 3:12,
  ARI = aris,
  stringsAsFactors = F
)
ggplot2::ggplot(arisDF, ggplot2::aes(x = k, y = ARI, colour = col)) +
  ggplot2::geom_line(colour = "black") +
  ggplot2::geom_point(size = 4, ggplot2::aes(color = (ARI == max(ARI)))) +
  ggplot2::scale_color_manual(values = c("TRUE" = "#FF0000", "FALSE" = "#000000")) +
  ggplot2::scale_x_continuous(breaks = 3:12) +
  ggplot2::theme_bw() +
  ggplot2::theme(legend.position = "none",
                 text = ggplot2::element_text(size = 16))


Try the MultIS package in your browser

Any scripts or data that you put into this service are public.

MultIS documentation built on Aug. 6, 2021, 5:07 p.m.