Downsampling

Timothy Keyes

2025-06-04

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

count <- dplyr::count

Often, high-dimensional cytometry experiments collect tens or hundreds or millions of cells in total, and it can be useful to downsample to a smaller, more computationally tractable number of cells - either for a final analysis or while developing code.

To do this, {tidytof} implements the tof_downsample() verb, which allows downsampling using 3 methods: downsampling to an integer number of cells, downsampling to a fixed proportion of the total number of input cells, or downsampling to a fixed cellular density in phenotypic space.

Downsampling with tof_downsample()

Using {tidytof}’s built-in dataset phenograph_data, we can see that the original size of the dataset is 1000 cells per cluster, or 3000 cells in total:

data(phenograph_data)

phenograph_data |>
    dplyr::count(phenograph_cluster)
#> # A tibble: 3 × 2
#>   phenograph_cluster     n
#>   <chr>              <int>
#> 1 cluster1            1000
#> 2 cluster2            1000
#> 3 cluster3            1000

To randomly sample 200 cells per cluster, we can use tof_downsample() using the “constant” method:

phenograph_data |>
    # downsample
    tof_downsample(
        group_cols = phenograph_cluster,
        method = "constant",
        num_cells = 200
    ) |>
    # count the number of downsampled cells in each cluster
    count(phenograph_cluster)
#> # A tibble: 3 × 2
#>   phenograph_cluster     n
#>   <chr>              <int>
#> 1 cluster1             200
#> 2 cluster2             200
#> 3 cluster3             200

Alternatively, if we wanted to sample 50% of the cells in each cluster, we could use the “prop” method:

phenograph_data |>
    # downsample
    tof_downsample(
        group_cols = phenograph_cluster,
        method = "prop",
        prop_cells = 0.5
    ) |>
    # count the number of downsampled cells in each cluster
    count(phenograph_cluster)
#> # A tibble: 3 × 2
#>   phenograph_cluster     n
#>   <chr>              <int>
#> 1 cluster1             500
#> 2 cluster2             500
#> 3 cluster3             500

And finally, we might also be interested in taking a slightly different approach to downsampling that reduces the number of cells not to a fixed constant or proportion, but to a fixed density in phenotypic space. For example, the following scatterplot demonstrates that there are certain areas of phenotypic density in phenograph_data that contain more cells than others along the cd34/cd38 axes:

rescale_max <-
    function(x, to = c(0, 1), from = range(x, na.rm = TRUE)) {
        x / from[2] * to[2]
    }

phenograph_data |>
    # preprocess all numeric columns in the dataset
    tof_preprocess(undo_noise = FALSE) |>
    # plot
    ggplot(aes(x = cd34, y = cd38)) +
    geom_hex() +
    coord_fixed(ratio = 0.4) +
    scale_x_continuous(limits = c(NA, 1.5)) +
    scale_y_continuous(limits = c(NA, 4)) +
    scale_fill_viridis_c(
        labels = function(x) round(rescale_max(x), 2)
    ) +
    labs(
        fill = "relative density"
    )

plot of chunk unnamed-chunk-5

To reduce the number of cells in our dataset until the local density around each cell in our dataset is relatively constant, we can use the “density” method of tof_downsample:

phenograph_data |>
    tof_preprocess(undo_noise = FALSE) |>
    tof_downsample(method = "density", density_cols = c(cd34, cd38)) |>
    # plot
    ggplot(aes(x = cd34, y = cd38)) +
    geom_hex() +
    coord_fixed(ratio = 0.4) +
    scale_x_continuous(limits = c(NA, 1.5)) +
    scale_y_continuous(limits = c(NA, 4)) +
    scale_fill_viridis_c(
        labels = function(x) round(rescale_max(x), 2)
    ) +
    labs(
        fill = "relative density"
    )

plot of chunk unnamed-chunk-6

Thus, we can see that the density after downsampling is more uniform (though not exactly uniform) across the range of cd34/cd38 values in phenograph_data.

Additional documentation

For more details, check out the documentation for the 3 underlying members of the tof_downsample_* function family (which are wrapped by tof_downsample):

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            hexbin_1.28.5       
#>  [49] ggforce_0.4.2        MASS_7.3-65          lava_1.8.1          
#>  [52] embed_1.1.5          rappdirs_0.3.3       DelayedArray_0.35.1 
#>  [55] tools_4.5.0          future.apply_1.11.3  nnet_7.3-20         
#>  [58] glue_1.8.0           grid_4.5.0           Rtsne_0.17          
#>  [61] recipes_1.3.1        gtable_0.3.6         tzdb_0.5.0          
#>  [64] class_7.3-23         data.table_1.17.4    hms_1.1.3           
#>  [67] utf8_1.2.5           tidygraph_1.3.1      XVector_0.49.0      
#>  [70] RcppAnnoy_0.0.22     markdown_2.0         ggrepel_0.9.6       
#>  [73] BiocVersion_3.22.0   foreach_1.5.2        pillar_1.10.2       
#>  [76] RcppHNSW_0.6.0       splines_4.5.0        tweenr_2.0.3        
#>  [79] lattice_0.22-7       survival_3.8-3       bit_4.6.0           
#>  [82] RProtoBufLib_2.21.0  tidyselect_1.2.1     Biostrings_2.77.1   
#>  [85] knitr_1.50           gridExtra_2.3        litedown_0.7        
#>  [88] xfun_0.52            graphlayouts_1.2.2   hardhat_1.4.1       
#>  [91] timeDate_4041.110    stringi_1.8.7        UCSC.utils_1.5.0    
#>  [94] yaml_2.3.10          evaluate_1.0.3       codetools_0.2-20    
#>  [97] ggraph_2.2.1         tibble_3.2.1         BiocManager_1.30.25 
#> [100] cli_3.6.5            uwot_0.2.3           rpart_4.1.24        
#> [103] jquerylib_0.1.4      dichromat_2.0-0.1    Rcpp_1.0.14         
#> [106] globals_0.18.0       png_0.1-8            parallel_4.5.0      
#> [109] gower_1.0.2          readr_2.1.5          blob_1.2.4          
#> [112] listenv_0.9.1        glmnet_4.1-9         viridisLite_0.4.2   
#> [115] ipred_0.9-15         ggridges_0.5.6       scales_1.4.0        
#> [118] prodlim_2025.04.28   purrr_1.0.4          crayon_1.5.3        
#> [121] rlang_1.1.6          KEGGREST_1.49.0