Methods and reproducibility outputs¶
This page describes the reproducibility outputs generated by MTD Explorer.
These files are designed to help users audit, reproduce, and report an analysis run.
The main folder is:
Input provenance files¶
Two files preserve the exact analysis inputs independently of the original input directory.
Samplesheet copy¶
MTD Explorer copies the exact samplesheet supplied to --input into the output directory at run start. This allows the study design used by that result directory to be recovered even if the original samplesheet is later edited, renamed, or moved.
FASTQ manifest¶
After FASTQ detection and layout validation, MTD Explorer records one row per sample with these columns:
The manifest stores resolved absolute FASTQ paths and file sizes in bytes. For single-end samples, the R2 fields are recorded as -. The FASTQ files themselves are not copied into methods/; the manifest records which files were actually resolved and used.
Main reproducibility table¶
The most important reproducibility file is:
Example table:
Download example run parameters CSV
This table records the run configuration in a structured format.
The columns are usually:
Each row describes one setting, file path, software version, output pattern, or analysis choice used during the run.
Run metadata¶
The Run metadata rows record when and how the pipeline was launched.
Typical parameters include:
The original_command row is especially important because it stores the exact
command line used to start the analysis.
This can include input paths, output paths, host taxon settings, custom databases, read extraction options, and analysis parameters.
Input and output paths¶
The Input and output rows record the main files and folders used by the run.
Typical parameters include:
These rows help users trace the analysis back to the original samplesheet, FASTQ directory, output directory, and optional metadata file.
Study design¶
The Study design rows record settings that affect biological interpretation.
Typical parameters include:
These values help identify the host annotation used for downstream host analysis and the association metric used by HAllA.
Read preparation¶
The Read preparation rows record preprocessing settings.
Typical parameters include:
no_trim
trim_length
read_layout
prepared_fastq_pattern_se
prepared_fastq_pattern_pe
paired_fastq_record_validation
These rows document whether fastp trimming was used, the minimum read length, the effective SE/PE layout, normalized downstream FASTQ patterns, and paired-record validation behavior.
Host filtering¶
The Host filtering rows record the Kraken2 settings used to split
host and non-host reads.
Typical parameters include:
host_kraken_db
host_kraken_db_mode
host_kraken_db_from_hostid
confidence
minimum_hit_groups
classified_out
unclassified_out
These rows are important because the host filtering step affects which reads are passed to downstream microbiome and functional analyses.
Microbiome classification¶
The Microbiome classification rows record the Kraken2 database and
classification settings used for the non-host read fraction.
Typical parameters include:
microbiome_kraken_db
microbiome_kraken_db_mode
microbiome_kraken_db_default
confidence
minimum_hit_groups
raw_report_pattern
final_report_pattern
These values should be reported when comparing taxonomic profiles across runs.
Contaminant removal¶
The Contaminant removal rows record whether a contaminant taxid list was
available to KrakenTools.
Typical parameters include:
If contaminant removal is enabled or available, users should check whether the raw and final global composition outputs differ.
Abundance estimation¶
The Abundance estimation rows record Bracken parameters.
Typical parameters include:
bracken_read_length
bracken_threshold
bracken_distribution_file
bracken_distribution_file_status
taxonomic_levels
These rows are useful for reproducing microbiome abundance estimation.
The read length and distribution file must match the intended Bracken database configuration. The pipeline also records Bracken package metadata and the CLI version banner separately when available. This distinction matters because a packaged Bracken release can expose an older CLI banner; for reproducibility, prefer the recorded package version when identifying the installed Conda build.
Detected microbiome read extraction¶
The Detected microbiome read extraction rows record whether reads assigned to
detected microbiome taxa were extracted.
Typical parameters include:
These settings affect downstream per-taxon read extraction and any analyses based on extracted microbiome reads.
Host downstream analysis¶
The Host downstream analysis rows record host alignment, counting, and
ssGSEA-related settings.
Typical programs and tools include Magic-BLAST, HISAT2, featureCounts, and ssGSEA.
Typical parameters include:
host_alignment_mode
read_layout
blast_database
hisat2_database
gtf_file
conda_environment
paired_end_mode
output
gmt_requested
gmt_resolved
gmt_mode
master_gmt
analysis_gmt
The featureCounts rows record the dedicated MTD_featurecounts environment. Paired-end quantification is explicitly recorded as -p plus --countReadPairs, meaning paired alignments are counted as fragments/read pairs. The current runtime validates featureCounts 2.1.1.
The ssGSEA rows distinguish the value requested by the user from the resolved mode/path and record the persistent host master GMT plus the analysis-specific filtered GMT when applicable. This is especially important now that --ssgsea-gmt auto is the default.
Functional profiling¶
The Functional profiling rows record HUMAnN settings.
Typical parameters include:
These rows help document how non-host reads were passed into functional profiling and how HUMAnN outputs were normalized.
Association analysis¶
The Association analysis rows record HAllA settings.
Typical parameters include:
These values help interpret the integration outputs and clarify whether extra diagnostic or alternative association analyses were enabled.
Key outputs¶
The Key outputs rows record major result files generated by the run.
Typical parameters include:
These paths help users locate the main taxonomic composition table, final species abundance table, and matrix used by HAllA.
Software paths and versions¶
The Software path and Software version rows record executable paths and
best-effort version captures.
Typical programs include:
These rows support reproducibility, but they should be interpreted carefully.
A value such as not_found or command not found means that the version
capture step did not find that executable in the environment where the capture
was attempted.
It does not necessarily mean the whole analysis failed.
Some tools may have been called from another environment, wrapper, module, or step-specific context.
Recommended inspection order¶
For reproducibility, inspect files in this order:
methods/used_samplesheet.csv
methods/used_fastq_files.tsv
methods/mtd_methods_run_parameters.csv
host_counts.txt
Nonhost_DEG/
Host_DEG/
hmn_genefamily_abundance_files/
ssGSEA/
halla/
Start with the saved samplesheet and FASTQ manifest to confirm the exact inputs, then inspect methods/mtd_methods_run_parameters.csv for parameters, databases, and captured software versions.
Then inspect the output folders relevant to the result you want to reproduce.
What this page can support¶
The methods outputs can help answer questions such as:
What not to conclude¶
Do not assume two runs are comparable unless their databases, software versions, read preprocessing settings, taxonomic thresholds, normalization choices, and analysis modes are comparable.
Do not treat a visual output as reproducible without checking the corresponding run-parameter table.
Do not ignore not_found values in the software section; check whether they are
expected for that environment or indicate a missing executable.