Dimensionality reduction

Timothy Keyes

2024-11-22

library(tidytof)
library(dplyr)
library(ggplot2)

A useful tool for visualizing the phenotypic relationships between single cells and clusters of cells is dimensionality reduction, a form of unsupervised machine learning used to represent high-dimensional datasets in a smaller number of dimensions.

{tidytof} includes several dimensionality reduction algorithms commonly used by biologists: Principal component analysis (PCA), t-distributed stochastic neighbor embedding (tSNE), and uniform manifold approximation and projection (UMAP). To apply these to a dataset, use tof_reduce_dimensions().

Dimensionality reduction with tof_reduce_dimensions().

Here is an example call to tof_reduce_dimensions() in which we use tSNE to visualize data in {tidytof}’s built-in phenograph_data dataset.

data(phenograph_data)

# perform the dimensionality reduction
phenograph_tsne <-
    phenograph_data |>
    tof_preprocess() |>
    tof_reduce_dimensions(method = "tsne")
#> Loading required namespace: Rtsne

# select only the tsne embedding columns
phenograph_tsne |>
    select(contains("tsne")) |>
    head()
#> # A tibble: 6 × 2
#>   .tsne1 .tsne2
#>    <dbl>  <dbl>
#> 1  -12.0 -13.5 
#> 2  -11.1  -1.65
#> 3  -26.7  13.8 
#> 4  -20.0  -2.42
#> 5  -17.9 -11.3 
#> 6  -21.3   3.39

By default, tof_reduce_dimensions will add reduced-dimension feature embeddings to the input tof_tbl and return the augmented tof_tbl (that is, a tof_tbl with new columns for each embedding dimension) as its result. To return only the features embeddings themselves, set augment to FALSE (as in tof_cluster).

phenograph_data |>
    tof_preprocess() |>
    tof_reduce_dimensions(method = "tsne", augment = FALSE)
#> # A tibble: 3,000 × 2
#>    .tsne1 .tsne2
#>     <dbl>  <dbl>
#>  1  19.0    4.27
#>  2   9.83  -3.54
#>  3  30.8  -17.1 
#>  4  19.2   -8.72
#>  5  21.9    1.22
#>  6  15.5  -15.5 
#>  7  10.4   -5.48
#>  8  23.1  -17.8 
#>  9  15.4  -11.9 
#> 10  10.1    1.84
#> # ℹ 2,990 more rows

Changing the method argument results in different low-dimensional embeddings:

phenograph_data |>
    tof_reduce_dimensions(method = "umap", augment = FALSE)
#> # A tibble: 3,000 × 2
#>    .umap1 .umap2
#>     <dbl>  <dbl>
#>  1 -9.69   3.34 
#>  2 -8.64   2.72 
#>  3 -2.60  -0.650
#>  4 -5.52  -0.317
#>  5 -9.77   3.03 
#>  6 -0.249 -2.62 
#>  7 -9.82   2.59 
#>  8 -2.04  -1.18 
#>  9 -6.21   0.215
#> 10 -8.60   4.97 
#> # ℹ 2,990 more rows

phenograph_data |>
    tof_reduce_dimensions(method = "pca", augment = FALSE)
#> # A tibble: 3,000 × 5
#>       .pc1     .pc2   .pc3    .pc4   .pc5
#>      <dbl>    <dbl>  <dbl>   <dbl>  <dbl>
#>  1 -2.77    1.23    -0.868  0.978   3.49 
#>  2 -0.969  -1.02    -0.787  1.22    0.329
#>  3 -2.36    2.54    -1.95  -0.882  -1.30 
#>  4 -3.68   -0.00565  0.962  0.410   0.788
#>  5 -4.03    2.07    -0.829  1.59    5.39 
#>  6 -2.59   -0.108    1.32  -1.41   -1.24 
#>  7 -1.55   -0.651   -0.233  1.08    0.129
#>  8 -1.18   -0.446    0.134 -0.771  -0.932
#>  9 -2.00   -0.485    0.593 -0.0416 -0.658
#> 10 -0.0356 -0.924   -0.692  1.45    0.270
#> # ℹ 2,990 more rows

Method specifications for tof_reduce_*() functions

