Output files¶

This page describes the main output folders and files generated by MTD Explorer.

The exact output structure can vary depending on the analysis mode, read layout, selected host, selected databases, and optional flags.

For input preparation, see Input files.
For analysis-mode behavior, see Analysis modes.

Main output directory¶

The output directory is defined with:

--output MTD_results

A typical output directory may contain folders such as:

MTD_results/
├── fastp/
├── kraken/
├── bracken_phylum_all
├── bracken_genus_all
├── bracken_species_all
├── bracken_species_all.biom
├── krona/
├── graphlan/
├── HUMAnN_output/
├── Host_DEG/
├── halla/
├── exploratory/
├── methods/
└── temp/

Not every run creates every folder. Some folders are created only when the corresponding analysis step is enabled or when enough data are available.

Output overview¶

Output	Description
`fastp/`	Read-preprocessing reports
`kraken/`	Host-filtering and microbiome-classification summaries and reports
`bracken_*_all`	Combined abundance tables generated from taxonomic profiles
`bracken_species_all.biom`	BIOM-format abundance table
`krona/`	Interactive taxonomic visualizations
`graphlan/`	Taxonomic tree/cladogram-style visualizations
`HUMAnN_output/`	Functional profiling outputs
`Host_DEG/`	Host count matrix and host comparison outputs
`halla/`	Host–microbiome association-analysis inputs and outputs
`exploratory/`	Non-comparison exploratory figures and QC outputs
`methods/`	Run parameters, methods summary, software paths, and versions
`temp/`	Intermediate working files

Warning

The temp/ directory can be large.

Do not delete it while the pipeline is running. After a successful run, it can be useful for troubleshooting, reproducibility checks, and development.

Read preprocessing outputs¶

When trimming is enabled, MTD Explorer uses fastp and writes reports to:

fastp/

Typical files include:

Trimmed_SAMPLE.fastp.html
Trimmed_SAMPLE.fastp.json

The HTML files are interactive reports that summarize read quality before and after preprocessing.

The JSON files contain machine-readable quality-control statistics.

If --no-trim is used, MTD Explorer skips fastp and prepares the input FASTQ files directly for downstream steps.

Kraken2 outputs¶

MTD Explorer uses Kraken2 in two major classification steps:

host read filtering;
microbiome or target-database classification of non-host reads.

Main Kraken2 outputs are stored in:

kraken/

A typical kraken/ folder may include:

kraken/
├── kraken_host_summary.tsv
├── kraken_nonhost_raw_summary.tsv
├── kraken_nonhost_final_summary.tsv
├── kraken_global_read_composition_raw.tsv
├── kraken_global_read_composition_final.tsv
├── reports_host/
├── reports_micro_raw/
└── reports_micro_final/

Host summary¶

kraken_host_summary.tsv

This table summarizes how many reads or read pairs were classified as host during the host-filtering step.

Typical columns include:

sample
host_classified_reads
host_classified_pct
host_unclassified_reads
host_unclassified_pct
count_unit

The count_unit column indicates whether counts represent reads or read pairs.

Raw non-host microbiome summary¶

kraken_nonhost_raw_summary.tsv

This table summarizes the first microbiome classification of reads that were not classified as host.

It is produced before optional contaminant removal.

Final non-host microbiome summary¶

kraken_nonhost_final_summary.tsv

This table summarizes the final microbiome classification after optional contaminant removal.

This is the classification state used for downstream abundance estimation.

Global read composition¶

kraken_global_read_composition_raw.tsv
kraken_global_read_composition_final.tsv

These tables summarize the global read composition for each sample.

They report the approximate distribution of:

host
microbiome
unclassified

The final table should usually be preferred for interpretation because it reflects the post-decontamination state.

Individual Kraken2 reports¶

Individual Kraken2 reports and classification outputs are stored in:

kraken/reports_host/
kraken/reports_micro_raw/
kraken/reports_micro_final/

These folders preserve per-sample reports for host filtering, raw microbiome classification, and final microbiome classification.

They are useful when you need to inspect the taxonomic profile of one sample in detail.

Bracken outputs¶

MTD Explorer uses Bracken after Kraken2 classification to estimate taxonomic abundance at selected ranks.

The main combined abundance tables are:

bracken_phylum_all
bracken_genus_all
bracken_species_all

These tables combine per-sample Bracken outputs into matrices that can be used for downstream microbiome analysis.

Typical ranks are:

File	Rank
`bracken_phylum_all`	Phylum
`bracken_genus_all`	Genus
`bracken_species_all`	Species

The species-level table is commonly used for downstream taxonomic summaries, exploratory figures, and integration analysis.

BIOM output¶

MTD Explorer also creates a BIOM-format abundance file:

bracken_species_all.biom

This file is useful for workflows and tools that accept the BIOM table format.

Krona outputs¶

MTD Explorer uses KronaTools to generate interactive taxonomic visualizations.

The main folder is:

krona/

Typical outputs include:

SAMPLE-bracken.krona
SAMPLE-bracken.html
all_animals-bracken.krona
all_animals-bracken.html

The .html files can be opened in a web browser.

The combined file:

all_animals-bracken.html

summarizes detected taxa across all processed samples.

GraPhlAn outputs¶

MTD Explorer uses GraPhlAn to generate taxonomic tree or cladogram-style visualizations.

The main folder is:

graphlan/

Typical files include:

Combined.mpa
Combined_for_graphlan.mpa
graphlan_input.clean.tsv
tree.txt
annot.txt
outtree.txt
outimg.png
outimg.pdf
outimg.cladogram_species_top80.png
outimg.cladogram_species_top80.pdf

The PNG and PDF files are the main figure outputs.

The intermediate text files are useful for debugging or modifying the visualization.

