The waddR package

# The `waddR` package

## Introduction

The `waddR` package offers statistical tests based on the 2-Wasserstein distance for detecting and characterizing differences between two distributions given in the form of samples. Functions for calculating the 2-Wasserstein distance and testing for differential distributions are provided, as well as a specifically tailored test for differential expression in single-cell RNA sequencing data.

`waddR` provides tools to address the following tasks, each described in a separate vignette:

- Calculation of the 2-Wasserstein distance,

- Two-sample tests to check for differences between two distributions,

- Detection of differential gene expression distributions in single-cell RNA sequencing (scRNAseq) data.

These are bundled into one package, because they are internally dependent: The procedure for detecting differential distributions in scRNAseq data is an adaptation of the general two-sample test, which itself uses the 2-Wasserstein distance to compare two distributions.

### 2-Wasserstein distance functions

The 2-Wasserstein distance is a metric to describe the distance between two distributions, representing e.g. two diferent conditions \(A\) and \(B\). The `waddR` package specifically considers the squared 2-Wasserstein distance which can be decomposed into location, size, and shape terms, thus providing a characterization of potential differences.

The `waddR` package offers three functions to calculate the (squared) 2-Wasserstein distance, which are implemented in C++ and exported to R with Rcpp for faster computation. The function `wasserstein_metric` is a Cpp reimplementation of the `wasserstein1d` function from the R package `transport`. The functions `squared_wass_approx` and `squared_wass_decomp` compute approximations of the squared 2-Wasserstein distance, with `squared_wass_decomp` also returning the decomposition terms for location, size, and shape.

See `?wasserstein_metric`, `?squared_wass_aprox`, and `?squared_wass_decomp` for more details.

### Testing for differences between two distributions

The `waddR` package provides two testing procedures using the 2-Wasserstein distance to test whether two distributions \(F_A\) and \(F_B\) given in the form of samples are different by testing the null hypothesis \(H_0: F_A = F_B\) against the alternative hypothesis \(H_1: F_A != F_B\).

The first, semi-parametric (SP), procedure uses a permutation-based test combined with a generalized Pareto distribution approximation to estimate small p-values accurately.

The second procedure uses a test based on asymptotic theory (ASY) which is valid only if the samples can be assumed to come from continuous distributions.

See `?wasserstein.test` for more details.

### Testing for differences between two distributions in the context of scRNAseq data

The `waddR` package provides an adaptation of the semi-parametric testing procedure based on the 2-Wasserstein distance which is specifically tailored to identify differential distributions in scRNAseq data. In particular, a two-stage (TS) approach is implemented that takes account of the specific nature of scRNAseq data by separately testing for differential proportions of zero gene expression (using a logistic regression model) and differences in non-zero gene expression (using the semiparametric 2-Wasserstein distance-based test) between two conditions.

See `?wasserstein.sc` and `?testZeroes` for more details.

## Installation

To install `waddR` from Bioconductor, use `BiocManager` with the following commands:

    if (!requireNamespace("BiocManager"))
     install.packages("BiocManager")
    BiocManager::install("waddR")

Using `BiocManager`, the package can also be installed from GitHub directly:

    BiocManager::install("goncalves-lab/waddR")

The package `waddR` can then be used in R:

    library("waddR")

## Session info

    sessionInfo()
    #> R version 4.6.0 Patched (2026-04-24 r89963)
    #> Platform: aarch64-apple-darwin23
    #> Running under: macOS Tahoe 26.3.1
    #>
    #> Matrix products: default
    #> BLAS:   /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRblas.0.dylib
    #> LAPACK: /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
    #>
    #> 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] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] waddR_1.26.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] SummarizedExperiment_1.42.0 xfun_0.57
    #>  [3] bslib_0.10.0                httr2_1.2.2
    #>  [5] Biobase_2.72.0              lattice_0.22-9
    #>  [7] Rdpack_2.6.6                vctrs_0.7.3
    #>  [9] tools_4.6.0                 generics_0.1.4
    #> [11] stats4_4.6.0                curl_7.1.0
    #> [13] parallel_4.6.0              tibble_3.3.1
    #> [15] RSQLite_2.4.6               blob_1.3.0
    #> [17] pkgconfig_2.0.3             Matrix_1.7-5
    #> [19] arm_1.15-3                  dbplyr_2.5.2
    #> [21] S4Vectors_0.50.0            lifecycle_1.0.5
    #> [23] compiler_4.6.0              Seqinfo_1.2.0
    #> [25] codetools_0.2-20            eva_0.2.6
    #> [27] htmltools_0.5.9             sass_0.4.10
    #> [29] yaml_2.3.12                 nloptr_2.2.1
    #> [31] pillar_1.11.1               jquerylib_0.1.4
    #> [33] MASS_7.3-65                 BiocParallel_1.46.0
    #> [35] SingleCellExperiment_1.34.0 cachem_1.1.0
    #> [37] DelayedArray_0.38.0         reformulas_0.4.4
    #> [39] boot_1.3-32                 abind_1.4-8
    #> [41] nlme_3.1-169                tidyselect_1.2.1
    #> [43] digest_0.6.39               purrr_1.2.2
    #> [45] dplyr_1.2.1                 splines_4.6.0
    #> [47] fastmap_1.2.0               grid_4.6.0
    #> [49] cli_3.6.6                   SparseArray_1.12.0
    #> [51] magrittr_2.0.5              S4Arrays_1.12.0
    #> [53] withr_3.0.2                 filelock_1.0.3
    #> [55] rappdirs_0.3.4              bit64_4.8.0
    #> [57] rmarkdown_2.31              XVector_0.52.0
    #> [59] matrixStats_1.5.0           bit_4.6.0
    #> [61] otel_0.2.0                  lme4_2.0-1
    #> [63] memoise_2.0.1               coda_0.19-4.1
    #> [65] evaluate_1.0.5              knitr_1.51
    #> [67] rbibutils_2.4.1             GenomicRanges_1.64.0
    #> [69] IRanges_2.46.0              BiocFileCache_3.2.0
    #> [71] rlang_1.2.0                 Rcpp_1.1.1-1.1
    #> [73] glue_1.8.1                  DBI_1.3.0
    #> [75] BiocGenerics_0.58.0         minqa_1.2.8
    #> [77] jsonlite_2.0.0              R6_2.6.1
    #> [79] MatrixGenerics_1.24.0