Skip to main content
MaAsLin3 (Multivariate Association with Linear Models) enables complex modeling of associations between microbial features and metadata using R’s lme4 formula syntax. The Cosmos-Hub automatically translates user-selected variables into valid MaAsLin3 formulas, supporting a wide range of study designs. This extends beyond the typical “Fixed” and “Random” effects by implementing other variables such as:
Interaction terms model how the effect of one variable depends on another.
  • Syntax: salmonella_enterica*days_of_life
  • Example: Testing if the impact of salmonella_enterica differs across days of life.
  • For ANOVA-style group testing, checks if any level differs from the others overall. This will group variables into a common cluster for analysis.
  • Syntax: group(variable)
  • Example: When multiple levels of a categorical variable should be treated jointly. Note: Group effects can be combined with fixed and random effects.
For testing stepwise differences between levels, like “mild < moderate < severe”. Used for ordinal metadata where the order matters but the scale is not linear.
  • Syntax: ordered(variable)
  • Example: Disease stages (Stage I, II, III) or ordered diet interventions.
Note: Ordered effects can be combined similarly with fixed/random effects.
  • For matched case-control designs, where samples are paired/matched within strata. Strata effects separate the analysis across strata of a variable and cannot be combined with other formula components.
  • Syntax: strata(variable)
  • Example: Stratifying analyses by distinct clinical groups.

​
Basic Formula Components

1

Fixed Effects (Simple relationships)

~ diet + age + sex
This means: “Model the abundance of each feature as influenced by diet, age, and sex.”This will perform the same function as adding each variable as a fixed effect in the standard GUI.Each variable is assumed to have an independent effect on the microbial feature’s abundance and/or prevalence.
2

Interaction Terms

~ diet * sex
Expands to:
diet + sex + diet:sex
This tests if the effect of diet is different between males and females.
3

Random Effects (Repeated Measures or Hierarchies)

~ treatment + (1 | subject_id)
This tells MaAsLin3: “Model treatment effects, while accounting for multiple samples from the same subject.”Random effects help control for non-independence of observations (e.g., same person measured over time).Multiple random effects are supported:
~ treatment + (1 | subject_id) + (1 | batch)
4

Group, Ordered, and Strata Variables

~ group(treatment_group) + ordered(severity)
Note: Group/ordered predictors should not appear in random effects.Only one strata variable can be used in a model:
age + strata(pair_id)

​
Example

Let’s say you’re analyzing a microbiome dataset of gut samples from different diets, ages, and sexes, with repeated sampling across time: 
~ diet * sex + age + (1 | subject_id)
This means:
  • Main effects of diet, sex, age
  • Diet × sex interaction
  • Random effect for individual subjects
If you’re doing a matched study (e.g., pre/post), you could use: 
~ treatment + strata(subject_pair)

​
Formula Scenarios

ScenarioFormula SyntaxDescription
Fixed Effects~ diet + ageBasic effects of variables like diet or age
Random Effects`~ diet + (1subject_id)`Accounts for repeated measurements within individuals
Interaction Terms~ diet * sexTests whether the effect of one variable depends on another
Fixed + Random + Interaction`~ diet * sex + (1subject_id)`Full model with main, interaction, and repeated effects
Group Effects~ group(diet)Treats all levels of a categorical variable jointly
Ordered Effects~ ordered(stage)Tests stepwise effects in ordinal variables (e.g., Stage I < II < III)
Strata Effects (Exclusive)~ strata(pair_id)For matched case-control studies (cannot be combined with other effects)

​
Combining Effect Types

Effect types can often be mixed—except strata, which must stand alone:
CombinationExample
Fixed + Random`~ age + (1subject_id)`
Fixed + Interaction~ age + treatment + age:treatment
Fixed + Group~ group(treatment) + age
Fixed + Ordered~ ordered(dose_level) + age
Fixed + Random + Group`~ group(treatment) + age + (1subject_id)`
Fixed + Random + Interaction`~ treatment * timepoint + (1subject_id)`
Strata Only~ strata(pair_id)

​
Syntax Notes

  • Interaction Terms: var1:var2 models whether the effect of var1 changes across var2.
  • Group Effects: group(var) aggregates all levels for joint testing.
  • Ordered Effects: ordered(var) evaluates progression across ordered categories.
  • Strata Effects: strata(var) conditions the analysis on matched groups (e.g., case-control pairs) and cannot be combined with other effects.

​
Cosmos-Hub Smart Formula Handling

  • Automatic parsing: Your selections in the Cosmos-Hub interface are converted into the correct formula string.
  • Validation: Invalid or unsupported combinations (e.g., using strata with random) are flagged before submission.
  • Support for prevalence and abundance.

​
Key Considerations

  • Strata must be the only term in the formula—no other variables allowed.
  • Group and ordered variables behave like fixed effects but are tested differently.
  • Interaction models are essential for longitudinal or treatment-timepoint designs.
⌘I