APackOfTheClones is an R package that extends the Bioconductor scRepertoire package to produce easily customizable "ball-packing" visualizations of the clonal expansion of T-cells/B-cells in a Seurat object, based on its receptor library and single cell RNA sequencing data (for example outputs from 10X genomics' single-cell immune profiling).
The baseline concept was first implemented in a study Ma et al.[1] by Murray Christian and Ben Murrell (@Murrellb) for nasal polyp APackOfTheClones counts the clonotype frequencies for each seurat/umap cluster and produces a circle packing of the frequencies to intuitively represent clonal expansion. The packing for each cluster are then plotted with roughly the same coordinates as the original dimensional reduction and color. Below is an example of APackOfTheClones being used on an example seurat object for scRepertoire with its corresponding VDJ library:
APackOfTheClones is registered on CRAN. To install the latest stable release, simply run the following
install.packages("APackOfTheClones")For more details on installation methods and information on alternative/development versions, see vignette("APackOfTheClones-install")
The package extends the functionality of scRepertoire v2 by working with a seurat object's corresponding T/B cell receptor library. To do this, read the scRepertoire vignette. Briefly, an scTCR-seq/scBCR-seq experiment (e.g. from a 10X genomics single cell immune profiling run) should be processed with scRepertoire::combineTCR / scRepertoire::combineBCR first. Then, it should be integrated into the corresponding seurat object either with scRepertoire::combineExpression.
To quickly produce the visualization, the vizAPOTC(your_combined_seurat_object) should give a reasonable visualization. There is an example seurat object included in the package which can be used with data("combined_pbmc"). The following code chunk is an example of how it can be done:
library(Seurat)
library(scRepertoire) # ensure v2 is installed: devtools::install_github("ncborcherding/scRepertoire")
library(APackOfTheClones)
# integrate the contigs with scRepertoire example data - this is identical to "combined_pbmc"
pbmc <- get(data("mini_contig_list", package = "scRepertoire")) %>%
combineTCR(
samples = c("P17B", "P17L", "P18B", "P18L", "P19B", "P19L", "P20B", "P20L")
) %>%
combineExpression(get(data("scRep_example", package = "scRepertoire")))
# produce the ball-packing plot with the default parameters
vizAPOTC(pbmc)
# there are many parameters to adjust, but most importantly, one can filter for
# subsets of the seurat object easily with keyword arguments corresponding to
# columns in the meta.data dataframe in the seurat object. Here, we filter for
# only the clones of the sample "P17" in a column named "orig.ident" that are only
# in seurat clusters 1, 3, and 4.
vizAPOTC(pbmc, orig.ident = c("P17B", "P17L"), seurat_clusters = c(1, 3, 4))Additional features and use-cases are covered in the vignettes and documentation, including options to store separate runs with different parameters on the same seurat object, highlighting clonotypes, getting shared clonotypes across clusters, displaying links between them, and more.
Most exported functions are named with camelCase with the exception of those that modify Seurat objects having PascalCase to mimic their conventions. All function arguments follow snake_case.
If you use APackOfTheClones in your work, please cite the corresponding publication with the output of citation("APackOfTheClones"):
Yang, Q., (2024). APackOfTheClones: Visualization of clonal expansion with circle packing. Journal of Open Source Software, 9(103), 6868, https://doi.org/10.21105/joss.06868
Comprehensive documentation, vignettes, and a changelog is deployed at https://qile0317.github.io/APackOfTheClones/
There are also the following vignettes that should be read in the following order:
vignette("APackOfTheClones")vignette("APackOfTheClones-runs")vignette("APackOfTheClones-shared")vignette("APackOfTheClones-utils")
All exported functions have function level documentation.
Github pull requests from forked branches are more than welcome as it is mostly a solo-project at the moment. For major changes, please open an issue first to discuss what you would like to change. Please also make sure to update tests as appropriate.
Qile Yang - qile [dot] yang [at] berkeley.edu
[1] Ma, J., Tibbitt, C. A., Georén, S. K., Christian, M., Murrell, B., Cardell, L. O., Bachert, C., & Coquet, J. M. (2021). Single-cell analysis pinpoints distinct populations of cytotoxic CD4+ T cells and an IL-10+CD109+ TH2 cell population in nasal polyps. Science immunology, 6(62), eabg6356. https://doi.org/10.1126/sciimmunol.abg6356
Thanks for Ben Murrell (@murrelb) at the Karolinska Institute for introducing the idea, implementing julia code, debug support, and giving suggestions. Thanks to Nick Borcherding (@ncborcherding) for providing more insights, suggestions, and promoting the package.