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:

​
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.