Combining Repertoire with Expression with SingleCellExperiment
24 October 2023
Contents
library(CellaRepertorium)
library(SingleCellExperiment)
#> Loading required package: SummarizedExperiment
#> Loading required package: MatrixGenerics
#> Loading required package: matrixStats
#>
#> Attaching package: 'matrixStats'
#> The following object is masked from 'package:dplyr':
#>
#> count
#>
#> Attaching package: 'MatrixGenerics'
#> The following objects are masked from 'package:matrixStats':
#>
#> colAlls, colAnyNAs, colAnys, colAvgsPerRowSet, colCollapse,
#> colCounts, colCummaxs, colCummins, colCumprods, colCumsums,
#> colDiffs, colIQRDiffs, colIQRs, colLogSumExps, colMadDiffs,
#> colMads, colMaxs, colMeans2, colMedians, colMins, colOrderStats,
#> colProds, colQuantiles, colRanges, colRanks, colSdDiffs, colSds,
#> colSums2, colTabulates, colVarDiffs, colVars, colWeightedMads,
#> colWeightedMeans, colWeightedMedians, colWeightedSds,
#> colWeightedVars, rowAlls, rowAnyNAs, rowAnys, rowAvgsPerColSet,
#> rowCollapse, rowCounts, rowCummaxs, rowCummins, rowCumprods,
#> rowCumsums, rowDiffs, rowIQRDiffs, rowIQRs, rowLogSumExps,
#> rowMadDiffs, rowMads, rowMaxs, rowMeans2, rowMedians, rowMins,
#> rowOrderStats, rowProds, rowQuantiles, rowRanges, rowRanks,
#> rowSdDiffs, rowSds, rowSums2, rowTabulates, rowVarDiffs, rowVars,
#> rowWeightedMads, rowWeightedMeans, rowWeightedMedians,
#> rowWeightedSds, rowWeightedVars
#> Loading required package: GenomicRanges
#> Loading required package: Biobase
#> Welcome to Bioconductor
#>
#> Vignettes contain introductory material; view with
#> 'browseVignettes()'. To cite Bioconductor, see
#> 'citation("Biobase")', and for packages 'citation("pkgname")'.
#>
#> Attaching package: 'Biobase'
#> The following object is masked from 'package:MatrixGenerics':
#>
#> rowMedians
#> The following objects are masked from 'package:matrixStats':
#>
#> anyMissing, rowMedians
library(dplyr)
library(ggplot2)
library(readr)
library(tidyr)
library(stringr)
library(purrr)It is possible to combine ContigCellDB objects with SingleCellExperiment objects that measure overlapping barcodes. We choose to include the ContigCellDB object as a member of the colData. In this way, it is possible to include different cellular “views” of the repertoire, such as the alpha chain and beta chain properties, as well as the paired clonotypes.
1 “Load” expression
First we’ll cook up some single cell expression data.
set.seed(1345)
data(ccdb_ex)
barcodes = ccdb_ex$cell_tbl[ccdb_ex$cell_pk]
# Take a subsample of almost all of the barcdes
barcodes = barcodes[sample(nrow(barcodes), nrow(barcodes) - 5),]
samples = unique(ccdb_ex$cell_tbl[setdiff(ccdb_ex$cell_pk, 'barcode')])
# For each sample, generate 0-100 "extra" barcodes for which only 5' expression is recovered
extra = samples %>% rowwise() %>% mutate(extrabc = {
extra_bc = floor(runif(1, 0, 100))
list(tibble(barcode = paste0('barcode', seq_len(extra_bc))))
})
extra = extra %>% unnest(cols = c(extrabc))
all_bc = bind_rows(extra, barcodes)Simulate some “cells” and “genes” that nearly form a superset of the cells for which repertoire are available. This is generally true if no barcode filters have been applied to the expression data. In practice a few cells may have repertoire but not expression (or fail QC for expression). We will work with the intersection of these cells.
genes = 200
cells = nrow(all_bc)
array_size = genes*cells
expression = matrix(rnbinom(array_size, size = 5, mu = 3), nrow = genes, ncol = cells)
sce = SingleCellExperiment(assay = list(counts = expression), colData = all_bc)2 Remake the ContigCellDB with empty cells
ccdb2 = ccdb_join(sce, ccdb_ex)
ccdb2 = cdhit_ccdb(ccdb2, 'cdr3', type = 'AA', cluster_pk = 'aa80', identity = .8, min_length = 5)
ccdb2 = fine_clustering(ccdb2, sequence_key = 'cdr3', type = 'AA', keep_clustering_details = FALSE)
#> Calculating intradistances on 993 clusters.
#> SummarizingThe ccdb_join(template, ccdb) function does a left join of the template onto the cell_tbl of the ccdb. This will ensure that the cell_tbl is expanded and ordered properly to mesh with sce when we add it below.
3 Chain pairings
colData(sce)$alpha = canonicalize_cell(ccdb2, chain == 'TRA', contig_fields = c('chain', 'v_gene','d_gene', 'j_gene', 'aa80'))
colData(sce)$beta = canonicalize_cell(ccdb2, chain == 'TRB', contig_fields = c('chain', 'v_gene','d_gene', 'j_gene', 'aa80'))
colData(sce)$pairing = enumerate_pairing(ccdb2, chain_recode_fun = 'guess')We can add multiple views, represented as fields in the colData(sce) of the repertoire.
4 Visualization of TCR features with Scater
We can leverage Scater’s ability to use “nested” data frames to visualize TCR features.
library(scater)
#> Loading required package: scuttle
sce = logNormCounts(sce)
sce = runPCA(sce)
plotReducedDim(sce, dimred = 'PCA', colour_by = I(sce$pairing$pairing), point_alpha = 1)
Here we calculate the first two principal components (which aren’t very interesting because these are simulated data without any special structure), and then visualize if the TCR was paired or not.
only_paired = sce[,which(sce$pairing$pairing == 'paired')]
plotReducedDim(only_paired, dimred = 'PCA', colour_by = I(only_paired$alpha$j_gene), point_alpha = 1)
#> Warning: Removed 328 rows containing missing values (`geom_point()`).
plotReducedDim(only_paired, dimred = 'PCA', colour_by = I(only_paired$beta$j_gene), point_alpha = 1)
Since the ContigCellDB is nested within the SingleCellExperiment it automatically gets subsetted appropriately when the parent object is subsetted. Enough data.frame-like semantics have been implemented so that fields from the cell_tbl can be visualized.
5 Colophone
sessionInfo()
#> R version 4.3.1 (2023-06-16)
#> Platform: x86_64-pc-linux-gnu (64-bit)
#> Running under: Ubuntu 22.04.3 LTS
#>
#> Matrix products: default
#> BLAS: /home/biocbuild/bbs-3.18-bioc/R/lib/libRblas.so
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_GB LC_COLLATE=C
#> [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
#> [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
#> [9] LC_ADDRESS=C LC_TELEPHONE=C
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
#>
#> time zone: America/New_York
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats4 stats graphics grDevices utils datasets methods
#> [8] base
#>
#> other attached packages:
#> [1] scater_1.30.0 scuttle_1.12.0
#> [3] SingleCellExperiment_1.24.0 SummarizedExperiment_1.32.0
#> [5] Biobase_2.62.0 GenomicRanges_1.54.0
#> [7] MatrixGenerics_1.14.0 matrixStats_1.0.0
#> [9] Biostrings_2.70.0 GenomeInfoDb_1.38.0
#> [11] IRanges_2.36.0 S4Vectors_0.40.0
#> [13] BiocGenerics_0.48.0 ggdendro_0.1.23
#> [15] XVector_0.42.0 purrr_1.0.2
#> [17] stringr_1.5.0 tidyr_1.3.0
#> [19] readr_2.1.4 ggplot2_3.4.4
#> [21] dplyr_1.1.3 CellaRepertorium_1.12.0
#> [23] BiocStyle_2.30.0
#>
#> loaded via a namespace (and not attached):
#> [1] bitops_1.0-7 gridExtra_2.3
#> [3] rlang_1.1.1 magrittr_2.0.3
#> [5] furrr_0.3.1 compiler_4.3.1
#> [7] DelayedMatrixStats_1.24.0 vctrs_0.6.4
#> [9] reshape2_1.4.4 pkgconfig_2.0.3
#> [11] crayon_1.5.2 fastmap_1.1.1
#> [13] backports_1.4.1 magick_2.8.1
#> [15] labeling_0.4.3 utf8_1.2.4
#> [17] rmarkdown_2.25 tzdb_0.4.0
#> [19] ggbeeswarm_0.7.2 nloptr_2.0.3
#> [21] bit_4.0.5 xfun_0.40
#> [23] beachmat_2.18.0 zlibbioc_1.48.0
#> [25] cachem_1.0.8 jsonlite_1.8.7
#> [27] progress_1.2.2 DelayedArray_0.28.0
#> [29] BiocParallel_1.36.0 irlba_2.3.5.1
#> [31] broom_1.0.5 parallel_4.3.1
#> [33] prettyunits_1.2.0 R6_2.5.1
#> [35] bslib_0.5.1 stringi_1.7.12
#> [37] RColorBrewer_1.1-3 parallelly_1.36.0
#> [39] boot_1.3-28.1 jquerylib_0.1.4
#> [41] Rcpp_1.0.11 bookdown_0.36
#> [43] knitr_1.44 Matrix_1.6-1.1
#> [45] splines_4.3.1 tidyselect_1.2.0
#> [47] viridis_0.6.4 abind_1.4-5
#> [49] yaml_2.3.7 codetools_0.2-19
#> [51] listenv_0.9.0 lattice_0.22-5
#> [53] tibble_3.2.1 plyr_1.8.9
#> [55] withr_2.5.1 evaluate_0.22
#> [57] archive_1.1.6 future_1.33.0
#> [59] pillar_1.9.0 BiocManager_1.30.22
#> [61] generics_0.1.3 vroom_1.6.4
#> [63] RCurl_1.98-1.12 hms_1.1.3
#> [65] sparseMatrixStats_1.14.0 munsell_0.5.0
#> [67] scales_1.2.1 minqa_1.2.6
#> [69] globals_0.16.2 glue_1.6.2
#> [71] tools_4.3.1 BiocNeighbors_1.20.0
#> [73] ScaledMatrix_1.10.0 lme4_1.1-34
#> [75] forcats_1.0.0 cowplot_1.1.1
#> [77] grid_4.3.1 colorspace_2.1-0
#> [79] nlme_3.1-163 GenomeInfoDbData_1.2.11
#> [81] beeswarm_0.4.0 BiocSingular_1.18.0
#> [83] vipor_0.4.5 rsvd_1.0.5
#> [85] cli_3.6.1 fansi_1.0.5
#> [87] viridisLite_0.4.2 S4Arrays_1.2.0
#> [89] gtable_0.3.4 broom.mixed_0.2.9.4
#> [91] sass_0.4.7 digest_0.6.33
#> [93] ggrepel_0.9.4 SparseArray_1.2.0
#> [95] farver_2.1.1 htmltools_0.5.6.1
#> [97] lifecycle_1.0.3 bit64_4.0.5
#> [99] MASS_7.3-60