maggic-wand

maggic-wand generates publication-quality static plots from MAGGIC (Metagenome Assembled Genome with Iterative Classification) pipeline output. It takes the maggic-results.tsv table and optional maggic-globalabundance.tsv (CoverM TMM matrix) and produces PNG charts suitable for downstream MultiQC integration.

 

Problems It Solves

• Manual plotting: Avoids per-run manual invocation of ggplot/matplotlib scripts
• Inconsistent taxonomy parsing: extracts genus, species, and phylum from GTDB-Tk style __-delimited strings in one place
• Abundance aggregation: joins CoverM TMM per-bin values to genus/species level with taxonomy from results
• Reproducible output: fixed color palettes (tab20-based), deterministic figure sizes, 300dpi PNG

 

How It Works

1. User points maggic-wand at a directory containing maggic-results.tsv
2. The tool loads results, optionally joins with maggic-globalabundance.tsv for abundance-aware plots
3. Taxonomy (genus, species, phylum) is extracted and attached to abundance rows
4. Requested plot types are generated as 300dpi PNGs

 

• Minimum Requirements
• Installation
  • Installation from PyPI
  • Installation via uv (Editable)
  • Installation from Source
  • Installation via Container
• Input Files
• Usage
  • Generate All Plots
  • Single Plot Type
  • Individual Plot Commands
• Plot Types
• CLI Help

 

Minimum Requirements

1. Python 3.12+
2. Dependencies: pandas, matplotlib, seaborn, scipy, wordcloud, typer, beartype, rich, pydantic

 

Installation

Installation from PyPI

pip install maggic-wand

Or with uv:

uv pip install maggic-wand

The package installs the maggic-wand CLI entry point.

Installation via uv (Editable)

git clone repo-url
cd maggic-wand
uv sync

Installation from Source

pip install .

For development with formatting tools:

pip install -e ".[dev]"

Installation via Container

Docker image:

docker pull ghcr.io/biocoder/maggic-wand:0.1.4

Singularity (via oras):

apptainer pull maggic-wand.sif "oras://ghcr.io/biocoder/maggic-wand-sif:0.1.4"

Run:

docker run --rm ghcr.io/biocoder/maggic-wand:0.1.4 plot -d /path/to/maggic/results/ -o /path/to/output/

 

Input Files

maggic-wand expects these files in the results directory:

File	Required	Source
maggic-results.tsv	Yes	MAGGIC pipeline output (30-column TSV with bin metadata, taxonomy, AMR, MGE fields)
maggic-globalabundance.tsv	No	CoverM TMM-normalized abundance matrix (bins x samples)
ALL_REFINED_BINS_QUALITY_REPORT.tsv	No	Binette post deduplication quality report (12 columns)

Plots that depend on abundance data (diversity, heatmap) are skipped with a warning if maggic-globalabundance.tsv is absent. The quality-ecdf plot is skipped if the Binette quality report is absent.

 

Usage

Generate All Plots

maggic-wand plot --maggic-results-dir /path/to/maggic/results/

This discovers maggic-results.tsv and optional companion files, then writes all PNG plots to <results_dir>/plots/.

Single Plot Type

# Only diversity (genus + species) and heatmap (genus + species)
maggic-wand plot --maggic-results-dir results/ --plot-type diversity,heatmap

Individual Plot Commands

For targeted use (e.g., scripting a single chart):

# Diversity stacked bars (genus + species) — outputs genus_diversity.png and species_diversity.png
maggic-wand plot-diversity results/maggic-results.tsv results/maggic-globalabundance.tsv -o diversity.png -n 10

# Quality scatter
maggic-wand plot-quality results/maggic-results.tsv -o quality.png

# Heatmaps (genus + species) — outputs genus_heatmap.png and species_heatmap.png
maggic-wand plot-heatmap results/maggic-results.tsv results/maggic-globalabundance.tsv -o heatmap.png -n 30

 

Plot Types

Plot	Flag	Input Needed	Description
Diversity	diversity	results + abundance	Stacked bars at genus and species level, top-N taxa, TMM-summed per sample, normalized to 100%
Heatmap	heatmap	results + abundance	Hierarchical clustering heatmaps at genus and species level, phylum-colored side bar, column dendrogram
Quality scatter	quality	results	Completeness vs Contamination, colored by bin type
AMR wordcloud	amr-wordcloud	results	Gene frequency from AMR_Genes column
AMR donut	amr-donut	results	AMR class distribution, top-15 + Other
MGE radar	mge-radar	results	Dual radar (plasmid + virus profile), top-N bins
Quality ECDF	quality-ecdf	results + Binette report	Cumulative completeness/contamination/score by binning tool (VAMB, MetaBat2, SemiBin2)
Contig scatter	contigscatter	results	log10(contig count) vs Completeness, marker size = genome size

 

CLI Help

maggic-wand --help
maggic-wand plot --help
maggic-wand plot-diversity --help
maggic-wand plot-heatmap --help