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 87-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 61 registered tool IDs and 87 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 src/abi/plugins/metagenomic_plasmid/pipeline_dag.yaml; the Python engine resolves sample-specific inputs, conditions, paths, provenance, and normalized result tables.

Optional circular maps, linear gene maps, and interactive network rendering are no longer scheduled by the workflow, including when legacy visualization options are supplied. Reports consume structured analysis results without requiring these figures. Comparative clinker, sequence comparisons, and network calculations remain available; render publication figures externally from the result tables. Historical visualization tables remain readable.

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.