Designing a Reproducible mtDNA Analysis Pipeline

A reproducible workflow lets another researcher understand what ran, with which inputs, and in what order. Saving the final spreadsheet is not enough.

Reproducibility has levels. Repeatability means rerunning with the same data and environment. Computational reproducibility means an independent researcher can obtain the result from preserved inputs, code, parameters, and dependencies. Robustness asks whether reasonable analytical choices change the conclusion. A pipeline record should support all three without pretending that identical execution proves biological validity.

Freeze the analytical question

Write a short specification before selecting tools:

• biological unit and inclusion/exclusion rules;
• assay and expected mtDNA region;
• source data type and required QC gates;
• reference sequence accession/version and coordinate convention;
• intended outputs: consensus, variants, haplogroup, tree, tables, or report;
• acceptance criteria and what triggers manual review or resequencing.

Separate identity metadata from analytical parameters. A sample code, extraction replicate, sequencing replicate, and file record are different entities. Define how they relate so a rerun does not silently select a different file with the same name.

Make inputs immutable and addressable

For every source artifact, record its checksum, byte size, original name, format, storage location, acquisition context, and access restrictions. A checksum answers “are these bytes identical?”; it does not show that the correct sample was uploaded, so preserve the sample manifest and chain of transformations too.

Derived artifacts also need identities. A trimmed read, consensus FASTA, normalized VCF, alignment, and Newick tree should each have a checksum and a parent relationship. If an intermediate affects a result, either preserve it or preserve enough deterministic information to regenerate and verify it.

Represent dependencies as a graph

A directed acyclic graph (DAG) makes prerequisites explicit. For example:

1. Parse and validate the source.
2. Run assay-appropriate QC.
3. Construct or import a reviewed consensus.
4. Classify haplogroup from that accepted input.
5. Align the selected cohort and infer a tree.
6. Assemble a report from frozen outputs.

The edges matter more than the order shown in a diagram. Haplogroup classification must not run from an unreviewed Sanger base-call string merely because parsing finished. Tree inference may depend on accepted consensus versions from many samples, not one sample’s QC step. Model manual gates as explicit states or signed records instead of invisible pauses.

Independent branches can run concurrently. If contamination screening and trace QC do not depend on one another, both may proceed; if QC fails, only descendants that require accepted QC should be blocked. Record whether a downstream step was skipped, failed, cancelled, or simply never requested.

Pin every changing dependency

“Ran MAFFT” is not enough. Capture:

Containers improve portability but are not self-documenting. Pin an image digest rather than a mutable tag, retain the workflow definition, and record external databases separately. For hosted services, preserve submitted inputs, response, service version if exposed, and date; a URL alone is not reproducible.

Reference semantics deserve special care in mtDNA. rCRS and RSRS are not interchangeable labels. Record the exact sequence and whether the tool internally converts, aligns, or reports variants against another coordinate system. A pipeline configuration field does not prove that every underlying tool used it.

Capture execution as evidence

Each run should be append-only and include:

• pipeline definition/version and initiating user or service;
• resolved input identifiers and checksums, not only a query such as “all project samples”;
• resolved parameters after defaults and overrides;
• per-step start/end times, status, standard output/error or structured error;
• output identifiers, checksums, summary metrics, warnings, and exit code;
• scheduler/runtime identifiers sufficient to find detailed logs.

Treat a retry as part of execution history. Record attempt number and cause. Do not convert a failed first attempt into an unexplained success. Likewise, a timeout, missing binary, empty output, or partial cohort should be a visible state.

Validate data between steps

Exit code zero only means the program believed it completed. Add assertions at handoffs:

• parsed record and sample counts match expectations;
• sequence lengths, alphabets, orientation, and ranges are plausible;
• no sample identifiers were duplicated or truncated;
• VCF reference alleles match the declared reference;
• consensus and alignment checksums are the versions selected for downstream use;
• tree tip labels map one-to-one to included samples;
• report tables cite the run and outputs actually reviewed.

Use positive and negative controls appropriate to the assay. Maintain small test fixtures with known structural expectations, but do not overstate a known result as universal validation of a scientific method.

Rerun and compare, do not overwrite

Create a new run when inputs, parameters, software, database, or workflow definition change. Compare runs at meaningful layers: input checksums, QC decisions, consensus differences, variant normalization, haplogroup call/quality, alignment columns, tree splits, and report values. Explain expected differences.

A bit-for-bit PDF may vary because of timestamps even when scientific content is unchanged. Conversely, an unchanged headline haplogroup can hide changes in the supporting mutation profile. Define which outputs are expected to be byte-identical and which require semantic comparison.

Release checklist

• Frozen question, cohort, sample/replicate map, assay, and acceptance criteria
• Checksummed source and derivative manifest with parent relationships
• Versioned DAG including manual review gates and failure behavior
• Exact references, tools, databases, commands, parameters, code, and environment
• Per-run and per-step inputs, timings, outputs, warnings, errors, and retries
• Automated handoff assertions plus recorded expert review decisions
• New run for every material change and documented run-to-run comparison
• Exportable workflow, manifests, logs, and limitations alongside results

Where GeneFlow fits

GeneFlow stores pipeline definitions as validated DAGs with an rCRS or RSRS reference field. The shipped executor supports QC and HaploGrep3 step types, resolves per-run sample/step overrides, runs dependency-ready steps in waves, allows independent branches to continue after another branch fails, and marks downstream steps as skipped/failed when an upstream dependency does not complete. Pipeline runs and step executions retain status, resolved JSON input/output, timing, and errors.

This provides execution provenance for those supported steps, not an end-to-end mtDNA workflow engine. Consensus construction, NGS mapping/assembly and variant calling, contamination analysis, tree inference, and report generation are not pipeline step types in the current DAG executor. The pipeline’s reference field is recorded metadata; researchers must verify the reference/tree actually used by each external or configured tool. Automatic analyses triggered directly by file parsing should also not be assumed to belong to a recorded pipeline run. Preserve external workflow artifacts and manual approvals, and create explicit runs rather than treating the latest sample result as a complete audit trail.

Further reading

• Wilkinson et al., The FAIR Guiding Principles
• Common Workflow Language specification
• Grüning et al., Practical Computational Reproducibility in the Life Sciences
• NIST Application Container Security Guide