APackOfTheClones Essentials

Setting up the Seurat Object and Receptor Library with scRepertoire

The premise of the package is that it provides an additional analysis tool on top of scRepertoire’s many functions, which are all ran after combining all TCR/BCR contigs into clones, and integrating the clonal information into a seurat object with a dimensional reduction(s). Here are the corresponding vignettes to read in order for combining contigs:

1. Loading Data
2. Combining Contigs into Clones
3. Additional Processing Steps (optional)

And here is a practical example on how to generate a combined seurat + VDJ object to be used in the vignette named pbmc, which is also identical to the built-in example dataset combined_pbmc which can be loaded with data("combined_pbmc", package = "APackOfTheClones"):

library(scRepertoire)

# load in the corresponding 6-sample TCR contigs from scRepertoire
contig_list <- get(data("contig_list", package = "scRepertoire"))

# combine the TCR contigs into clones with custom samples
combined_contig_list <- scRepertoire::combineTCR(
  contig_list,
  samples = c("P17B", "P17L", "P18B", "P18L", "P19B", "P19L", "P20B", "P20L"),
  removeNA = FALSE,
  removeMulti = FALSE,
  filterMulti = FALSE
)

For integrating the clonal information, scRepertoire::combineExpression is the function used to do so, but for APackOfTheClones the scRNA-seq object has to be a seurat object:

# a seurat object corresponding to combined_contig_list named `pbmc` is loaded
pbmc <- scRepertoire::combineExpression(
  combined_contig_list,
  pbmc,
  cloneCall = "gene",
  proportion = TRUE
)

And as a reference, here is the corresponding UMAP plot of the seurat object

library(Seurat)
library(ggplot2)

pbmc_umap_plot <- UMAPPlot(pbmc)
pbmc_umap_plot + coord_fixed()

Key characteristics of the plot

• One should notice the immediate correspondence of circular clusters to umap clusters, and be able to derive some immediate insights about which clusters have expanded.
• The clonotype counts for each seurat cluster corresponds to their position and color in the original UMAP centroids
• The most expanded clonotypes are in the center of each circle cluster with larger sizes, symbolizing increased expansion
• On the plot, there is a somewhat imperfect visual legend of the relative clone sizes
• Some clusters have considerable visual overlap
• The returned plot is a fully customizable ggplot object

The resulting clonal expansion plot may not be visually satisfactory on the first run without customizations from optional arguments. These arguments and other ggplot tricks will be covered to fine-tune the visualization until publication-ready.

A Note on Subsetting Data

The subsetting parameters are barely more than syntactic sugar to subset the seurat metadata and dimensional reduction coordinates, and serves as a convenience to the user if they want to quickly generate insights. Generally, if the analysis of data subsets (such as certain samples, or condition, etc.) is crucial to a publication, one would likely already be working with fully subsetted seurat objects, and APackOfTheClones functions can be directly applied in those cases. See the corresponding Seurat vignette("essential_commands") for details.

Visually Scaling Circle Sizes

For each seurat cluster at index \(i\), the final radii \(r_{ij}\) of each physical circle at index \(j\) representing clone size \(s_{ij}\) is calculated with a clone size scaling factor \(C \in (0, \infty)\) and a radius scaling factor \(R \in (0, 1]\) with the following formula:

\[ r_{ij} = C \cdot (\sqrt{s_{ij}} - (1 - R)) \]

Intuitively, \(C\) represents how much to enlarge/shrink each radius geometrically relative to the clone size, whereas \(R\) represents the scaled size of the smallest clone’s radius, and all circles will have their radii decreased by that amount. \(R\) defaults to 0.95, whereas \(C\) defaults to an approximated factor based on the number of clones that the package computes. The corresponding arguments are clone_scale_factor and rad_scale_factor in vizAPOTC().

Cluster Repulsion