tof_reduce_dimensions() provides a high-level API for three lower-level functions: tof_reduce_pca(), tof_reduce_umap(), and tof_reduce_tsne(). The help files for each of these functions provide details about the algorithm-specific method specifications associated with each of these dimensionality reduction approaches. For example, tof_reduce_pca takes the num_comp argument to determine how many principal components should be returned:

# 2 principal components
phenograph_data |>
    tof_reduce_pca(num_comp = 2)
#> # A tibble: 3,000 × 2
#>       .pc1     .pc2
#>      <dbl>    <dbl>
#>  1 -2.77    1.23   
#>  2 -0.969  -1.02   
#>  3 -2.36    2.54   
#>  4 -3.68   -0.00565
#>  5 -4.03    2.07   
#>  6 -2.59   -0.108  
#>  7 -1.55   -0.651  
#>  8 -1.18   -0.446  
#>  9 -2.00   -0.485  
#> 10 -0.0356 -0.924  
#> # ℹ 2,990 more rows
# 3 principal components
phenograph_data |>
    tof_reduce_pca(num_comp = 3)
#> # A tibble: 3,000 × 3
#>       .pc1     .pc2   .pc3
#>      <dbl>    <dbl>  <dbl>
#>  1 -2.77    1.23    -0.868
#>  2 -0.969  -1.02    -0.787
#>  3 -2.36    2.54    -1.95 
#>  4 -3.68   -0.00565  0.962
#>  5 -4.03    2.07    -0.829
#>  6 -2.59   -0.108    1.32 
#>  7 -1.55   -0.651   -0.233
#>  8 -1.18   -0.446    0.134
#>  9 -2.00   -0.485    0.593
#> 10 -0.0356 -0.924   -0.692
#> # ℹ 2,990 more rows

see ?tof_reduce_pca, ?tof_reduce_umap, and ?tof_reduce_tsne for additional details.

Visualization using tof_plot_cells_embedding()

Regardless of the method used, reduced-dimension feature embeddings can be visualized using {ggplot2} (or any graphics package). {tidytof} also provides some helper functions for easily generating dimensionality reduction plots from a tof_tbl or tibble with columns representing embedding dimensions:

# plot the tsne embeddings using color to distinguish between clusters
phenograph_tsne |>
    tof_plot_cells_embedding(
        embedding_cols = contains(".tsne"),
        color_col = phenograph_cluster
    )

plot of chunk unnamed-chunk-7


# plot the tsne embeddings using color to represent CD11b expression
phenograph_tsne |>
    tof_plot_cells_embedding(
        embedding_cols = contains(".tsne"),
        color_col = cd11b
    ) +
    ggplot2::scale_fill_viridis_c()

plot of chunk unnamed-chunk-7

Such visualizations can be helpful in qualitatively describing the phenotypic differences between the clusters in a dataset. For example, in the example above, we can see that one of the clusters has high CD11b expression, whereas the others have lower CD11b expression.

Session info

