APackOfTheClones

<!-- badges: end -->

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).

This package's visualization counts the clonotype frequencies for each cell cluster and produces a circle packing for each cluster of the frequencies to intuitively represent clonal expansion. The packing for each cluster are then plotted with roughly the same coordinates as a dimensional reduction plot of each cell. Below is an example of APackOfTheClones being used on an example seurat object for scRepertoire with its corresponding VDJ library:

The baseline concept was first implemented in a study Ma et al.[1] by Murray Christian and Ben Murrell for nasal polyp $T_{H}$ cells.

Installation

APackOfTheClones is registered on CRAN. To install the latest stable release, simply run the following

R install.packages("APackOfTheClones")

For more details/info on alternative/development versions, see vignette("APackOfTheClones-install")

Usage

Clonal visualizations are created from a user-defined clonotype column in the metadata, along with a user-defined dimensional reduction from a Seurat Object. To get clonotypes, users can use their own column or read the scRepertoire vignette for a tutorial on how to integrate real data. 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:

```R 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("minicontiglist", 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.

Package conventions

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.

Please Cite

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

Documentation

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.

Contributing

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.

Contact

Qile Yang - qile [dot] yang [at] berkeley.edu

References

[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

Acknowledgements

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.