vflank 0.1.0__py3-none-any.whl

vflank/__init__.py

@@ -0,0 +1,3 @@
+"""vflank — variant-aware flanking-sequence extraction and masking for ddPCR assay design."""
+
+__version__ = "0.1.0"

vflank/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface (Typer)."""

vflank/cli/_masking.py

@@ -0,0 +1,44 @@
+"""Shared construction of the population-frequency masking source for CLIs.
+
+Both ``small`` and ``fusion`` select a masking backend the same way; this keeps
+that logic in one place.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+from ..core.popfreq import GnomadStore
+from ..core.popfreq_api import GnomadApiSource
+from ..errors import VflankError
+
+
+def validate_pop_options(pop_source: str, pop_data: str) -> None:
+    if pop_source not in ("vcf", "api"):
+        raise VflankError(f"--pop-source must be 'vcf' or 'api', got '{pop_source}'")
+    if pop_data not in ("genome", "exome", "both"):
+        raise VflankError(f"--pop-data must be 'genome', 'exome', or 'both', got '{pop_data}'")
+
+
+def make_pop_source(
+    pop_source: str,
+    pop_vcf_dir: Path | None,
+    genome_build: str,
+    pop_data: str,
+    chroms: Iterable[str],
+) -> GnomadStore | GnomadApiSource | None:
+    """Build the masking source, or None if VCF backend with no directory.
+
+    For the VCF backend, runs ``preflight`` against ``chroms`` so a wholly-absent
+    requested data kind fails fast (no silent genome-only fallback).
+    """
+    if pop_source == "api":
+        return GnomadApiSource(genome_build, pop_data)
+    if pop_vcf_dir is not None:
+        store = GnomadStore(pop_vcf_dir, genome_build, pop_data)
+        resolved = sorted(set(chroms))
+        if resolved:
+            store.preflight(resolved)
+        return store
+    return None

vflank/cli/app.py

