maggic-wand 0.1.0__tar.gz

maggic_wand-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python development
+__pycache__/
+*.py[cod]
+*$py.class
+uv*
+*.ruff_cache
+
+# Distribution
+.Python
+build/
+dist/
+*.egg-info/
+nosetests.xml
+coverage.xml
+*.cover
+*.square
+*container*
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Testing
+.pytest_cache/
+.tox/
+.coverage
+htmlcov/
+*png
+*ank*
+*plan*
+*docs*
+.maggic-wand
+
+# Pipeline outputs and temporary files
+IN-LS/
+work/
+.nextflow.log*
+.nextflow/
+slurm-*.out
+job_scripts/
+resolve-fastq/
+results_*/
+CPIPES-bettercallsal/
+bettercallsal/
+fastq_json_cache/
+bactree-tests/__pycache*
+*rules*
+
+# IDEs and Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Local environment/config
+.env
+.env.*
+*bank/*

maggic_wand-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: maggic-wand
+Version: 0.1.0
+Summary: Publication-quality plots from MAGGIC pipeline results
+Author-email: Kranti Konganti <Kranti.Konganti@fda.hhs.gov>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: beartype>=0.18
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: pandas>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: seaborn>=0.13
+Requires-Dist: typer>=0.9
+Requires-Dist: wordcloud>=1.9
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: flynt; extra == 'dev'
+Requires-Dist: isort; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

maggic_wand-0.1.0/maggic_wand/__init__.py

@@ -0,0 +1,24 @@
+# Kranti Konganti
+#
+# 6/1/2026
+# (C) HFP, FDA.
+
+"""Package init and version for maggic-wand."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from beartype import beartype
+
+
+@beartype
+def _get_version() -> str:
+    """Return the installed package version."""
+    try:
+        return version("maggic-wand")
+    except PackageNotFoundError:
+        return "0.0.0-dev"
+
+
+__version__ = _get_version()

maggic_wand-0.1.0/maggic_wand/cli.py

@@ -0,0 +1,419 @@
+#!/usr/bin/env python3
+# Kranti Konganti
+#
+# 6/1/2026
+# (C) HFP, FDA.
+
+"""CLI entry point for maggic-wand."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+from beartype import beartype
+
+import maggic_wand.data as data
+from maggic_wand.helpers import print_package_info
+from maggic_wand.logging_utils import log
+
+ALL_PLOT_TYPES = frozenset(
+    (
+        "amr-donut",
+        "amr-wordcloud",
+        "contigscatter",
+        "diversity",
+        "heatmap",
+        "mge-radar",
+        "quality",
+        "quality-ecdf",
+    )
+)
+
+app = typer.Typer(
+    name="maggic-wand",
+    help="Publication-quality plots from MAGGIC results",
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+
+@app.command()
+@beartype
+def plot_diversity(
+    results: Path = typer.Argument(..., help="Path to maggic-results.tsv"),
+    abundance: Path = typer.Argument(..., help="Path to maggic-globalabundance.tsv"),
+    output: Path = typer.Option(
+        Path("genus_diversity.png"),
+        "--output",
+        "-o",
+        help="Output PNG path for genus plot (species uses same stem)",
+    ),
+    top_n: int = typer.Option(
+        10,
+        "--top-n",
+        "-n",
+        help="Number of top taxa to display",
+    ),
+) -> None:
+    """Generate diversity bar plots at genus and species level."""
+    log.info("[royal_blue1]Loading results...[/royal_blue1]")
+    results_df = data.load_maggic_results(results)
+
+    log.info("[royal_blue1]Loading abundance...[/royal_blue1]")
+    abundance_df = data.load_globalabundance(abundance)
+
+    log.info("[royal_blue1]Enriching with taxonomy...[/royal_blue1]")
+    enriched = data.enrich_with_taxonomy(abundance_df, results_df)
+
+    from maggic_wand.plots.diversity import (
+        genus_stacked_bar,
+        species_stacked_bar,
+    )
+
+    # Genus stacked bar
+    genus_output = output.parent / "genus_diversity.png"
+    log.info(
+        f"[royal_blue1]Generating genus stacked bar[/royal_blue1]"
+        f" (top {top_n} genera)..."
+    )
+    _ = genus_stacked_bar(enriched, results_df, genus_output, top_n=top_n)
+    log.info(f"[green]+ {genus_output}[/green]")
+
+    # Species stacked bar
+    species_output = output.parent / "species_diversity.png"
+    log.info("[royal_blue1]Generating species stacked bar...[/royal_blue1]")
+    result = species_stacked_bar(enriched, results_df, species_output)
+    if result is None:
+        log.warning("  [yellow]skip[/yellow] (< 2 unique species)")
+    else:
+        log.info(f"[green]+ {species_output}[/green]")
+
+
+@app.command()
+@beartype
+def plot_quality(
+    results: Path = typer.Argument(..., help="Path to maggic-results.tsv"),
+    output: Path = typer.Option(
+        Path("quality_scatter.png"),
+        "--output",
+        "-o",
+        help="Output PNG path",
+    ),
+) -> None:
+    """Generate quality scatter (Completeness vs Contamination)."""
+    log.info("[royal_blue1]Loading results...[/royal_blue1]")
+    results_df = data.load_maggic_results(results)
+
+    from maggic_wand.plots.quality import (
+        quality_scatter,
+    )
+
+    log.info("[royal_blue1]Generating quality scatter chart...[/royal_blue1]")
+    _ = quality_scatter(results_df, output)
+    log.info(f"[green]+ {output}[/green]")
+
+
+@app.command(name="plot-heatmap")
+@beartype
+def plot_heatmap(
+    results: Path = typer.Argument(..., help="Path to maggic-results.tsv"),
+    abundance: Path = typer.Argument(..., help="Path to maggic-globalabundance.tsv"),
+    output: Path = typer.Option(
+        Path("genus_heatmap.png"),
+        "--output",
+        "-o",
+        help="Output PNG path for genus plot (species uses same stem)",
+    ),
+    top_n: int | None = typer.Option(
+        30,
+        "--top-n",
+        "-n",
+        help="Number of top taxa to display (None for all)",
+    ),
+) -> None:
+    """Generate genus and species heatmaps with hierarchical clustering."""
+    log.info("[royal_blue1]Loading results...[/royal_blue1]")
+    results_df = data.load_maggic_results(results)
+
+    log.info("[royal_blue1]Loading abundance...[/royal_blue1]")
+    abundance_df = data.load_globalabundance(abundance)
+
+    log.info("[royal_blue1]Enriching with taxonomy...[/royal_blue1]")
+    enriched = data.enrich_with_taxonomy(abundance_df, results_df)
+
+    from maggic_wand.plots.heatmap import genus_heatmap, species_heatmap
+
+    # Genus heatmap
+    genus_output = output.parent / "genus_heatmap.png"
+    log.info(
+        f"[royal_blue1]Generating genus heatmap[/royal_blue1]" f" (top {top_n} taxa)..."
+    )
+    _ = genus_heatmap(enriched, results_df, genus_output, top_n=top_n)
+    log.info(f"[green]+ {genus_output}[/green]")
+
+    # Species heatmap
+    species_output = output.parent / "species_heatmap.png"
+    log.info("[royal_blue1]Generating species heatmap...[/royal_blue1]")
+    result = species_heatmap(enriched, results_df, species_output)
+    if result is None:
+        log.warning("  [yellow]skip[/yellow] (< 2 unique species)")
+    else:
+        log.info(f"[green]+ {species_output}[/green]")
+
+
+# End-to-end pipeline helpers
+
+
+@beartype
+def _discover_files(results_dir: Path) -> tuple[Path, Path | None]:
+    """Discover maggic-results.tsv and maggic-globalabundance.tsv in a directory.
+
+    Returns:
+        Tuple of (results_path, abundance_path|None).
+    """
+    results = results_dir / "maggic-results.tsv"
+    abundance = results_dir / "maggic-globalabundance.tsv"
+
+    if not results.exists():
+        raise typer.BadParameter(f"maggic-results.tsv not found in {results_dir}")
+
+    abund_path: Path | None = None
+    if abundance.exists():
+        abund_path = abundance
+    return (results, abund_path)
+
+
+# Commands
+
+
+@app.command(name="plot")
+@beartype
+def plot_all(
+    results_dir: Path = typer.Option(
+        ...,
+        "--maggic-results-dir",
+        "-d",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+        help=(
+            "MAGGIC results directory (contains "
+            "maggic-results.tsv, maggic-globalabundance.tsv)"
+        ),
+    ),
+    output_dir: Path = typer.Option(
+        None,
+        "--output-dir",
+        "-o",
+        help="Output directory for plots (default: results_dir/plots/)",
+    ),
+    plot_type: str = typer.Option(
+        "all",
+        "--plot-type",
+        "-p",
+        help=(
+            "Comma-separated list of plots to generate: "
+            "diversity,quality,heatmap (default: all)"
+        ),
+    ),
+    top_n: int = typer.Option(
+        10,
+        "--top-n",
+        "-n",
+        help="Number of top genera for diversity and heatmap plots",
+    ),
+) -> None:
+    """Generate all plots from MAGGIC results directory.
+
+    Discovers maggic-results.tsv and maggic-globalabundance.tsv in the
+    specified directory, then generates all requested plot types.
+    """
+    # Parse plot types
+    requested = {t.strip() for t in plot_type.split(",")}
+    if requested == {"all"}:
+        requested = set(ALL_PLOT_TYPES)
+    invalid = requested - ALL_PLOT_TYPES
+    if invalid:
+        raise typer.BadParameter(
+            f"Unknown plot type(s): {', '.join(sorted(invalid))}. "
+            f"Valid types: {', '.join(sorted(ALL_PLOT_TYPES))}"
+        )
+
+    # Resolve output directory
+    out_dir: Path = output_dir or (results_dir / "plots")
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # Discover input files
+    results_path, abundance_path = _discover_files(results_dir)
+    has_abundance = abundance_path is not None
+
+    log.info(f"[royal_blue1]Input dir:[/royal_blue1] {results_dir}")
+    log.info(f"[royal_blue1]Output dir:[/royal_blue1] {out_dir}")
+    log.info(f"[royal_blue1]Plots:[/royal_blue1] {', '.join(sorted(requested))}")
+
+    # Load shared data
+    results_df = data.load_maggic_results(results_path)
+
+    enriched = (
+        None
+        if not has_abundance
+        else data.enrich_with_taxonomy(
+            data.load_globalabundance(abundance_path), results_df
+        )
+    )
+
+    # Generate plots
+    for plot_name in sorted(requested):
+        if plot_name == "quality":
+            from maggic_wand.plots.quality import (
+                quality_scatter,
+            )
+
+            output = out_dir / "quality_scatter.png"
+            log.info(f"[royal_blue1]Generating {plot_name}...[/royal_blue1]")
+            quality_scatter(results_df, output)
+            log.info(f"  [green]+ {output}[/green]")
+
+        elif plot_name == "diversity":
+            if enriched is None:
+                log.warning(f"  [yellow]skip {plot_name}[/yellow] (no abundance data)")
+                continue
+
+            from maggic_wand.plots.diversity import (
+                genus_stacked_bar,
+                species_stacked_bar,
+            )
+
+            # Genus stacked bar
+            genus_output = out_dir / "genus_diversity.png"
+            log.info(f"[royal_blue1]Generating genus {plot_name}...[/royal_blue1]")
+            genus_stacked_bar(enriched, results_df, genus_output, top_n=top_n)
+            log.info(f"  [green]+ {genus_output}[/green]")
+
+            # Species stacked bar
+            species_output = out_dir / "species_diversity.png"
+            log.info("[royal_blue1]Generating species diversity...[/royal_blue1]")
+            result = species_stacked_bar(enriched, results_df, species_output)
+            if result is None:
+                log.warning("  [yellow]skip species[/yellow] (< 2 unique species)")
+            else:
+                log.info(f"  [green]+ {species_output}[/green]")
+
+        elif plot_name == "heatmap":
+            if enriched is None:
+                log.warning(f"  [yellow]skip {plot_name}[/yellow] (no abundance data)")
+                continue
+
+            from maggic_wand.plots.heatmap import (
+                genus_heatmap,
+                species_heatmap,
+            )
+
+            # Genus heatmap
+            genus_output = out_dir / "genus_heatmap.png"
+            log.info(f"[royal_blue1]Generating genus {plot_name}...[/royal_blue1]")
+            genus_heatmap(enriched, results_df, genus_output, top_n=30)
+            log.info(f"  [green]+ {genus_output}[/green]")
+
+            # Species heatmap
+            species_output = out_dir / "species_heatmap.png"
+            log.info("[royal_blue1]Generating species heatmap...[/royal_blue1]")
+            result = species_heatmap(enriched, results_df, species_output)
+            if result is None:
+                log.warning("  [yellow]skip species[/yellow] (< 2 unique species)")
+            else:
+                log.info(f"  [green]+ {species_output}[/green]")
+
+        elif plot_name == "amr-wordcloud":
+            from maggic_wand.plots.amr import (
+                amr_wordcloud,
+            )
+
+            output = out_dir / "amr_wordcloud.png"
+            log.info(f"[royal_blue1]Generating {plot_name}...[/royal_blue1]")
+            amr_wordcloud(results_df, output)
+            log.info(f"  [green]+ {output}[/green]")
+
+        elif plot_name == "amr-donut":
+            from maggic_wand.plots.amr import (
+                amr_class_donut,
+            )
+
+            output = out_dir / "amr_class_donut.png"
+            log.info(f"[royal_blue1]Generating {plot_name}...[/royal_blue1]")
+            amr_class_donut(results_df, output)
+            log.info(f"  [green]+ {output}[/green]")
+
+        elif plot_name == "mge-radar":
+            from maggic_wand.plots.mge import mge_radar
+
+            output = out_dir / "mge_radar.png"
+            log.info(f"[royal_blue1]Generating {plot_name}...[/royal_blue1]")
+            mge_radar(results_df, output)
+            log.info(f"  [green]+ {output}[/green]")
+
+        elif plot_name == "quality-ecdf":
+            from maggic_wand.plots.histogram import (
+                quality_ecdf,
+            )
+
+            quality_path = results_dir / "ALL_REFINED_BINS_QUALITY_REPORT.tsv"
+            if not quality_path.exists():
+                log.warning(
+                    f"  [yellow]skip {plot_name}[/yellow]"
+                    f" (no Binette quality report)"
+                )
+                continue
+
+            output = out_dir / "quality_ecdf.png"
+            log.info(f"[royal_blue1]Generating {plot_name}...[/royal_blue1]")
+            quality_df = data.load_binette_quality_report(quality_path)
+            quality_ecdf(quality_df, output)
+            log.info(f"  [green]+ {output}[/green]")
+
+        elif plot_name == "contigscatter":
+            from maggic_wand.plots.contigscatter import (
+                completeness_contig_scatter,
+            )
+
+            output = out_dir / "completeness_contig_scatter.png"
+            log.info(f"[royal_blue1]Generating {plot_name}...[/royal_blue1]")
+            completeness_contig_scatter(results_df, output)
+            log.info(f"  [green]+ {output}[/green]")
+
+    log.info("")
+    log.info(f"[bold yellow]Plots written to[/bold yellow] {out_dir}")
+
+
+@app.command(name="version")
+@beartype
+def version() -> None:
+    """Print package version."""
+    from maggic_wand import __version__
+
+    log.info(f"maggic-wand v{__version__}")
+
+
+VERSION_FLAGS = frozenset(("-v", "--version"))
+
+
+@beartype
+def main() -> None:
+    """Entry point."""
+    # Show package info banner when invoked without a subcommand or with -h/--help/-v/--version
+    has_help = "-h" in sys.argv or "--help" in sys.argv
+    has_version = any(flag in sys.argv for flag in VERSION_FLAGS)
+    no_subcommand = len(sys.argv) == 1
+
+    if no_subcommand:
+        print_package_info(help_flag="-h")
+    elif has_help:
+        print_package_info(help_flag="--help")
+    elif has_version:
+        print_package_info(help_flag="-h")
+        return None
+
+    app()

maggic_wand-0.1.0/maggic_wand/constants.py

@@ -0,0 +1,144 @@
+# Kranti Konganti
+#
+# 6/1/2026
+# (C) HFP, FDA.
+
+"""Global constants for maggic-wand."""
+
+from __future__ import annotations
+
+from typing import Final
+
+# Package
+PKG_NAME: Final[str] = "maggic-wand"
+PKG_TAGLINE: Final[str] = "Publication-quality plots from MAGGIC results"
+
+# CLI colors (rich markup)
+COLOR_PKG: Final[str] = "light_sea_green"
+COLOR_INFO: Final[str] = "bold blue"
+COLOR_SUCCESS: Final[str] = "bold green"
+COLOR_WARN: Final[str] = "bold yellow"
+
+# Unassigned / fallback
+UNASSIGNED: Final[str] = "Unassigned"
+COLOR_UNASSIGNED: Final[str] = "#cccccc"
+COLOR_GREY: Final[str] = "#999999"
+COLOR_GREEN: Final[str] = "#1b9e77"
+
+# Composite phylum palette: 79 distinctive colors from tab20/20b/20c/Paired/Accent
+PHYLUM_COLORS = (
+    "#1f77b4",
+    "#aec7e8",
+    "#ff7f0e",
+    "#ffbb78",
+    "#2ca02c",
+    "#98df8a",
+    "#d62728",
+    "#ff9896",
+    "#9467bd",
+    "#c5b0d5",
+    "#8c564b",
+    "#c49c94",
+    "#e377c2",
+    "#f7b6d2",
+    "#7f7f7f",
+    "#c7c7c7",
+    "#bcbd22",
+    "#dbdb8d",
+    "#17becf",
+    "#9edae5",
+    "#393b79",
+    "#5254a3",
+    "#6b6ecf",
+    "#9c9ede",
+    "#637939",
+    "#8ca252",
+    "#b5cf6b",
+    "#cedb9c",
+    "#8c6d31",
+    "#bd9e39",
+    "#e7ba52",
+    "#e7cb94",
+    "#843c39",
+    "#ad494a",
+    "#d6616b",
+    "#e7969c",
+    "#7b4173",
+    "#a55194",
+    "#ce6dbd",
+    "#de9ed6",
+    "#3182bd",
+    "#6baed6",
+    "#9ecae1",
+    "#c6dbef",
+    "#e6550d",
+    "#fd8d3c",
+    "#fdae6b",
+    "#fdd0a2",
+    "#31a354",
+    "#74c476",
+    "#a1d99b",
+    "#c7e9c0",
+    "#756bb1",
+    "#9e9ac8",
+    "#bcbddc",
+    "#dadaeb",
+    "#636363",
+    "#969696",
+    "#bdbdbd",
+    "#d9d9d9",
+    "#a6cee3",
+    "#1f78b4",
+    "#b2df8a",
+    "#33a02c",
+    "#fb9a99",
+    "#e31a1c",
+    "#fdbf6f",
+    "#ff7f00",
+    "#cab2d6",
+    "#6a3d9a",
+    "#ffff99",
+    "#b15928",
+    "#7fc97f",
+    "#beaed4",
+    "#fdc086",
+    "#386cb0",
+    "#f0027f",
+    "#bf5b16",
+    "#666666",
+)
+
+# Bin-type palette (quality scatter)
+BIN_TYPE_COLOURS = {
+    "Chromosome_MAG": "#1b9e77",
+    "Plasmid_MAG": "#d95f02",
+    "Virus_MAG": "#7570b3",
+    "Mixed_MAG": "#e7298a",
+    "Skeletal_MAG": "#66a61e",
+    "Fragments": "#808080",
+    "Low_Quality": "#666666",
+}
+
+# Genus color pool (tab20 derived)
+GENUS_COLOR_POOL: tuple[str, ...] = (
+    "#1f77b4",
+    "#ff7f0e",
+    "#2ca02c",
+    "#d62728",
+    "#9467bd",
+    "#8c564b",
+    "#e377c2",
+    "#7f7f7f",
+    "#bcbd22",
+    "#17becf",
+    "#aec7e8",
+    "#ffbb78",
+    "#98df8a",
+    "#ff9896",
+    "#c5b0d5",
+    "#c49c94",
+    "#f7b6d2",
+    "#c7c7c7",
+    "#dbdb8d",
+    "#f7c5a8",
+)