Home | Quick start | Installation | Configuration | Mapping files | Workflows | Outputs | Flag reference | FAQ | Glossary

---

MATAFILER4 documentation

MATAFILER4 is a Linux/HPC-oriented metagenomic processing pipeline for raw shotgun metagenomic reads. It supports assembly-dependent workflows for communities that assemble well, such as many host-associated microbiomes, and assembly-independent profiling workflows for highly complex communities such as soil.

This documentation snapshot was updated against MATAF4.pl version 4.38.

Which mode should I use?

Use case	Recommended starting point
Gut or other host-associated shotgun metagenomes where assemblies are expected to recover substantial read content	Assembly-dependent workflow
Highly complex communities where assemblies are unlikely to be informative	Assembly-independent profiling
Short-read plus ONT/PacBio support data	Hybrid assemblies
Mapping reads to a defined reference FASTA or database	map2tar / map2DB / map2GC
You already have output and need to know what files matter	Outputs
You need the exact current command-line options	Flag reference

Minimal installation

git clone https://github.com/hildebra/MATAFILER4.git
cd MATAFILER4
bash helpers/install/installer.sh
micromamba activate MF4
./MATAF4.pl -checkInstall

Minimal test pattern

Create or adapt a mapping file, then run a dry-run first:

MAP=/path/to/mapping_file.map
perl $MF4DIR/MATAF4.pl -map "$MAP" -assembleMG 2 -requireInput 1 -submit 0 -from 0 -to 1

Only submit to the scheduler after the dry-run has validated paths and configuration:

perl $MF4DIR/MATAF4.pl -map "$MAP" -assembleMG 2 -requireInput 1 -submit 1 -from 0 -to 1

For new analyses, -requireInput 1 prevents missing or unmatched input reads from being silently skipped. The default 0 is useful when resuming an older run whose original reads were intentionally removed.

Documentation map

1. Installation — software, environments, databases and HPC setup.
2. Quick start — shortest path from install to a test run.
3. Configuration — config.txt, temporary directories and cluster settings.
4. Mapping files — required map structure and sample metadata fields.
5. Common workflows — assembly-dependent, assembly-independent, hybrid and reference mapping examples.
6. Outputs — file-by-file description of final and intermediate results.
7. Flag reference — current options parsed from MATAF4.pl, geneCat.pl, MGS.pl and buildTree5.pl.
8. FAQ — troubleshooting and common failure modes.
9. Glossary — terms used throughout the pipeline.

Validated flag references

The command-line reference is generated from the uploaded Perl sources for MATAF4.pl, geneCat.pl, MGS.pl and buildTree5.pl. See Flag reference.