MaAsLin3 (Multivariate Association with Linear Models) supports a rich variety of model formula specifications, empowering users to design analyses that reflect the biological complexity of their studies. This extends beyond the typical “Fixed” and “Random” effects by implementing other variables such as:

  • Group Effects (such as participant_id for longitudinal studies)
  • Ordered Effects (to cross-compare categorical variables with a natural ordering such as cancer stage, consumption frequency, or dosage group)
  • Strata Effects (a single grouping variable to be included in matched case-control studies)

Overview of Model Formula Syntax

In MaAsLin3, the model formula is specified in lme4 formula notation. It describes the relationship between metadata variables (predictors). Users can build formulas that accommodate different experimental designs without manual R scripting. Below we summarize the available scenarios:

Formula Scenarios

Formula ScenarioFormula Syntax
Fixed effect~ salmonella_enterica + days_of_life
Fixed effect and random effect`~ salmonella_enterica + days_of_life + (1sample_id)`
Fixed effect and interaction term~ salmonella_enterica + days_of_life + salmonella_enterica:days_of_life
Fixed effect, random effects and interaction term`~ salmonella_enterica + days_of_life + salmonella_enterica:days_of_life + (1sample_id)`
Group effect~ group(salmonella_enterica)
Fixed effect and group effect~ group(salmonella_enterica) + days_of_life
Fixed effect, random effects and group effect`~ group(salmonella_enterica) + days_of_life + (1sample_id)`
Ordered effect~ ordered(salmonella_enterica)
Fixed effect and ordered effect~ ordered(salmonella_enterica) + days_of_life
Fixed effect, random effects and ordered effect`~ ordered(salmonella_enterica) + days_of_life + (1sample_id)`
Strata effect (exclusive)~ strata(salmonella_enterica)

Detailed Effect Types

Important Considerations

  • Permutations: Group and ordered effects allow combinations similar to fixed and random effects.
  • Exclusivity: Strata effects must be specified alone and cannot coexist with fixed, random, group, or interaction terms.
  • Flexibility: CosmosID-HUB automatically parses user selections into the correct MaAsLin3 formula syntax.
  • Model Validation: CosmosID-HUB internally checks formula validity before submission to MaAsLin3 to prevent common errors.