Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cosmosid.com/llms.txt

Use this file to discover all available pages before exploring further.

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.