HUMAnN outputs¶

MTD Explorer uses HUMAnN for microbial functional profiling.

The main output folder is:

HUMAnN_output/

Depending on the run, this folder may contain normalized inputs and output tables related to:

gene families
pathway abundance
pathway coverage

MTD Explorer also performs post-processing of HUMAnN outputs for downstream functional interpretation.

Host expression outputs¶

Host expression outputs are stored mainly in:

Host_DEG/

This folder may include host count matrices and downstream comparison outputs, depending on the analysis mode.

MTD Explorer uses host alignment and read-counting steps involving tools such as HISAT2, Magic-BLAST, and featureCounts, depending on the selected options and installed host resources.

In comparison mode, host differential-expression analysis can involve DESeq2.

In exploratory mode, comparison-dependent host differential-expression steps are skipped, but host expression QC outputs may still be generated when possible.

HAllA outputs¶

MTD Explorer uses HAllA for host–microbiome association analysis.

The main folder is:

halla/

Typical files may include matrices prepared for association analysis, such as host and microbiome input tables, plus HAllA results.

The exact files depend on whether the upstream host and microbiome matrices are available and suitable for association analysis.

Exploratory outputs¶

Exploratory outputs are stored in:

exploratory/

This folder is especially important when running:

--analysis-mode exploratory

or:

--no-comparison

Typical subfolders may include:

exploratory/
├── taxonomy/
├── host_expression/
└── pipeline_qc/

Taxonomy exploratory outputs¶

Taxonomy exploratory outputs may include:

heatmap/
stacked_bar/
prevalence_abundance/
detected_microbiome/
detected_microbiome_extracted_reads/
core_microbiome/
species_overlap/
detected_microbiome_pie/
alpha_diversity/
beta_diversity/
microbiome_abundance_qc/
logs/

These outputs are designed for descriptive analysis, quality control, and visual inspection of the detected microbiome.

Host expression exploratory outputs¶

Host expression exploratory outputs may include non-comparison QC figures, such as:

host_expression_pca.png
host_expression_top_variable_heatmap.png
host_expression_sample_correlation_heatmap.png
host_expression_detected_features_per_sample.png

These are not differential-expression results. They are exploratory summaries of the host expression matrix.

Pipeline QC outputs¶

Pipeline QC outputs may include summaries of read composition and abundance matrix behavior.

These outputs help identify unusual samples, sparse matrices, or unexpected classification patterns.

Methods and run parameters¶

MTD Explorer writes run information to:

methods/

A key file is:

methods/mtd_methods_run_parameters.csv

This file records parameters and run metadata such as:

input samplesheet
output directory
host Taxonomy ID
host species name
host Kraken2 database
microbiome Kraken2 database
analysis settings
read layout
trimming settings
Bracken read length
Kraken2 confidence values
software paths
software versions

This file is useful for:

reproducibility;
methods writing;
troubleshooting;
comparing runs;
reporting software and parameter choices.

Tip

Keep the methods/ folder with your final results.

It is one of the most useful folders when writing a manuscript or debugging a run later.

Temporary files¶

Intermediate files are stored in:

temp/

This folder may include:

prepared_fastq_manifest.tsv
fastq_input_manifest.tsv
Trimmed_SAMPLE.fq.gz
Trimmed_SAMPLE_R1.fq.gz
Trimmed_SAMPLE_R2.fq.gz
Kraken2 intermediate FASTQ files
Bracken intermediate reports
HUMAnN intermediate inputs

The temp/ folder can be large, but it is often useful for troubleshooting.

Do not delete it until you are sure the run completed successfully and all final outputs were copied or exported.

Read manifests¶

MTD Explorer creates internal manifest files to track resolved and prepared FASTQ files.

Important examples include:

fastq_input_manifest.tsv
prepared_fastq_manifest.tsv

These files record:

sample
layout
read1
read2

They are helpful when debugging input-file detection or paired-end resolution.

Which files should I inspect first?¶

For a normal run, start with these files and folders:

Goal	Start here
Check read preprocessing	`fastp/`
Check host and microbiome read composition	`kraken/kraken_global_read_composition_final.tsv`
Check per-sample taxonomic reports	`kraken/reports_micro_final/`
Check abundance tables	`bracken_species_all`
Check interactive taxonomy plots	`krona/`
Check taxonomic tree figures	`graphlan/`
Check functional profiling	`HUMAnN_output/`
Check host expression outputs	`Host_DEG/`
Check exploratory figures	`exploratory/`
Check parameters and software versions	`methods/mtd_methods_run_parameters.csv`

Outputs by analysis mode¶

Output type	`comparison`	`exploratory`
FASTQ preparation	yes	yes
Host filtering	yes	yes
Microbiome classification	yes	yes
Bracken abundance tables	yes	yes
HUMAnN functional profiling	yes	yes
Krona and GraPhlAn visualizations	yes	yes
DEG-dependent host analysis	yes	skipped
DEG-dependent microbiome analysis	yes	skipped
Exploratory taxonomy figures	yes, when enabled	yes
Exploratory host expression QC	usually skipped	yes, when possible
Methods/run-parameter log	yes	yes

Troubleshooting missing outputs¶

Some outputs may be absent when:

the run stopped before reaching that step;
the selected mode skips that step;
no taxa were detected at the required rank;
the input matrix was empty or too sparse;
required databases were missing or incomplete;
an optional flag was not enabled;
downstream software failed but the pipeline continued with a warning.

When troubleshooting, start with:

methods/mtd_methods_run_parameters.csv
kraken/kraken_global_read_composition_final.tsv
exploratory/*/logs/

Then check the terminal log from the original run.

Next step¶

After reviewing output files, continue to the Command-line reference or the Troubleshooting guide.