# mbcausal Wiki

Internal guide for the microbiome causal inference pipeline.

mbcausal profiles shotgun metagenomes, turns them into a CLR feature matrix, factorizes it
into named groups of taxa, and runs lagged causal discovery over clinical outcomes on IBD
cohorts (iHMP and others).

> [!WARNING]
> **Not all stages are built.** Profiling, the data layer, the preprocessor, the NMF
> representation and the lagged causal discovery suite are implemented and tested. The
> predictor and evaluator stages are still stubs, as is the autoencoder representation.

## Pages

- [Installation](Installation.md), create the env and install the package
- [Configuration](Configuration.md), paths and run settings (`mbcausal.yaml`)
- [Profiling](Profiling.md), reads to abundance tables
- [Preprocessing](Preprocessing.md), cohort tables, QC and the CLR feature matrix
- [Discovery](Discovery.md), NMF factors, the eligibility screen and lagged effects
- [Simulation](Simulation.md), cohorts where the answer is known
- [Reproduction](Reproduction.md), the exact commands behind the paper's numbers

## Subcommand

```
profile          fastq            -> per sample profiler reports
build-cohort     reports          -> abundance.csv + sample_table.csv with qc_pass
preprocess       cohort tables    -> CLR feature matrix
discover         feature matrix   -> NMF factors, eligibility screen, lagged estimates
sim              nothing          -> cohorts whose answer we chose in advance
```

## Repo

- package: `src/mbcausal/`
- simulation study: `src/mbcausal/sim/`
- checks: `make check` (pytest, ruff, mypy)