sessionInfo()
#> R Under development (unstable) (2024-11-20 r87352)
#> Platform: x86_64-apple-darwin20
#> Running under: macOS Monterey 12.7.6
#> 
#> Matrix products: default
#> BLAS:   /Library/Frameworks/R.framework/Versions/4.5-x86_64/Resources/lib/libRblas.0.dylib 
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.5-x86_64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.0
#> 
#> locale:
#> [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
#> 
#> time zone: America/New_York
#> tzcode source: internal
#> 
#> attached base packages:
#> [1] stats4    stats     graphics  grDevices utils     datasets  methods  
#> [8] base     
#> 
#> other attached packages:
#>  [1] tidyr_1.3.1                 stringr_1.5.1              
#>  [3] HDCytoData_1.27.0           flowCore_2.19.0            
#>  [5] SummarizedExperiment_1.37.0 Biobase_2.67.0             
#>  [7] GenomicRanges_1.59.1        GenomeInfoDb_1.43.1        
#>  [9] IRanges_2.41.1              S4Vectors_0.45.2           
#> [11] MatrixGenerics_1.19.0       matrixStats_1.4.1          
#> [13] ExperimentHub_2.15.0        AnnotationHub_3.15.0       
#> [15] BiocFileCache_2.15.0        dbplyr_2.5.0               
#> [17] BiocGenerics_0.53.3         generics_0.1.3             
#> [19] forcats_1.0.0               ggplot2_3.5.1              
#> [21] dplyr_1.1.4                 tidytof_1.1.0              
#> 
#> loaded via a namespace (and not attached):
#>   [1] jsonlite_1.8.9          shape_1.4.6.1           magrittr_2.0.3         
#>   [4] farver_2.1.2            rmarkdown_2.29          zlibbioc_1.53.0        
#>   [7] vctrs_0.6.5             memoise_2.0.1           htmltools_0.5.8.1      
#>  [10] S4Arrays_1.7.1          curl_6.0.1              SparseArray_1.7.2      
#>  [13] sass_0.4.9              parallelly_1.39.0       bslib_0.8.0            
#>  [16] lubridate_1.9.3         cachem_1.1.0            commonmark_1.9.2       
#>  [19] igraph_2.1.1            mime_0.12               lifecycle_1.0.4        
#>  [22] iterators_1.0.14        pkgconfig_2.0.3         Matrix_1.7-1           
#>  [25] R6_2.5.1                fastmap_1.2.0           GenomeInfoDbData_1.2.13
#>  [28] future_1.34.0           digest_0.6.37           colorspace_2.1-1       
#>  [31] AnnotationDbi_1.69.0    irlba_2.3.5.1           RSQLite_2.3.8          
#>  [34] labeling_0.4.3          filelock_1.0.3          cytolib_2.19.0         
#>  [37] fansi_1.0.6             yardstick_1.3.1         timechange_0.3.0       
#>  [40] httr_1.4.7              polyclip_1.10-7         abind_1.4-8            
#>  [43] compiler_4.5.0          bit64_4.5.2             withr_3.0.2            
#>  [46] doParallel_1.0.17       viridis_0.6.5           DBI_1.2.3              
#>  [49] ggforce_0.4.2           MASS_7.3-61             lava_1.8.0             
#>  [52] embed_1.1.4             rappdirs_0.3.3          DelayedArray_0.33.2    
#>  [55] tools_4.5.0             future.apply_1.11.3     nnet_7.3-19            
#>  [58] glue_1.8.0              grid_4.5.0              Rtsne_0.17             
#>  [61] recipes_1.1.0           gtable_0.3.6            tzdb_0.4.0             
#>  [64] class_7.3-22            data.table_1.16.2       hms_1.1.3              
#>  [67] tidygraph_1.3.1         utf8_1.2.4              XVector_0.47.0         
#>  [70] RcppAnnoy_0.0.22        markdown_1.13           ggrepel_0.9.6          
#>  [73] BiocVersion_3.21.1      foreach_1.5.2           pillar_1.9.0           
#>  [76] RcppHNSW_0.6.0          splines_4.5.0           tweenr_2.0.3           
#>  [79] lattice_0.22-6          survival_3.7-0          bit_4.5.0              
#>  [82] RProtoBufLib_2.19.0     tidyselect_1.2.1        Biostrings_2.75.1      
#>  [85] knitr_1.49              gridExtra_2.3           xfun_0.49              
#>  [88] graphlayouts_1.2.1      hardhat_1.4.0           timeDate_4041.110      
#>  [91] stringi_1.8.4           UCSC.utils_1.3.0        yaml_2.3.10            
#>  [94] evaluate_1.0.1          codetools_0.2-20        ggraph_2.2.1           
#>  [97] tibble_3.2.1            BiocManager_1.30.25     cli_3.6.3              
#> [100] uwot_0.2.2              rpart_4.1.23            munsell_0.5.1          
#> [103] jquerylib_0.1.4         Rcpp_1.0.13-1           globals_0.16.3         
#> [106] png_0.1-8               parallel_4.5.0          gower_1.0.1            
#> [109] readr_2.1.5             blob_1.2.4              listenv_0.9.1          
#> [112] glmnet_4.1-8            viridisLite_0.4.2       ipred_0.9-15           
#> [115] ggridges_0.5.6          scales_1.3.0            prodlim_2024.06.25     
#> [118] purrr_1.0.2             crayon_1.5.3            rlang_1.1.4            
#> [121] KEGGREST_1.47.0