Configuration.md

Configuration

Settings (paths, threads and so on) resolve with this precedence, highest first:

per run argument  >  env var (MBCAUSAL_*)  >  mbcausal.yaml  >  the default

Defaults live in src/mbcausal/config.py. They are relative placeholders, not real locations, so a fresh clone writes under the project rather than into someone else's directories. Point them at real paths before running anything.

A config file

Copy the example and edit.

cp mbcausal.example.yaml mbcausal.yaml

reports_dir: /path/to/reports              # raw profiler output
preprocess_dir: /path/to/preprocess        # cohort tables and CLR matrices
kraken_db: /path/to/ref_db/k2_default
metaphlan_db: /path/to/metaphlan4
ihmp_metadata: /path/to/hmp2_metadata.csv
threads: 16

Paths

• Relative paths anchor to the project root, so they resolve the same wherever you run from.
• Absolute paths are used as they are.
• Run commands from the repo root so mbcausal.yaml is found.

One off override

MBCAUSAL_THREADS=64 MBCAUSAL_PREPROCESS_DIR=/tmp/out mbcausal discover -i ...

Keys

Key	Meaning
reports_dir	raw profiler reports and logs
preprocess_dir	processed tables (abundance.csv, sample_table.csv, CLR matrices)
kraken_db	Kraken2 and Bracken database
metaphlan_db	MetaPhlAn4 bowtie2 database directory
ganon_db	ganon2 database prefix, the stem of <prefix>.hibf and .tax
ihmp_metadata	HMP2 metadata CSV
threads, read_length, drop_taxa	run defaults

preprocess_dir also determines where simulation output lands. See Simulation.