$W_d^*$: distance-based multivariate analysis of variance for multivariate data

September 2025 Updates:

In version 2.3.0 we update exisiting functions and introduce new ones. Changes include:

• Allows installation of R package using devtools::install_github()
• Package versioning
• Addition of function to to peform covariate-adjusted tests using WdS.test()
• Addition of effect-size using omega squared
• Addition of between degrees of freedom
• Changes of parameters within the a.dist() function to not request duplicate objects
• Error and datatype handling improvements
• Improvements to outputs including a.dist() and WdS.test()
• Revamped help files and updated examples for a.dist() and WdS.test()

Introduction

WdStar is an R package for $W_d^*$, a method for multivariate analysis of variance based on Welch's MANOVA designed to address challenges of existing methods including PERMANOVA.

• Are you using PERMANOVA and concerned about how heteroscedasticity and unbalanced sample sizes may affect your analyses?
• Have you ever questioned the reliability of community-wide microbiome analysis results?
• Are you looking for a global test for your multivariate dataset?

$W_d^*$ addresses these concerns and is

• robust to heteroscedasticity;
• handles multi-level factors and stratification;
• allows for multiple post hoc testing scenarios;
• allows for adjustment of covariates; and
• compatible with any data type.

Peer-Reviewed Publications on the $W_d^*$-test Family

$aW_d^*$: preprint title

• Publication authors: preprint doi link
• Code repository

$W_d^*$-test: robust distance-based multivariate analysis of variance

• Hamidi B, Wallace K, Vasu C, & Alekseyenko AV. Microbiome. 2019.
• Code repository

$T_w^2$: multivariate Welch t-test on distances

• Alekseyenko AV. Multivariate Welch t-test on distances. Bioinformatics. 2016.
• Code repository

Installation

Source installation of WdStar R package is available directly from GitHub using remotes or devtools for R 3.4 or later:

install.packages("remotes")
remotes::install_github("alekseyenko/WdStar", force=T)
library(WdStar)
packageVersion("WdStar")

Quick Start

For detailed and complex examples please refer to our publication repositories, which contain Markdown files with application datasets and code.

The following is a simple example using the mtcars dataset to assess the effect of gears on mpg, cyl, and disp (first three variables of the dataset):

# Load dataset
data(mtcars)

# The outcome could be a single variable or multiple variables (such as multidimensional omics data).  

### This is an example of outcome with a single variable (`mpg`):
dm <- dist(mtcars$mpg, method="euclidean")

### This is an example of outcome with multiple variables (`mpg`, `cyl`, and `disp`):
dm <- dist(mtcars[1:3], method="euclidean") 

# Grouping/independent variable. You could use multiple variables here too.
f <- factor(mtcars$gear)

# Basic multivariate test example ###########
#############################################
WdS.test(dm=dm, f=f)

# Stratified example ########################
#############################################
strata <- factor(mtcars$vs)
WdS.test(dm=dm, f=f, strata=strata)

# Covariate adjustment/elimination examples #
#############################################
## Right-hand side adjustment formula to specify adjustment covariates. 
formula <- ~ wt + as.factor(am) 

## Adjustment example 1: pass unadjusted `dm` and formula to WdS.test()
WdS.test(dm=dm, f=f, formula=formula, formula_data=mtcars) ## Perform adjusted test

## Adjustment example 2: Create the adjusted distance matrix `a.dm` outside the function
a.dm <- a.dist(dm=dm, formula=formula, formula_data=mtcars) 
WdS.test(dm=a.dm, f=f) ## Perform adjusted test with `a.dm`

Further examples are provided in the package documentation and may be accessed by running the following commands:

?WdS.test
?a.dist

Feature Requests and Bugs

We welcome feature requests and bug reports and kindly ask you to submit them via our GitHub issue tracker.