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:

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 Under development (unstable) (2023-10-22 r85388)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 22.04.3 LTS
#> 
#> Matrix products: default
#> BLAS:   /home/biocbuild/bbs-3.19-bioc/R/lib/libRblas.so 
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: America/New_York
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] waddR_1.17.0
#> 
#> loaded via a namespace (and not attached):
#>  [1] SummarizedExperiment_1.33.0 xfun_0.40                  
#>  [3] bslib_0.5.1                 Biobase_2.63.0             
#>  [5] lattice_0.22-5              vctrs_0.6.4                
#>  [7] tools_4.4.0                 bitops_1.0-7               
#>  [9] generics_0.1.3              stats4_4.4.0               
#> [11] curl_5.1.0                  parallel_4.4.0             
#> [13] tibble_3.2.1                fansi_1.0.5                
#> [15] RSQLite_2.3.1               blob_1.2.4                 
#> [17] pkgconfig_2.0.3             Matrix_1.6-1.1             
#> [19] arm_1.13-1                  dbplyr_2.3.4               
#> [21] S4Vectors_0.41.0            lifecycle_1.0.3            
#> [23] GenomeInfoDbData_1.2.11     compiler_4.4.0             
#> [25] codetools_0.2-19            eva_0.2.6                  
#> [27] GenomeInfoDb_1.39.0         htmltools_0.5.6.1          
#> [29] sass_0.4.7                  RCurl_1.98-1.12            
#> [31] yaml_2.3.7                  nloptr_2.0.3               
#> [33] pillar_1.9.0                crayon_1.5.2               
#> [35] jquerylib_0.1.4             MASS_7.3-60.1              
#> [37] BiocParallel_1.37.0         SingleCellExperiment_1.25.0
#> [39] DelayedArray_0.29.0         cachem_1.0.8               
#> [41] boot_1.3-28.1               abind_1.4-5                
#> [43] nlme_3.1-163                tidyselect_1.2.0           
#> [45] digest_0.6.33               purrr_1.0.2                
#> [47] dplyr_1.1.3                 splines_4.4.0              
#> [49] fastmap_1.1.1               grid_4.4.0                 
#> [51] SparseArray_1.3.0           cli_3.6.1                  
#> [53] magrittr_2.0.3              S4Arrays_1.3.0             
#> [55] utf8_1.2.4                  withr_2.5.1                
#> [57] filelock_1.0.2              bit64_4.0.5                
#> [59] rmarkdown_2.25              XVector_0.43.0             
#> [61] httr_1.4.7                  matrixStats_1.0.0          
#> [63] lme4_1.1-34                 bit_4.0.5                  
#> [65] coda_0.19-4                 memoise_2.0.1              
#> [67] evaluate_0.22               knitr_1.44                 
#> [69] GenomicRanges_1.55.0        IRanges_2.37.0             
#> [71] BiocFileCache_2.11.0        rlang_1.1.1                
#> [73] Rcpp_1.0.11                 glue_1.6.2                 
#> [75] DBI_1.1.3                   BiocGenerics_0.49.0        
#> [77] minqa_1.2.6                 jsonlite_1.8.7             
#> [79] R6_2.5.1                    MatrixGenerics_1.15.0      
#> [81] zlibbioc_1.49.0