Metagenomic Plasmid Analysis

Validation Status

Dated case study (2026-07-09) — Assembly-mode RefSeq validation passed:

  • 3 RefSeq plasmids, 39/39 DAG steps passed

  • NC_002127.1 (3.3kb, genomad=0.99 high / platon=3.7 low), NC_011977.1 (7.6kb ColE9-J, both tools called plasmid), NC_002483.1 (99kb F plasmid, genomad=0.995 high / platon=22.1 low)

  • Tools: genomad + platon, strategy: majority_vote

  • 3/9 sciplot figures rendered (assembly_metrics, plasmid_length_distribution, plasmid_score_vs_length)

  • Known limitations: annotation/typing tools were disabled in this run; 6 figures skipped due to missing annotation/typing/host data

This evidence covers the 39-step route selected by that configuration, not every branch of the current 90-node DAG. Later real-data and SCAPP evidence is tracked separately; do not merge software-contract success with biological acceptance. The current plugin inventory is 64 registered tool IDs and 90 DAG nodes.

The metagenomic_plasmid plugin is ABI’s platform-aware plasmid workflow for Illumina, ONT, PacBio HiFi, hybrid, and assembly-only projects. Its canonical topology is declared in plugins/metagenomic_plasmid/pipeline_dag.yaml; the Python engine resolves sample-specific inputs, conditions, paths, provenance, and normalized result tables.

Default routes

Illumina

FASTQ → fastp → MultiQC → optional Bowtie2 host removal → MEGAHIT → QUAST
      → geNomad → circularity/structure check → PlasmidFinder + MOB-typer
      → Bakta + AMRFinderPlus + ISEScan + IntegronFinder
      → MMseqs2 catalog → Bowtie2 + samtools + CoverM → report

ONT

FASTQ/POD5/BAM → optional Dorado or BAM-to-FASTQ → NanoPlot → Filtlong
               → optional minimap2 host removal → metaFlye
               → optional Medaka → QUAST → shared downstream path

PacBio HiFi

FASTQ/BAM → optional BAM-to-FASTQ → NanoPlot + HiFiAdapterFilt
          → optional minimap2 host removal → hifiasm-meta → QUAST
          → shared downstream path

Hybrid

Illumina + ONT/HiFi → fastp + NanoPlot/Filtlong
                    → platform-specific optional host removal
                    → OPERA-MS → QUAST → shared downstream path

hybridSPAdes and metaSPAdes are explicit alternatives. Selecting an alternative replaces the platform default; ABI does not run multiple assemblers implicitly.

Tool policy

The default path is intentionally narrow:

  • geNomad is the default selected plasmid detector. Platon, PLASMe, PlasX, and the graph-based SCAPP route are optional evidence and are disabled unless the configuration selects them. Weighted-vote weights are read from plasmid_detection.tool_weights; weights for unselected tools do not execute those tools.

  • PlasmidFinder and MOB-typer are the default typing tools.

  • AMRFinderPlus is the default AMR path. ABRicate and RGI are optional.

  • ISEScan and IntegronFinder are enabled by default; eggNOG-mapper is optional.

  • MMseqs2 performs cross-sample catalog clustering. BLAST, MUMmer, and clinker are representative-sequence validation/visualization tools only.

  • MetaBAT2, MaxBin2, CONCOCT, and SemiBin belong to the optional MAG host-genome branch, not plasmid binning.

  • BWA, KneadData, the Hi-C placeholder, pMLST, and batch Bandage nodes are not part of the workflow DAG.

FastQC is disabled by default because fastp already emits HTML and JSON QC reports. Enable it only for a publication or QC-audit appendix. MultiQC remains enabled for project-level aggregation.

Conditional cross-sample analyses

ABI derives eligibility from the actual sample sheet:

Module

Default gate

Alpha/beta diversity

at least 3 samples with read-based abundance

Differential abundance

at least 2 groups and 3 eligible replicates per group

FastSpar network

at least 20 samples with read-based abundance

When a gate is not met, the node is omitted and the reason is written to tables/analysis_status.tsv and the serialized plan. Assembly-only rows do not count as abundance replicates.

Eligible differential analysis uses DESeq2 on raw mapped counts. If raw counts are unavailable, the runner labels rounded coverage explicitly as a count proxy. internal_effect_size is available as a descriptive fallback and does not emit inferential p-values.

Stable result contract

Every declared table is created with its header before execution. A valid zero-hit run therefore produces empty TSVs rather than missing files. Core public tables include:

  • sample_qc.tsv, assembly_qc.tsv

  • plasmid_predictions.tsv, plasmid_consensus.tsv, plasmid_structure.tsv, plasmid_catalog.tsv

  • plasmid_abundance.tsv, plasmid_annotation.tsv, amr_genes.tsv, mge_elements.tsv, plasmid_typing.tsv

  • host_profile.tsv, host_plasmid_links.tsv

  • differential_plasmids.tsv, network_edges.tsv, network_nodes.tsv

  • analysis_status.tsv

Legacy normalized tables remain available for compatibility.

Reproducibility

Each run writes provenance/resource_manifest.json and the compatibility file provenance/resources.json. Database entries record resource ID, path, version, date, source, status, and checksum. File resources use a content SHA-256; database directories explicitly listed in provenance.checksum_resource_ids use a deterministic content-tree SHA-256 unless a provider checksum is configured.

Tool versions, resolved inputs, commands, logs, and the resolved configuration are recorded separately. Placeholder paths ending in NOT_CONFIGURED are reported as such; dry-run success is not evidence that external tools or databases are installed.

Commands

abi plan --type metagenomic_plasmid \
  --config examples/config_minimal.yaml --profile dry_run

abi dry-run --type metagenomic_plasmid \
  --config examples/config_minimal.yaml --profile dry_run

abi check-resources --type metagenomic_plasmid

For production execution, configure database paths and versions, validate the sample sheet, then run the resource and workflow checks before starting tools.