# Downsampling

## Timothy Keyes

### 2025-04-16

    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 RC (2025-04-04 r88126 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.27.0           flowCore_2.20.0
    #>  [5] SummarizedExperiment_1.38.0 Biobase_2.68.0
    #>  [7] GenomicRanges_1.60.0        GenomeInfoDb_1.44.0
    #>  [9] IRanges_2.42.0              S4Vectors_0.46.0
    #> [11] MatrixGenerics_1.20.0       matrixStats_1.5.0
    #> [13] ExperimentHub_2.16.0        AnnotationHub_3.16.0
    #> [15] BiocFileCache_2.16.0        dbplyr_2.5.0
    #> [17] BiocGenerics_0.54.0         generics_0.1.3
    #> [19] forcats_1.0.0               ggplot2_3.5.2
    #> [21] dplyr_1.1.4                 tidytof_1.2.0
    #>
    #> loaded via a namespace (and not attached):
    #>   [1] jsonlite_2.0.0          shape_1.4.6.1           magrittr_2.0.3
    #>   [4] farver_2.1.2            rmarkdown_2.29          vctrs_0.6.5
    #>   [7] memoise_2.0.1           sparsevctrs_0.3.3       htmltools_0.5.8.1
    #>  [10] S4Arrays_1.8.0          curl_6.2.2              SparseArray_1.8.0
    #>  [13] sass_0.4.10             parallelly_1.43.0       bslib_0.9.0
    #>  [16] lubridate_1.9.4         cachem_1.1.0            commonmark_1.9.5
    #>  [19] igraph_2.1.4            mime_0.13               lifecycle_1.0.4
    #>  [22] iterators_1.0.14        pkgconfig_2.0.3         Matrix_1.7-3
    #>  [25] R6_2.6.1                fastmap_1.2.0           GenomeInfoDbData_1.2.14
    #>  [28] future_1.40.0           digest_0.6.37           colorspace_2.1-1
    #>  [31] AnnotationDbi_1.70.0    irlba_2.3.5.1           RSQLite_2.3.9
    #>  [34] labeling_0.4.3          filelock_1.0.3          cytolib_2.20.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.34.0
    #>  [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.2.1           gtable_0.3.6            tzdb_0.5.0
    #>  [64] class_7.3-23            data.table_1.17.0       hms_1.1.3
    #>  [67] utf8_1.2.4              tidygraph_1.3.1         XVector_0.48.0
    #>  [70] RcppAnnoy_0.0.22        markdown_2.0            ggrepel_0.9.6
    #>  [73] BiocVersion_3.21.1      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.20.0     tidyselect_1.2.1        Biostrings_2.76.0
    #>  [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.4.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.4               uwot_0.2.3              rpart_4.1.24
    #> [103] munsell_0.5.1           jquerylib_0.1.4         Rcpp_1.0.14
    #> [106] globals_0.16.3          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-8            viridisLite_0.4.2
    #> [115] ipred_0.9-15            ggridges_0.5.6          scales_1.3.0
    #> [118] prodlim_2024.06.25      purrr_1.0.4             crayon_1.5.3
    #> [121] rlang_1.1.6             KEGGREST_1.48.0