Dimensionality reduction

Timothy Keyes

2025-06-04

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   3.62   8.21
#> 2   7.89  10.0 
#> 3  29.6   14.3 
#> 4  13.3   18.4 
#> 5   6.57   7.58
#> 6  19.4   13.2

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   2.76  14.7 
#>  2   9.11  12.3 
#>  3  33.3    8.40
#>  4  20.0    7.02
#>  5   5.55  16.1 
#>  6  18.4   18.7 
#>  7  11.0   13.4 
#>  8  17.3   22.9 
#>  9  19.9   11.5 
#> 10   3.96   8.45
#> # ℹ 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 -7.42    6.30 
#>  2 -7.22    5.06 
#>  3 -8.47    1.85 
#>  4 -7.30    0.659
#>  5 -7.13    6.27 
#>  6  0.0417 -3.99 
#>  7 -6.67    6.15 
#>  8 -8.69    1.34 
#>  9 -6.67    0.655
#> 10 -9.00    6.13 
#> # ℹ 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 version 4.5.0 (2025-04-11 ucrt)
#> Platform: x86_64-w64-mingw32/x64
#> Running under: Windows Server 2022 x64 (build 20348)
#> 
#> Matrix products: default
#>   LAPACK version 3.12.1
#> 
#> locale:
#> [1] LC_COLLATE=C                          
#> [2] LC_CTYPE=English_United States.utf8   
#> [3] LC_MONETARY=English_United States.utf8
#> [4] LC_NUMERIC=C                          
#> [5] LC_TIME=English_United States.utf8    
#> 
#> 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.29.0           flowCore_2.21.0            
#>  [5] SummarizedExperiment_1.39.0 Biobase_2.69.0             
#>  [7] GenomicRanges_1.61.0        GenomeInfoDb_1.45.4        
#>  [9] IRanges_2.43.0              S4Vectors_0.47.0           
#> [11] MatrixGenerics_1.21.0       matrixStats_1.5.0          
#> [13] ExperimentHub_2.99.5        AnnotationHub_3.99.5       
#> [15] BiocFileCache_2.99.5        dbplyr_2.5.0               
#> [17] BiocGenerics_0.55.0         generics_0.1.4             
#> [19] forcats_1.0.0               ggplot2_3.5.2              
#> [21] dplyr_1.1.4                 tidytof_1.3.0              
#> 
#> loaded via a namespace (and not attached):
#>   [1] RColorBrewer_1.1-3   jsonlite_2.0.0       shape_1.4.6.1       
#>   [4] magrittr_2.0.3       farver_2.1.2         rmarkdown_2.29      
#>   [7] vctrs_0.6.5          memoise_2.0.1        sparsevctrs_0.3.4   
#>  [10] htmltools_0.5.8.1    S4Arrays_1.9.1       curl_6.2.3          
#>  [13] SparseArray_1.9.0    sass_0.4.10          parallelly_1.45.0   
#>  [16] bslib_0.9.0          httr2_1.1.2          lubridate_1.9.4     
#>  [19] cachem_1.1.0         commonmark_1.9.5     igraph_2.1.4        
#>  [22] mime_0.13            lifecycle_1.0.4      iterators_1.0.14    
#>  [25] pkgconfig_2.0.3      Matrix_1.7-3         R6_2.6.1            
#>  [28] fastmap_1.2.0        future_1.49.0        digest_0.6.37       
#>  [31] AnnotationDbi_1.71.0 irlba_2.3.5.1        RSQLite_2.4.0       
#>  [34] labeling_0.4.3       filelock_1.0.3       cytolib_2.21.0      
#>  [37] yardstick_1.3.2      timechange_0.3.0     httr_1.4.7          
#>  [40] polyclip_1.10-7      abind_1.4-8          compiler_4.5.0      
#>  [43] bit64_4.6.0-1        withr_3.0.2          doParallel_1.0.17   
#>  [46] viridis_0.6.5        DBI_1.2.3            ggforce_0.4.2       
#>  [49] MASS_7.3-65          lava_1.8.1           embed_1.1.5         
#>  [52] rappdirs_0.3.3       DelayedArray_0.35.1  tools_4.5.0         
#>  [55] future.apply_1.11.3  nnet_7.3-20          glue_1.8.0          
#>  [58] grid_4.5.0           Rtsne_0.17           recipes_1.3.1       
#>  [61] gtable_0.3.6         tzdb_0.5.0           class_7.3-23        
#>  [64] data.table_1.17.4    hms_1.1.3            utf8_1.2.5          
#>  [67] tidygraph_1.3.1      XVector_0.49.0       RcppAnnoy_0.0.22    
#>  [70] markdown_2.0         ggrepel_0.9.6        BiocVersion_3.22.0  
#>  [73] foreach_1.5.2        pillar_1.10.2        RcppHNSW_0.6.0      
#>  [76] splines_4.5.0        tweenr_2.0.3         lattice_0.22-7      
#>  [79] survival_3.8-3       bit_4.6.0            RProtoBufLib_2.21.0 
#>  [82] tidyselect_1.2.1     Biostrings_2.77.1    knitr_1.50          
#>  [85] gridExtra_2.3        litedown_0.7         xfun_0.52           
#>  [88] graphlayouts_1.2.2   hardhat_1.4.1        timeDate_4041.110   
#>  [91] stringi_1.8.7        UCSC.utils_1.5.0     yaml_2.3.10         
#>  [94] evaluate_1.0.3       codetools_0.2-20     ggraph_2.2.1        
#>  [97] tibble_3.2.1         BiocManager_1.30.25  cli_3.6.5           
#> [100] uwot_0.2.3           rpart_4.1.24         jquerylib_0.1.4     
#> [103] dichromat_2.0-0.1    Rcpp_1.0.14          globals_0.18.0      
#> [106] png_0.1-8            parallel_4.5.0       gower_1.0.2         
#> [109] readr_2.1.5          blob_1.2.4           listenv_0.9.1       
#> [112] glmnet_4.1-9         viridisLite_0.4.2    ipred_0.9-15        
#> [115] ggridges_0.5.6       scales_1.4.0         prodlim_2025.04.28  
#> [118] purrr_1.0.4          crayon_1.5.3         rlang_1.1.6         
#> [121] KEGGREST_1.49.0