@@ -0,0 +1,45 @@
+"""vflank root CLI.
+
+    vflank small run ...        # extract + mask flanks from a MAF
+    vflank small inspect ...    # preview MAF columns
+    vflank small list-vcf ...   # verify gnomAD directory coverage
+    vflank version
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import __version__
+from ..logging import setup_logging
+from . import fusion, small
+
+app = typer.Typer(
+    name="vflank",
+    help="Variant-aware flanking-sequence extraction and masking for ddPCR assay design.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+app.add_typer(small.app, name="small", help="Small-variant (SNP/indel) flank extraction.")
+app.add_typer(fusion.app, name="fusion", help="Structural-variant junction extraction.")
+
+
+@app.callback()
+def main(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable DEBUG logging."),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Only show warnings and errors."),
+    debug: bool = typer.Option(False, "--debug", help="DEBUG logging + rich tracebacks."),
+):
+    """Global options applied before any subcommand."""
+    verbosity = 1 if (verbose or debug) else (-1 if quiet else 0)
+    setup_logging(verbosity, show_tracebacks=debug)
+
+
+@app.command()
+def version():
+    """Print the vflank version."""
+    typer.echo(__version__)
+
+
+if __name__ == "__main__":
+    app()

vflank/cli/fusion.py

@@ -0,0 +1,182 @@
+"""`vflank fusion` — structural-variant junction extraction (simple TSV input).
+
+Reads a breakpoint table (chr1 pos1 str1 chr2 pos2 str2; columns matched by
+name) and writes one FASTA record per fusion: the chimeric junction sequence a
+ddPCR probe spans. VCF/BND input is a later phase.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import typer
+from rich.table import Table
+
+from ..core.chrom import normalise_chrom
+from ..core.fusion import build_junction
+from ..core.popfreq_api import dataset_for_build
+from ..errors import VflankError
+from ..io import breakpoints as bp_io
+from ..io import fasta as fasta_io
+from ..io.breakpoints import SvColumns
+from ..io.reference import ReferenceFasta
+from ..logging import console
+from ._masking import make_pop_source, validate_pop_options
+
+app = typer.Typer(no_args_is_help=True)
+
+
+@app.command()
+def run(
+    sv_file: Path = typer.Argument(
+        ..., exists=True, help="Breakpoint TSV (chr1 pos1 str1 chr2 pos2 str2)."
+    ),
+    ref_genome: Path = typer.Option(
+        ..., "--ref-genome", "-r", help="Indexed reference FASTA (.fai required)."
+    ),
+    genome_build: str = typer.Option("hg19", "--genome-build", "-g", help="hg19 or hg38."),
+    flank: int = typer.Option(
+        200, "--flank", "-f", min=1, max=10_000,
+        help="Bases taken from each partner (junction is up to 2x this).",
+    ),
+    pop_vcf_dir: Path | None = typer.Option(
+        None, "--pop-vcf-dir", "-d",
+        help="Directory of gnomAD VCFs to mask junction flanks. Omit to skip masking.",
+    ),
+    pop_data: str = typer.Option(
+        "genome", "--pop-data", help="gnomAD data to mask against: genome, exome, or both."
+    ),
+    pop_source: str = typer.Option(
+        "vcf", "--pop-source", help="Masking backend: vcf or api (no download)."
+    ),
+    af_threshold: float = typer.Option(
+        0.001, "--af-threshold", min=0.0, max=1.0, help="Min population AF to mask a SNP."
+    ),
+    output: Path = typer.Option(
+        Path("fusion_junctions.fasta"), "--output", "-o", help="Output FASTA file."
+    ),
+    chr1_col: str = typer.Option(SvColumns.chr1, "--chr1-col"),
+    pos1_col: str = typer.Option(SvColumns.pos1, "--pos1-col"),
+    str1_col: str = typer.Option(SvColumns.str1, "--str1-col"),
+    chr2_col: str = typer.Option(SvColumns.chr2, "--chr2-col"),
+    pos2_col: str = typer.Option(SvColumns.pos2, "--pos2-col"),
+    str2_col: str = typer.Option(SvColumns.str2, "--str2-col"),
+    name_col: str = typer.Option(SvColumns.name, "--name-col"),
+    sample_col: str = typer.Option(SvColumns.sample, "--sample-col"),
+):
+    """Build fusion-junction sequences for a breakpoint table and write a FASTA."""
+    cols = SvColumns(
+        chr1_col, pos1_col, str1_col, chr2_col, pos2_col, str2_col, name_col, sample_col
+    )
+    try:
+        _run(sv_file, ref_genome, genome_build, flank, pop_vcf_dir, pop_data,
+             pop_source, af_threshold, output, cols)
+    except VflankError as exc:
+        console.print(f"[bold red]ERROR:[/bold red] {exc}")
+        raise typer.Exit(1) from exc
+
+
+def _run(sv_file, ref_genome, genome_build, flank, pop_vcf_dir, pop_data,
+         pop_source, af_threshold, output, cols: SvColumns):
+    t0 = time.time()
+    console.rule("[bold blue]vflank fusion run[/bold blue]")
+    if genome_build not in ("hg19", "hg38"):
+        raise VflankError(f"--genome-build must be 'hg19' or 'hg38', got '{genome_build}'")
+    validate_pop_options(pop_source, pop_data)
+    if pop_vcf_dir is not None and not pop_vcf_dir.is_dir():
+        raise VflankError(f"--pop-vcf-dir is not a directory: {pop_vcf_dir}")
+
+    console.print(f"[bold]Loading breakpoints:[/bold] {sv_file}")
+    df = bp_io.load_sv_table(sv_file, cols)
+    console.print(f"  {len(df):,} fusion(s)")
+
+    reference = ReferenceFasta(ref_genome)
+    console.print(f"[bold]Reference:[/bold] {ref_genome}  [dim]({genome_build})[/dim]")
+    build_warn = reference.check_build(genome_build)
+    if build_warn:
+        console.print(f"  [bold yellow]⚠ {build_warn}[/bold yellow]")
+
+    # --- Masking source (optional) — masks the junction flanks ---
+    bp_chroms = {
+        b
+        for col in (cols.chr1, cols.chr2)
+        for b, _err in (normalise_chrom(v) for v in df[col].dropna().unique())
+        if b
+    }
+    gnomad = make_pop_source(pop_source, pop_vcf_dir, genome_build, pop_data, bp_chroms)
+    if pop_source == "api":
+        dataset = dataset_for_build(genome_build)[1]
+        console.print(f"[bold]Masking:[/bold] gnomAD API  [dim]({pop_data}, {dataset})[/dim]")
+    elif gnomad is not None:
+        console.print(f"[bold]Masking:[/bold] {pop_vcf_dir}  [dim](pop-data={pop_data})[/dim]")
+    console.print(f"[bold]Flank:[/bold] {flank} bp/partner (junction ≤ {2 * flank} bp)\n")
+
+    records: list[str] = []
+    skipped = 0
+    n_masked_total = 0
+    skip_reasons: list[str] = []
+    summary_rows: list[dict] = []
+
+    for row_idx, row in df.iterrows():
+        fusion, reason = bp_io.parse_fusion_row(row, cols)
+        if reason is not None:
+            skip_reasons.append(f"row {row_idx} — {reason}")
+            skipped += 1
+            continue
+        try:
+            jr = build_junction(reference, fusion, flank, gnomad=gnomad, af_threshold=af_threshold)
+        except Exception as exc:  # noqa: BLE001
+            skip_reasons.append(f"row {row_idx} {fusion.name} — junction error: {exc}")
+            skipped += 1
+            continue
+
+        label = fasta_io.safe_header(fusion.name or "fusion")
+        bp = f"{fusion.bp1.chrom}_{fusion.bp1.pos}_{fusion.bp1.strand}__" \
+             f"{fusion.bp2.chrom}_{fusion.bp2.pos}_{fusion.bp2.strand}"
+        prefix = f"{fasta_io.safe_header(fusion.sample)}__" if fusion.sample else ""
+        header = f"{prefix}{label}__{bp}__j{jr.junction_index}"
+        records.append(f">{header}\n{jr.sequence}\n")
+        records.append(f">Masked__{header}\n{jr.masked_sequence}\n")
+        n_masked_total += jr.n_masked
+
+        truncated = len(jr.sequence) < 2 * flank
+        summary_rows.append({
+            "Name": fusion.name or ".", "BP1": f"{fusion.bp1.chrom}:{fusion.bp1.pos}",
+            "BP2": f"{fusion.bp2.chrom}:{fusion.bp2.pos}",
+            "Len": len(jr.sequence), "Junction": jr.junction_index,
+            "N": jr.n_masked, "Trunc": truncated,
+        })
+
+    reference.close()
+    if gnomad is not None:
+        gnomad.close()
+    fasta_io.write_fasta(output, records)
+
+    console.rule("[bold green]Results[/bold green]")
+    if summary_rows:
+        table = Table(show_header=True, header_style="bold cyan")
+        for col in ("Name", "BP1", "BP2", "Len", "Junction", "N", "Trunc"):
+            table.add_column(col)
+        for r in summary_rows[:50]:
+            n_str = f"[yellow]{r['N']}[/yellow]" if r["N"] else "[dim]0[/dim]"
+            table.add_row(
+                r["Name"], r["BP1"], r["BP2"], str(r["Len"]),
+                str(r["Junction"]), n_str, "[yellow]yes[/yellow]" if r["Trunc"] else "no",
+            )
+        console.print(table)
+
+    if skip_reasons:
+        console.print(f"\n[bold yellow]Skipped {skipped}:[/bold yellow]")
+        for reason in skip_reasons[:20]:
+            console.print(f"  • {reason}")
+
+    mask_line = f"[bold]Bases masked:[/bold] {n_masked_total:>6,}\n" if n_masked_total else ""
+    console.print(
+        f"\n[bold]Fusions:[/bold]   {len(df):>6,}\n"
+        f"[bold]Records:[/bold]   {len(records):>6,} [dim](raw + masked per fusion)[/dim]\n"
+        f"[bold]Skipped:[/bold]   {skipped:>6,}\n"
+        + mask_line +
+        f"[bold]Output:[/bold] [cyan]{output.resolve()}[/cyan]  "
+        f"[dim]({time.time() - t0:.1f}s)[/dim]"
+    )