Considerable visual overlap between clusters (due to the algorithm’s attempt to fit clusters to the original UMAP coordinates) may occur and obstruct eachother excessively. APackOfTheClones by default tries to alleviate this by repulsing overlapping clusters away from eachother. There are four optional arguments:

repulse = TRUE,
repulsion_threshold = 1,
repulsion_strength = 1,
max_repulsion_iter = 10

• repulsion_threshold indicates the amount of ggplot2 units of overlap between clusters that are acceptable. It defaults to 1, meaning that two clusters that overlap by about 1 unit are considered by the repulsion algorithm to not be overlapping. Increasing this number will increase the amount of overlap between clusters, and decreasing this number will do the opposite, while decreasing it to negative values will incur additional spacing between clusters. Note that as of the current version, two clusters are considered overlapping by comparing their approximated radii, which is computed from the right-most x coordinate. This isn’t a very accurate approximation for smaller clusters with non-circular borders.
• repulsion_strength relates to how much the clusters should repel each other. The repulsion algorithm works in iterations, where for each iteration, each cluster “pushes” each other away from eachother by some amount. Increasing this value will cause extra “pushing” during each iteration. However, increasing this factor too much may result once again in a very visually unpleasant plot.
• max_repulsion_iter indicates the number of iterations where clusters should repel eachother. Increasing this number would ensure that clusters will (almost always) for sure not be overlapping. A trick with this parameter to make more pleasant plots is to decrease repulsion_strength and increase max_repulsion_iter to possibly make a more pleasant arrangement of clusters.

For more details on them, read the “Arguments” section in the function documentation. Briefly, first, to make the circle clusters move away from eachother, repulse should be set to TRUE, and the function should be ran AGAIN. (If you feel this excessive re-running takes too long or is inefficient for your workflow in its current form due to a constant need to fine-tune, see the vignette APackOfTheClones-runs.)

Managing the Clone Size Legend

There are the following six parameters to adjust the legend:

add_size_legend = TRUE,
legend_sizes = "auto",
legend_position = "auto",
legend_buffer = 0.2,
legend_color = "#808080",
legend_spacing = "auto",
legend_label = "Clone sizes",
legend_text_size = 5,
add_legend_background = TRUE,

legend_sizes are autogenerated, with at least sizes for clone size 1 and max(clone sizes). The user can also input whichever sizes they wish as a numeric vector. The legend_position on the plot defaults to one of the four corners, whichever will result in the least overlap of the legend with circles present. Otherwise, the user can input manually "top left", "top right", "bottom left" "bottom right, or just a numeric indicating the x and y coordinates of the top leftmost corner of the legend. add_legend_background will display a rectangular background to the legend. The other parameters are less relevant and more details about these arguments can be read in the function documentation.

Note that the functions overlayLegend and removeLegend also exist for adding/removing legends on a readily generated plot.

Other Modifications

A collection of other utility parameters are:

order_clones = TRUE,
try_place = FALSE,
res = 360L,
linetype = "blank",
use_default_theme = TRUE,
retain_axis_scales = FALSE,
show_labels = FALSE,
label_size = 5,

The most important of which are 1. show_labels which overlays the seurat cluster on the plot in the format "Cx" in the center of each relevant cluster. (see vignette("APackOfTheClones-runs") on how one can modify them) 2. use_default_theme which will produce a plot that’s thematically very similar to the dimensional reduction plot, with axis labels and numeric ticks on each axis. This may be helpful for visually indicating certain plot parameters. However, for publications such as this one, as the numeric ticks in APackOfTheClones have no actual biologically relevant meaning aside from approximately matching clusters, it may be beneficial to set this argument to FALSE which will produce a plot with just the circles. The following is an example parameters to generate a plot that is likely publication-ready:

vizAPOTC(
  pbmc,
  repulsion_threshold = 0.9,
  show_labels = TRUE,
  label_size = 3,
  legend_text_size = 3.5,
  add_legend_background = FALSE,
  use_default_theme = FALSE,
  verbose = FALSE
)