alphavx 0.0.5__py3-none-any.whl

alphavx/__init__.py

@@ -0,0 +1,3 @@
+"""AlphaVX — AlphaGenome Variant Effect Interpreter."""
+
+__version__ = "0.0.5"

alphavx/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m alphavx`."""
+
+from alphavx.cli import app
+
+if __name__ == "__main__":
+    app()

alphavx/cache.py

@@ -0,0 +1,170 @@
+"""SQLite-based result caching for AlphaVX.
+
+Caches variant scoring results so interrupted batch runs can resume
+without re-querying the AlphaGenome API for already-scored variants.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS variant_scores (
+    variant_key TEXT NOT NULL,
+    scores_json TEXT NOT NULL,
+    scored_at TEXT NOT NULL,
+    config_hash TEXT
+);
+"""
+
+# Index for fast lookups on the composite key used by has() / get().
+_INDEX = """
+CREATE INDEX IF NOT EXISTS idx_variant_config
+ON variant_scores (variant_key, config_hash);
+"""
+
+
+class ResultCache:
+    """SQLite cache for variant scoring results.
+
+    Results are keyed by both the variant identifier **and** an optional
+    config hash so that different scoring configurations (modalities,
+    sequence_length, etc.) are cached independently.
+
+    Args:
+        cache_dir: Directory where the cache database will be stored.
+        config_hash: Optional hash string identifying the scoring
+            configuration.  When *None*, every ``has``/``get`` call will
+            behave as a cache miss (safe default for backward compat).
+    """
+
+    def __init__(self, cache_dir: Path, config_hash: str | None = None) -> None:
+        import threading
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.db_path = self.cache_dir / "alphavx_cache.db"
+        self.config_hash = config_hash
+        self._lock = threading.Lock()
+        self._init_db()
+
+    def _init_db(self) -> None:
+        """Create the cache table if it doesn't exist and migrate old schemas."""
+        with sqlite3.connect(self.db_path) as conn:
+            conn.execute(_SCHEMA)
+            # Migrate legacy databases that lack the config_hash column.
+            self._migrate(conn)
+            conn.execute(_INDEX)
+            conn.commit()
+        logger.debug("Cache initialized at %s", self.db_path)
+
+    @staticmethod
+    def _migrate(conn: sqlite3.Connection) -> None:
+        """Add the config_hash column if it is missing (legacy DB migration)."""
+        cursor = conn.execute("PRAGMA table_info(variant_scores)")
+        columns = {row[1] for row in cursor.fetchall()}
+        if "config_hash" not in columns:
+            # Recreate table to remove the PRIMARY KEY constraint on variant_key
+            conn.execute("ALTER TABLE variant_scores RENAME TO variant_scores_old")
+            conn.execute(_SCHEMA)
+            conn.execute(
+                "INSERT INTO variant_scores (variant_key, scores_json, scored_at, config_hash) "
+                "SELECT variant_key, scores_json, scored_at, NULL FROM variant_scores_old"
+            )
+            conn.execute("DROP TABLE variant_scores_old")
+            logger.info("Migrated cache DB: added config_hash column and removed old primary key")
+
+    def has(self, variant_key: str) -> bool:
+        """Check if a variant has cached results for the current config.
+
+        Args:
+            variant_key: Variant identifier (chr:pos:ref>alt).
+
+        Returns:
+            True if the variant has cached scores **and** the cache was
+            created with a non-None ``config_hash``.
+        """
+        if self.config_hash is None:
+            return False
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.execute(
+                "SELECT 1 FROM variant_scores "
+                "WHERE variant_key = ? AND config_hash = ?",
+                (variant_key, self.config_hash),
+            )
+            return cursor.fetchone() is not None
+
+    def get(self, variant_key: str) -> dict | None:
+        """Retrieve cached scores for a variant under the current config.
+
+        Args:
+            variant_key: Variant identifier (chr:pos:ref>alt).
+
+        Returns:
+            Deserialized scores dict, or None if not cached.
+        """
+        if self.config_hash is None:
+            return None
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.execute(
+                "SELECT scores_json FROM variant_scores "
+                "WHERE variant_key = ? AND config_hash = ?",
+                (variant_key, self.config_hash),
+            )
+            row = cursor.fetchone()
+            if row is None:
+                return None
+            return json.loads(row[0])
+
+    def put(self, variant_key: str, scores: dict) -> None:
+        """Store scores for a variant in the cache.
+
+        Args:
+            variant_key: Variant identifier (chr:pos:ref>alt).
+            scores: Scoring results to cache (must be JSON-serializable).
+        """
+        now = datetime.now(timezone.utc).isoformat()
+        scores_json = json.dumps(scores, default=str)
+        with self._lock:
+            with sqlite3.connect(self.db_path) as conn:
+                # Remove any previous entry for the same (variant, config) pair.
+                conn.execute(
+                    "DELETE FROM variant_scores "
+                    "WHERE variant_key = ? AND config_hash IS ?",
+                    (variant_key, self.config_hash),
+                )
+                conn.execute(
+                    "INSERT INTO variant_scores "
+                    "(variant_key, scores_json, scored_at, config_hash) "
+                    "VALUES (?, ?, ?, ?)",
+                    (variant_key, scores_json, now, self.config_hash),
+                )
+            conn.commit()
+        logger.debug("Cached scores for %s", variant_key)
+
+    def clear(self) -> None:
+        """Delete all cached results."""
+        with sqlite3.connect(self.db_path) as conn:
+            conn.execute("DELETE FROM variant_scores")
+            conn.commit()
+        logger.info("Cache cleared")
+
+    def stats(self) -> dict:
+        """Get cache statistics.
+
+        Returns:
+            Dict with 'count' (number of cached variants) and
+            'cache_size_bytes' (database file size).
+        """
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.execute("SELECT COUNT(*) FROM variant_scores")
+            count = cursor.fetchone()[0]
+
+        size = os.path.getsize(self.db_path) if self.db_path.exists() else 0
+        return {"count": count, "cache_size_bytes": size}

alphavx/cli.py

@@ -0,0 +1,296 @@
+"""AlphaVX command-line interface.
+
+Usage:
+    alphavx score input.vcf -o results/
+    alphavx query chr17:7674220:G>A
+    alphavx report results/
+    alphavx cache stats
+    alphavx cache clear
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from . import __version__
+from .config import load_config
+from .vcf_parser import parse_vcf, parse_variant_string
+from .cache import ResultCache
+from .scorer import VariantScorer
+from .reporter import generate_csv_report, generate_html_report, generate_report, generate_vcf_report
+
+app = typer.Typer(
+    name="alphavx",
+    help="AlphaVX — AlphaGenome Variant Effect Interpreter.\n\n"
+    "Batch-score genetic variants against AlphaGenome and generate "
+    "interpretable multi-modal effect reports.",
+    add_completion=False,
+)
+
+cache_app = typer.Typer(help="Manage the variant scoring cache.")
+app.add_typer(cache_app, name="cache")
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(levelname)-7s | %(message)s",
+    datefmt="%H:%M:%S",
+)
+logger = logging.getLogger(__name__)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"alphavx {__version__}")
+        raise typer.Exit()
+
+
+def _get_console():
+    """Get a Rich console for pretty output, or fall back to plain print."""
+    try:
+        from rich.console import Console
+        return Console()
+    except ImportError:
+        return None
+
+
+@app.callback()
+def main(
+    version: Optional[bool] = typer.Option(
+        None, "--version", "-v", callback=_version_callback,
+        is_eager=True, help="Show version and exit.",
+    ),
+) -> None:
+    """AlphaVX — AlphaGenome Variant Effect Interpreter."""
+
+
+@app.command()
+def score(
+    vcf_path: Path = typer.Argument(..., help="Path to VCF file containing variants to score."),
+    output: Path = typer.Option("results", "--output", "-o", help="Output directory for results."),
+    genes: Optional[str] = typer.Option(
+        None, "--genes", "-g",
+        help="Comma-separated gene list to filter results (e.g., BRCA1,TP53,CFTR).",
+    ),
+    config_path: Optional[Path] = typer.Option(
+        None, "--config", "-c", help="Path to alphavx.yaml configuration file.",
+    ),
+    no_cache: bool = typer.Option(False, "--no-cache", help="Disable result caching."),
+) -> None:
+    """Score all variants in a VCF file against AlphaGenome."""
+    console = _get_console()
+
+    # Load config
+    try:
+        config = load_config(config_path)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    config.output_dir = output
+    if no_cache:
+        config.cache_enabled = False
+
+    # Parse VCF
+    try:
+        records = parse_vcf(vcf_path)
+    except (FileNotFoundError, ValueError) as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    typer.echo(f"Parsed {len(records)} variants from {vcf_path}")
+
+    # Setup cache
+    cache = None
+    if config.cache_enabled:
+        cache = ResultCache(output / "cache", config_hash=config.scoring_fingerprint)
+        stats = cache.stats()
+        if stats["count"] > 0:
+            typer.echo(f"Cache: {stats['count']} variants already cached")
+
+    # Score
+    scorer = VariantScorer(config)
+
+    def progress(i: int, total: int, record) -> None:
+        typer.echo(f"[{i + 1}/{total}] Scoring {record.key}...")
+
+    df = scorer.score_batch(records, cache=cache, progress_callback=progress)
+
+    if df.empty:
+        typer.echo("No results — all variants failed or returned empty scores.")
+        raise typer.Exit(1)
+
+    # Filter by genes if specified
+    if genes:
+        gene_list = [g.strip().upper() for g in genes.split(",")]
+        gene_col = "gene_name" if "gene_name" in df.columns else None
+        if gene_col:
+            before = len(df)
+            df = df[df[gene_col].str.upper().isin(gene_list)]
+            typer.echo(f"Gene filter: {before} → {len(df)} rows (genes: {', '.join(gene_list)})")
+
+    # Generate reports
+    generate_csv_report(df, output, quantile_threshold=config.quantile_threshold)
+    generate_html_report(df, output, quantile_threshold=config.quantile_threshold)
+
+    # Generate annotated VCF
+    try:
+        generate_vcf_report(vcf_path, df, output, quantile_threshold=config.quantile_threshold)
+    except Exception as e:
+        logger.warning("Annotated VCF generation failed: %s", e)
+
+    # Generate plots
+    try:
+        from .plots import plot_summary_heatmap, plot_variant_detail
+        plots_dir = output / "plots"
+        plot_summary_heatmap(df, plots_dir / "summary_heatmap.png", config.quantile_threshold)
+
+        # Generate per-variant detail plots
+        variant_keys = df["variant_key"].unique() if "variant_key" in df.columns else []
+        for vk in variant_keys:
+            safe_name = str(vk).replace(":", "_").replace(">", "_")
+            plot_variant_detail(
+                df, vk, plots_dir / "per_variant" / f"{safe_name}.png",
+                config.quantile_threshold,
+            )
+        if len(variant_keys):
+            logger.info("Generated %d per-variant plots", len(variant_keys))
+    except Exception as e:
+        logger.warning("Plot generation failed: %s", e)
+
+    # Print summary
+    sig_count = 0
+    if "quantile_score" in df.columns:
+        sig_count = (df["quantile_score"].abs() > config.quantile_threshold).sum()
+
+    typer.echo("")
+    typer.echo("═" * 50)
+    typer.echo(f"  Variants scored:    {df['variant_key'].nunique() if 'variant_key' in df.columns else '?'}")
+    typer.echo(f"  Significant hits:   {sig_count}")
+    typer.echo(f"  Results:            {output / 'scores.csv'}")
+    typer.echo(f"  Report:             {output / 'report.html'}")
+    typer.echo("═" * 50)
+
+
+@app.command()
+def query(
+    variant: str = typer.Argument(
+        ..., help="Variant to score (e.g., chr17:7674220:G>A or chr17:7674220:G:A).",
+    ),
+    output: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Optional directory to save full CSV results.",
+    ),
+    config_path: Optional[Path] = typer.Option(
+        None, "--config", "-c", help="Path to alphavx.yaml configuration file.",
+    ),
+) -> None:
+    """Score a single variant and display results."""
+    # Parse variant
+    try:
+        record = parse_variant_string(variant)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    # Load config
+    try:
+        config = load_config(config_path)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    typer.echo(f"Scoring {record.key}...")
+
+    # Score
+    scorer = VariantScorer(config)
+    df = scorer.score_variant(record)
+
+    if df.empty:
+        typer.echo("No results returned for this variant.")
+        raise typer.Exit(1)
+
+    # Display significant results
+    if "quantile_score" in df.columns:
+        sig = df[df["quantile_score"].abs() > config.quantile_threshold]
+    else:
+        sig = df.head(0)
+
+    typer.echo(f"\nTotal scores: {len(df)}")
+    typer.echo(f"Significant:  {len(sig)}")
+
+    if not sig.empty:
+        typer.echo(f"\n{'Variant':<25} {'Gene':<12} {'Modality':<20} {'Tissue':<25} {'Raw':<12} {'Quantile':<10}")
+        typer.echo("─" * 104)
+        display_cols = ["variant_key", "gene_name", "output_type", "biosample_name", "raw_score", "quantile_score"]
+        for _, row in sig.sort_values("quantile_score", key=abs, ascending=False).head(30).iterrows():
+            vk = str(row.get("variant_key", ""))[:24]
+            gene = str(row.get("gene_name", ""))[:11]
+            mod = str(row.get("output_type", ""))[:19]
+            tissue = str(row.get("biosample_name", ""))[:24]
+            raw = f"{row.get('raw_score', 0):.6f}"
+            quant = f"{row.get('quantile_score', 0):.6f}"
+            typer.echo(f"{vk:<25} {gene:<12} {mod:<20} {tissue:<25} {raw:<12} {quant:<10}")
+
+    # Save if output specified
+    if output:
+        generate_csv_report(df, output, quantile_threshold=config.quantile_threshold)
+        typer.echo(f"\nFull results saved to {output / 'scores.csv'}")
+
+
+@app.command()
+def report(
+    results_dir: Path = typer.Argument(
+        ..., help="Directory containing scores.csv to generate report from.",
+    ),
+) -> None:
+    """Generate an HTML report from existing scoring results."""
+    try:
+        generate_report(results_dir)
+        typer.echo(f"Report generated: {results_dir / 'report.html'}")
+    except FileNotFoundError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+
+@cache_app.command("stats")
+def cache_stats(
+    cache_dir: Path = typer.Option(
+        "results/cache", "--dir", "-d", help="Cache directory.",
+    ),
+) -> None:
+    """Show cache statistics."""
+    cache = ResultCache(cache_dir)
+    stats = cache.stats()
+    typer.echo(f"Cached variants: {stats['count']}")
+    typer.echo(f"Cache size:      {stats['cache_size_bytes'] / 1024:.1f} KB")
+    typer.echo(f"Cache location:  {cache.db_path}")
+
+
+@cache_app.command("clear")
+def cache_clear(
+    cache_dir: Path = typer.Option(
+        "results/cache", "--dir", "-d", help="Cache directory.",
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation prompt."),
+) -> None:
+    """Clear all cached results."""
+    cache = ResultCache(cache_dir)
+    stats = cache.stats()
+
+    if stats["count"] == 0:
+        typer.echo("Cache is already empty.")
+        return
+
+    if not force:
+        confirm = typer.confirm(f"Delete {stats['count']} cached variant scores?")
+        if not confirm:
+            typer.echo("Cancelled.")
+            return
+
+    cache.clear()
+    typer.echo(f"Cleared {stats['count']} cached entries.")

alphavx/config.py

@@ -0,0 +1,142 @@
+"""Configuration loading and validation for AlphaVX."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Load .env.alphavx file if present (before any os.environ reads)
+# NOTE: We use ".env.alphavx" instead of ".env" because anndata (an
+# alphagenome dependency) uses pydantic-settings which auto-reads ".env"
+# and rejects unknown keys like ALPHAVX_API_KEY.
+try:
+    from dotenv import load_dotenv
+
+    _ENV_FILENAME = ".env.alphavx"
+
+    # Search current dir and project root
+    _candidates = [
+        Path.cwd() / _ENV_FILENAME,
+        Path(__file__).resolve().parent.parent.parent / _ENV_FILENAME,
+    ]
+    for _candidate in _candidates:
+        if _candidate.exists():
+            load_dotenv(_candidate)
+            break
+except ImportError:
+    pass
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MODALITIES = [
+    "RNA_SEQ",
+    "SPLICE_SITES",
+    "SPLICE_SITE_USAGE",
+    "SPLICE_JUNCTIONS",
+    "DNASE",
+    "ATAC",
+    "CHIP_HISTONE",
+    "CHIP_TF",
+]
+
+
+@dataclass
+class Config:
+    """AlphaVX runtime configuration."""
+
+    api_key: str = ""
+    max_retries: int = 3
+    retry_delay: float = 5.0
+    sequence_length: int = 2**20  # 1,048,576 — AlphaGenome optimal
+    quantile_threshold: float = 0.995
+    output_dir: Path = field(default_factory=lambda: Path("results"))
+    cache_enabled: bool = True
+    modalities: list[str] = field(default_factory=lambda: list(DEFAULT_MODALITIES))
+
+    @property
+    def scoring_fingerprint(self) -> str:
+        """Return a short hash of config fields that affect API results.
+
+        Covers ``modalities`` (sorted) and ``sequence_length`` so that
+        different scoring configurations produce distinct cache entries.
+        """
+        canonical = json.dumps(
+            {"modalities": sorted(self.modalities),
+             "sequence_length": self.sequence_length},
+            sort_keys=True,
+        )
+        return hashlib.sha256(canonical.encode()).hexdigest()[:12]
+
+
+def load_config(config_path: Path | None = None) -> Config:
+    """Load configuration from YAML file and/or environment variables.
+
+    Priority: YAML file values > environment variables > defaults.
+
+    Args:
+        config_path: Optional path to an alphavx.yaml configuration file.
+
+    Returns:
+        Populated Config instance.
+
+    Raises:
+        ValueError: If no API key is found in config or environment.
+    """
+    config = Config()
+    key_env_name: str | None = None
+
+    # Load from YAML if provided
+    if config_path is not None:
+        try:
+            import yaml
+        except ImportError:
+            logger.warning("pyyaml not installed — ignoring config file %s", config_path)
+        else:
+            with open(config_path) as f:
+                raw = yaml.safe_load(f) or {}
+
+            api_section = raw.get("api", {})
+            scoring_section = raw.get("scoring", {})
+            output_section = raw.get("output", {})
+
+            key_env_name = api_section.get("key_env")
+
+            if "max_retries" in api_section:
+                config.max_retries = int(api_section["max_retries"])
+            if "retry_delay" in api_section:
+                config.retry_delay = float(api_section["retry_delay"])
+            if "modalities" in scoring_section:
+                config.modalities = scoring_section["modalities"]
+            if "quantile_threshold" in scoring_section:
+                config.quantile_threshold = float(scoring_section["quantile_threshold"])
+            if "sequence_length" in scoring_section:
+                config.sequence_length = int(scoring_section["sequence_length"])
+            if "cache" in output_section:
+                config.cache_enabled = bool(output_section["cache"])
+
+            logger.info("Loaded config from %s", config_path)
+
+    # Resolve API key: env var takes precedence if config doesn't set it
+    if not config.api_key:
+        # If YAML specified a custom env var name via key_env, try it first
+        if key_env_name:
+            config.api_key = os.environ.get(key_env_name, "")
+        # Fall back to the hardcoded env var names
+        if not config.api_key:
+            config.api_key = os.environ.get(
+                "ALPHAVX_API_KEY",
+                os.environ.get("ALPHAGENOME_API_KEY", ""),
+            )
+
+    if not config.api_key:
+        raise ValueError(
+            "No API key found. Set ALPHAVX_API_KEY or ALPHAGENOME_API_KEY environment "
+            "variable, or provide it in your alphavx.yaml config file.\n"
+            "Sign up at: https://deepmind.google.com/science/alphagenome/"
+        )
+
+    return config