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

# Longitudinal and Complex Association Testing with MaAsLin3

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:

<AccordionGroup>
  <Accordion title="Interaction Terms" icon="sparkles">
    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.
  </Accordion>

  <Accordion title="Group Effects" icon="sparkles">
    * 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.
  </Accordion>

  <Accordion title="Ordered Effects" icon="sparkles">
    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.
  </Accordion>

  <Accordion title="Strata Effects" icon="sparkles">
    * 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.
  </Accordion>
</AccordionGroup>

# <u>Basic Formula Components</u>

<Steps>
  <Step title="Fixed Effects (Simple relationships)">
    ```text theme={null}
    ~ 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.
  </Step>

  <Step title="Interaction Terms">
    ```text theme={null}
    ~ diet * sex 
    ```

    Expands to:

    ```text theme={null}
    diet + sex + diet:sex 
    ```

    This tests if the **effect of diet** is **different between males and females**.
  </Step>

  <Step title="Random Effects (Repeated Measures or Hierarchies)">
    ```text theme={null}
    ~ 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:

    ```text theme={null}
    ~ treatment + (1 | subject_id) + (1 | batch) 
    ```
  </Step>

  <Step title="Group, Ordered, and Strata Variables">
    ```text theme={null}
    ~ 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:

    ```text theme={null}
    age + strata(pair_id) 
    ```
  </Step>
</Steps>

# Example

Let’s say you're analyzing a microbiome dataset of gut samples from different diets, ages, and sexes, with repeated sampling across time:

```text theme={null}
~ 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:

```text theme={null}
~ treatment + strata(subject_pair)
```

# Formula Scenarios

| Scenario                         | Formula Syntax        | Description                                                              |                                                         |
| -------------------------------- | --------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------- |
| **Fixed Effects**                | `~ diet + age`        | Basic effects of variables like diet or age                              |                                                         |
| **Random Effects**               | \`\~ diet + (1        | subject\_id)\`                                                           | Accounts for repeated measurements within individuals   |
| **Interaction Terms**            | `~ diet * sex`        | Tests whether the effect of one variable depends on another              |                                                         |
| **Fixed + Random + Interaction** | \`\~ diet \* sex + (1 | subject\_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:

| Combination                  | Example                             |                |
| ---------------------------- | ----------------------------------- | -------------- |
| Fixed + Random               | \`\~ age + (1                       | subject\_id)\` |
| Fixed + Interaction          | `~ age + treatment + age:treatment` |                |
| Fixed + Group                | `~ group(treatment) + age`          |                |
| Fixed + Ordered              | `~ ordered(dose_level) + age`       |                |
| Fixed + Random + Group       | \`\~ group(treatment) + age + (1    | subject\_id)\` |
| Fixed + Random + Interaction | \`\~ treatment \* timepoint + (1    | subject\_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.