# 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"
        )

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

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`):

- `tof_downsample_constant`
- `tof_downsample_prop`
- `tof_downsample_density`

# 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