svphaser 2.0.1__tar.gz

svphaser-2.0.1/.gitignore

@@ -0,0 +1,12 @@
+# Ignore all files in output directories
+output_*/
+output/
+__pycache__/
+# Ignore all CSV and VCF files anywhere (optional, only if you want)
+*.csv
+*.vcf
+# Or, ignore only those in the output directories:
+output_*/**/*.csv
+output_*/**/*.vcf
+output/**/*.csv
+output/**/*.vcf

svphaser-2.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Structural and Functional Genomics Laboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

svphaser-2.0.1/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: svphaser
+Version: 2.0.1
+Summary: Structural-variant phasing from HP-tagged long-read BAMs
+Project-URL: Homepage, https://github.com/your-org/svphaser
+Project-URL: Issues, https://github.com/your-org/svphaser/issues
+Project-URL: Source, https://github.com/your-org/svphaser
+Author-email: SvPhaser Team <you@lab.org>
+License: MIT
+License-File: LICENSE
+Keywords: BAM,ONT,VCF,genomics,long-reads,phasing,structural-variants
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Requires-Dist: cyvcf2>=0.30
+Requires-Dist: pandas>=2.1
+Requires-Dist: pysam>=0.23
+Requires-Dist: typer>=0.14
+Provides-Extra: bench
+Requires-Dist: py-spy>=0.3; extra == 'bench'
+Requires-Dist: pytest-benchmark>=4.0; extra == 'bench'
+Provides-Extra: dev
+Requires-Dist: black>=24.3; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: hypothesis>=6.90; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.6; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: tox>=4.10; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: plots
+Requires-Dist: matplotlib>=3.7; extra == 'plots'
+Description-Content-Type: text/markdown
+
+# SvPhaser
+
+> **Haplotype‑aware structural‑variant genotyper for long‑read data**
+
+[![PyPI version](https://img.shields.io/pypi/v/svphaser.svg?logo=pypi)](https://pypi.org/project/svphaser)
+[![Tests](https://img.shields.io/github/actions/workflow/status/your‑org/SvPhaser/ci.yml?label=ci)](https://github.com/your‑org/SvPhaser/actions)
+[![License](https://img.shields.io/github/license/your‑org/SvPhaser.svg)](LICENSE)
+
+---
+
+`SvPhaser` phases **pre‑called structural variants (SVs)** using *HP‑tagged* long‑read alignments (PacBio HiFi, ONT Q20+, …).  Think of it as *WhatsHap* for insertions/deletions/duplications: we do **not** discover SVs; we assign each variant a haplotype genotype (`0|1`, `1|0`, `1|1`, or `./.`) together with a **Genotype Quality (GQ)** score – all in a single, embarrassingly‑parallel pass over the genome.
+
+## Key highlights
+
+* **Fast, per‑chromosome multiprocessing** – linear scale‑out on 32‑core workstations.
+* **Deterministic Δ‑based decision tree** – no MCMC or hidden state machines.
+* **Friendly CLI** (`svphaser phase …`) and importable Python API.
+* **Seamless VCF injection** – adds `HP_GT`, `HP_GQ`, `HP_GQBIN` INFO tags while copying the original header verbatim.
+* **Configurable confidence bins** and publication‑ready plots (see `result_images/`).
+
+---
+
+## Installation
+
+```bash
+# Requires Python ≥3.9
+pip install svphaser            # PyPI (coming soon)
+# or
+pip install git+https://github.com/your‑org/SvPhaser.git@v0.2.0
+```
+
+`cyvcf2`, `pysam`, `typer[all]`, and `pandas` are pulled in automatically.
+
+## Quick‑start
+
+```bash
+svphaser phase \
+    sample_unphased.vcf.gz \
+    sample.sorted_phased.bam \
+    --out-dir results/ \
+    --min-support 10 \
+    --major-delta 0.70 \
+    --equal-delta 0.25 \
+    --gq-bins "30:High,10:Moderate" \
+    --threads 32
+```
+
+Outputs (written inside **`results/`**)
+
+```
+sample_unphased_phased.vcf   # original VCF + HP_* INFO fields
+sample_unphased_phased.csv   # tidy table for plotting / downstream R
+```
+
+See [`docs/methodology.md`](docs/Methodology.md) and the flow‑chart below for algorithmic details.
+
+![SvPhaser methodology](docs/result_images/methodology_diagram.png)
+
+## Folder layout
+
+```
+SvPhaser/
+├─ src/svphaser/        # importable package
+│  ├─ cli.py            # Typer entry‑point
+│  ├─ logging.py        # unified log setup
+│  └─ phasing/
+│     ├─ algorithms.py  # core maths
+│     ├─ io.py          # driver & I/O
+│     ├─ _workers.py    # per‑chrom processes
+│     └─ types.py       # thin dataclasses
+├─ tests/               # pytest suite + mini data
+├─ docs/                # extra documentation
+├─ result_images/       # generated plots & diagrams
+└─ CHANGELOG.md
+```
+
+## Python usage
+
+```python
+from pathlib import Path
+from svphaser.phasing.io import phase_vcf
+
+phase_vcf(
+    Path("sample.vcf.gz"),
+    Path("sample.bam"),
+    out_dir=Path("results"),
+    min_support=10,
+    major_delta=0.70,
+    equal_delta=0.25,
+    gq_bins="30:High,10:Moderate",
+    threads=8,
+)
+```
+
+The resulting `DataFrame` can be loaded from the CSV for custom analytics.
+
+
+
+
+## Development & contributing
+
+1. Clone and create a virtual env:
+
+   ```bash
+   git clone https://github.com/your‑org/SvPhaser.git && cd SvPhaser
+   python -m venv .venv && source .venv/bin/activate
+   pip install -e .[dev]
+   ```
+2. Run the test‑suite & type checks:
+
+   ```bash
+   pytest -q
+   mypy src/svphaser
+   black --check src tests
+   ```
+3. Send a PR targeting the **`dev`** branch; one topic per PR.
+
+Please read `CONTRIBUTING.md` (to come) for style‑guides and the DCO sign‑off.
+
+## Citing SvPhaser
+
+If SvPhaser contributed to your research, please cite:
+
+```bibtex
+@software{svphaser2024,
+  author       = {Pranjul Mishra, Sachin Ghadak, CeNT Lab},
+  title        = {SvPhaser: haplotype‑aware SV genotyping},
+  version      = {0.2.0},
+  date         = {2024-06-18},
+  url          = {https://github.com/your‑org/SvPhaser}
+}
+```
+
+
+
+
+## License
+`SvPhaser` is released under the MIT License – see [`LICENSE`](LICENSE).
+
+
+
+
+
+## 📬 Contact
+
+Developed by **Team5** (*BioAI Hackathon*) – Sachin Gadakh & Pranjul Mishra.
+
+Lead contacts:
+• [pranjul.mishra@proton.me](mailto:pranjul.mishra@proton.me)
+• [s.gadakh@cent.uw.edu.pl](mailto:s.gadakh@cent.uw.edu.pl)
+
+Feedback, feature requests and bug reports are all appreciated — feel free to open a GitHub issue or reach out by e‑mail.
+
+---
+
+*Happy phasing!*

svphaser-2.0.1/README.md

@@ -0,0 +1,156 @@
+# SvPhaser
+
+> **Haplotype‑aware structural‑variant genotyper for long‑read data**
+
+[![PyPI version](https://img.shields.io/pypi/v/svphaser.svg?logo=pypi)](https://pypi.org/project/svphaser)
+[![Tests](https://img.shields.io/github/actions/workflow/status/your‑org/SvPhaser/ci.yml?label=ci)](https://github.com/your‑org/SvPhaser/actions)
+[![License](https://img.shields.io/github/license/your‑org/SvPhaser.svg)](LICENSE)
+
+---
+
+`SvPhaser` phases **pre‑called structural variants (SVs)** using *HP‑tagged* long‑read alignments (PacBio HiFi, ONT Q20+, …).  Think of it as *WhatsHap* for insertions/deletions/duplications: we do **not** discover SVs; we assign each variant a haplotype genotype (`0|1`, `1|0`, `1|1`, or `./.`) together with a **Genotype Quality (GQ)** score – all in a single, embarrassingly‑parallel pass over the genome.
+
+## Key highlights
+
+* **Fast, per‑chromosome multiprocessing** – linear scale‑out on 32‑core workstations.
+* **Deterministic Δ‑based decision tree** – no MCMC or hidden state machines.
+* **Friendly CLI** (`svphaser phase …`) and importable Python API.
+* **Seamless VCF injection** – adds `HP_GT`, `HP_GQ`, `HP_GQBIN` INFO tags while copying the original header verbatim.
+* **Configurable confidence bins** and publication‑ready plots (see `result_images/`).
+
+---
+
+## Installation
+
+```bash
+# Requires Python ≥3.9
+pip install svphaser            # PyPI (coming soon)
+# or
+pip install git+https://github.com/your‑org/SvPhaser.git@v0.2.0
+```
+
+`cyvcf2`, `pysam`, `typer[all]`, and `pandas` are pulled in automatically.
+
+## Quick‑start
+
+```bash
+svphaser phase \
+    sample_unphased.vcf.gz \
+    sample.sorted_phased.bam \
+    --out-dir results/ \
+    --min-support 10 \
+    --major-delta 0.70 \
+    --equal-delta 0.25 \
+    --gq-bins "30:High,10:Moderate" \
+    --threads 32
+```
+
+Outputs (written inside **`results/`**)
+
+```
+sample_unphased_phased.vcf   # original VCF + HP_* INFO fields
+sample_unphased_phased.csv   # tidy table for plotting / downstream R
+```
+
+See [`docs/methodology.md`](docs/Methodology.md) and the flow‑chart below for algorithmic details.
+
+![SvPhaser methodology](docs/result_images/methodology_diagram.png)
+
+## Folder layout
+
+```
+SvPhaser/
+├─ src/svphaser/        # importable package
+│  ├─ cli.py            # Typer entry‑point
+│  ├─ logging.py        # unified log setup
+│  └─ phasing/
+│     ├─ algorithms.py  # core maths
+│     ├─ io.py          # driver & I/O
+│     ├─ _workers.py    # per‑chrom processes
+│     └─ types.py       # thin dataclasses
+├─ tests/               # pytest suite + mini data
+├─ docs/                # extra documentation
+├─ result_images/       # generated plots & diagrams
+└─ CHANGELOG.md
+```
+
+## Python usage
+
+```python
+from pathlib import Path
+from svphaser.phasing.io import phase_vcf
+
+phase_vcf(
+    Path("sample.vcf.gz"),
+    Path("sample.bam"),
+    out_dir=Path("results"),
+    min_support=10,
+    major_delta=0.70,
+    equal_delta=0.25,
+    gq_bins="30:High,10:Moderate",
+    threads=8,
+)
+```
+
+The resulting `DataFrame` can be loaded from the CSV for custom analytics.
+
+
+
+
+## Development & contributing
+
+1. Clone and create a virtual env:
+
+   ```bash
+   git clone https://github.com/your‑org/SvPhaser.git && cd SvPhaser
+   python -m venv .venv && source .venv/bin/activate
+   pip install -e .[dev]
+   ```
+2. Run the test‑suite & type checks:
+
+   ```bash
+   pytest -q
+   mypy src/svphaser
+   black --check src tests
+   ```
+3. Send a PR targeting the **`dev`** branch; one topic per PR.
+
+Please read `CONTRIBUTING.md` (to come) for style‑guides and the DCO sign‑off.
+
+## Citing SvPhaser
+
+If SvPhaser contributed to your research, please cite:
+
+```bibtex
+@software{svphaser2024,
+  author       = {Pranjul Mishra, Sachin Ghadak, CeNT Lab},
+  title        = {SvPhaser: haplotype‑aware SV genotyping},
+  version      = {0.2.0},
+  date         = {2024-06-18},
+  url          = {https://github.com/your‑org/SvPhaser}
+}
+```
+
+
+
+
+## License
+`SvPhaser` is released under the MIT License – see [`LICENSE`](LICENSE).
+
+
+
+
+
+## 📬 Contact
+
+Developed by **Team5** (*BioAI Hackathon*) – Sachin Gadakh & Pranjul Mishra.
+
+Lead contacts:
+• [pranjul.mishra@proton.me](mailto:pranjul.mishra@proton.me)
+• [s.gadakh@cent.uw.edu.pl](mailto:s.gadakh@cent.uw.edu.pl)
+
+Feedback, feature requests and bug reports are all appreciated — feel free to open a GitHub issue or reach out by e‑mail.
+
+---
+
+*Happy phasing!*

svphaser-2.0.1/pyproject.toml

@@ -0,0 +1,127 @@
+# -------------------------------------------------------------------
+#  SvPhaser • project metadata (PEP-621) with hatch-vcs versioning
+# -------------------------------------------------------------------
+[build-system]
+requires = ["hatchling>=1.24", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "svphaser"
+dynamic = ["version"]
+description = "Structural-variant phasing from HP-tagged long-read BAMs"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "SvPhaser Team", email = "you@lab.org" }]
+keywords = ["genomics", "structural-variants", "phasing", "long-reads", "ONT", "BAM", "VCF"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Operating System :: OS Independent",
+]
+
+dependencies = [
+  "pysam>=0.23",
+  "cyvcf2>=0.30",
+  "typer>=0.14",
+  "pandas>=2.1",
+]
+
+[project.optional-dependencies]
+plots = ["matplotlib>=3.7"]
+bench = ["pytest-benchmark>=4.0", "py-spy>=0.3"]
+dev = [
+  "pytest>=8",
+  "pytest-cov>=5",
+  "pytest-xdist>=3.5",
+  "hypothesis>=6.90",
+  "ruff>=0.5",
+  "mypy>=1.8",
+  "black>=24.3",
+  "pre-commit>=3.6",
+  "build>=1.2",
+  "twine>=5.0",
+  "tox>=4.10",
+  "pandas-stubs>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/your-org/svphaser"
+Issues   = "https://github.com/your-org/svphaser/issues"
+Source   = "https://github.com/your-org/svphaser"
+
+[project.scripts]
+svphaser = "svphaser.cli:app"
+
+# -------------------------------------------------------------------
+#  Hatch build config (src/ layout + typed package)
+# -------------------------------------------------------------------
+[tool.hatch.build.targets.wheel]
+packages = ["src/svphaser"]
+include = ["src/svphaser/py.typed"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/**", "README.md", "LICENSE", "pyproject.toml"]
+
+# Version from Git tags like v2.0.0 → 2.0.0
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/svphaser/_version.py"
+tag-pattern = "v(?P<version>.+)"
+
+# -------------------------------------------------------------------
+#  Tooling (ruff / black / mypy / pytest / coverage)
+# -------------------------------------------------------------------
+[tool.black]
+line-length = 100
+target-version = ["py39"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+exclude = [
+  "notebooks/**",
+  "docs/**/Presentation*/**",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C90"]
+ignore = ["E203"]  # black-compatible slicing
+
+[tool.ruff.lint.mccabe]
+max-complexity = 12
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+show_error_codes = true
+warn_unreachable = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-q --strict-markers --disable-warnings"
+testpaths = ["tests"]
+xfail_strict = true
+
+[tool.coverage.run]
+branch = true
+source = ["svphaser"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "if TYPE_CHECKING:",
+  "raise NotImplementedError",
+]
+precision = 1

svphaser-2.0.1/src/svphaser/__init__.py

@@ -0,0 +1,88 @@
+"""Top-level SvPhaser package.
+
+Public surface kept tiny: a version string and a convenience helper
+that calls the library’s main phasing routine.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# --------------------------------------------------------------------
+# Robust version lookup:
+# - Prefer installed package metadata (works for wheels and PEP 660 editables)
+# - Fall back to placeholder in _version.py for raw-source/dev use
+# --------------------------------------------------------------------
+try:
+    from importlib.metadata import version as _pkg_version  # Python 3.8+
+
+    __version__ = _pkg_version("svphaser")
+except Exception:
+    try:
+        from ._version import __version__  # "0+unknown" in repo; overwritten in builds
+    except Exception:  # highly defensive
+        __version__ = "0+unknown"
+
+# Centralized defaults (keep CLI in sync)
+DEFAULT_MIN_SUPPORT: int = 10
+DEFAULT_MAJOR_DELTA: float = 0.70
+DEFAULT_EQUAL_DELTA: float = 0.25
+DEFAULT_GQ_BINS: str = "30:High,10:Moderate"
+
+
+def phase(
+    sv_vcf: Path | str,
+    bam: Path | str,
+    /,
+    *,
+    out_dir: Path | str = ".",
+    min_support: int = DEFAULT_MIN_SUPPORT,
+    major_delta: float = DEFAULT_MAJOR_DELTA,
+    equal_delta: float = DEFAULT_EQUAL_DELTA,
+    gq_bins: str = DEFAULT_GQ_BINS,
+    threads: int | None = None,
+) -> tuple[Path, Path]:
+    """Phase *sv_vcf* using HP-tagged *bam*, writing outputs into *out_dir*.
+
+    Thin wrapper around :py:func:`svphaser.phasing.io.phase_vcf` so users/tests
+    can skip importing submodules.
+
+    Returns
+    -------
+    (out_vcf_path, out_csv_path)
+    """
+    from .phasing.io import phase_vcf  # local import avoids heavy deps at import-time
+
+    out_dir_p = Path(out_dir)
+    out_dir_p.mkdir(parents=True, exist_ok=True)
+
+    stem = Path(sv_vcf).name
+    if stem.endswith(".vcf.gz"):
+        stem = stem[:-7]
+    elif stem.endswith(".vcf"):
+        stem = stem[:-4]
+
+    out_vcf = out_dir_p / f"{stem}_phased.vcf"
+    out_csv = out_dir_p / f"{stem}_phased.csv"
+
+    phase_vcf(
+        sv_vcf,
+        bam,
+        out_dir=out_dir_p,  # type: ignore[arg-type]
+        min_support=min_support,
+        major_delta=major_delta,
+        equal_delta=equal_delta,
+        gq_bins=gq_bins,  # type: ignore[arg-type]
+        threads=threads,
+    )
+    return out_vcf, out_csv
+
+
+__all__ = [
+    "phase",
+    "__version__",
+    "DEFAULT_MIN_SUPPORT",
+    "DEFAULT_MAJOR_DELTA",
+    "DEFAULT_EQUAL_DELTA",
+    "DEFAULT_GQ_BINS",
+]

svphaser-2.0.1/src/svphaser/__main__.py

@@ -0,0 +1,5 @@
+# src/svphaser/__main__.py
+from .cli import app
+
+if __name__ == "__main__":
+    app()

svphaser-2.0.1/src/svphaser/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '2.0.1'
+__version_tuple__ = version_tuple = (2, 0, 1)
+
+__commit_id__ = commit_id = None

svphaser-2.0.1/src/svphaser/cli.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+svphaser.cli
+============
+Command-line interface for **SvPhaser**.
+
+The program writes two files inside **--out-dir** (or the CWD):
+
+* ``<stem>_phased.vcf``   (uncompressed; GT/GQ and optional HP_GQBIN injected)
+* ``<stem>_phased.csv``   (tabular summary including gq_label column)
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from svphaser import (
+    DEFAULT_EQUAL_DELTA,
+    DEFAULT_GQ_BINS,
+    DEFAULT_MAJOR_DELTA,
+    DEFAULT_MIN_SUPPORT,
+    __version__,
+)
+
+app = typer.Typer(add_completion=False, rich_markup_mode="rich")
+
+
+def _version_callback(value: bool):
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            help="Show SvPhaser version and exit.",
+            is_flag=True,
+            callback=_version_callback,
+        ),
+    ] = None
+):
+    """SvPhaser – Structural-variant phasing from HP-tagged long-read BAMs."""
+    # no-op; callback handles --version
+    return
+
+
+# ──────────────────────────────────────────────────────────────────────────
+#  phase command
+# ──────────────────────────────────────────────────────────────────────────
+@app.command("phase")
+def phase_cmd(
+    sv_vcf: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            help="Input *un-phased* SV VCF (.vcf or .vcf.gz)",
+        ),
+    ],
+    bam: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            help="Long-read BAM/CRAM with HP tags",
+        ),
+    ],
+    out_dir: Annotated[
+        Path,
+        typer.Option(
+            "--out-dir",
+            "-o",
+            exists=False,
+            file_okay=False,
+            dir_okay=True,
+            writable=True,
+            help=(
+                "Directory in which to write <stem>_phased.vcf & .csv "
+                "(created if missing; defaults to current dir)."
+            ),
+            show_default=True,
+        ),
+    ] = Path("."),
+    # ---------- thresholds ------------------------------------------------
+    min_support: Annotated[
+        int,
+        typer.Option(
+            help=(
+                "Minimum HP-tagged reads per haplotype. "
+                "SVs where *both* n1 AND n2 fall below this "
+                "are dropped entirely."
+            ),
+            show_default=True,
+        ),
+    ] = DEFAULT_MIN_SUPPORT,
+    major_delta: Annotated[
+        float,
+        typer.Option(
+            help="r >= this ⇒ strong majority ⇒ GT 1|0 or 0|1",
+            show_default=True,
+        ),
+    ] = DEFAULT_MAJOR_DELTA,
+    equal_delta: Annotated[
+        float,
+        typer.Option(
+            help="|n1−n2|/N ≤ this ⇒ near-tie ⇒ GT 1|1",
+            show_default=True,
+        ),
+    ] = DEFAULT_EQUAL_DELTA,
+    # ---------- confidence bins ------------------------------------------
+    gq_bins: Annotated[
+        str,
+        typer.Option(
+            help=(
+                "Comma-separated GQ≥threshold:Label definitions "
+                "(e.g. '30:High,10:Moderate'). Labels appear in the CSV "
+                "[gq_label] and in the VCF INFO field HP_GQBIN when set."
+            ),
+            show_default=True,
+        ),
+    ] = DEFAULT_GQ_BINS,
+    # ---------- multiprocessing ------------------------------------------
+    threads: Annotated[
+        int | None,
+        typer.Option(
+            "-t",
+            "--threads",
+            help="Worker processes to use (defaults to all CPU cores).",
+            show_default=True,
+        ),
+    ] = None,
+) -> None:
+    """Phase structural variants using HP-tagged read evidence."""
+    # Initialise logging BEFORE we import anything that might log
+    from svphaser.logging import init as _init_logging
+
+    _init_logging("INFO")  # or "DEBUG" if you want more detail
+
+    # Resolve output paths
+    if not out_dir.exists():
+        out_dir.mkdir(parents=True)
+
+    stem = sv_vcf.name
+    if stem.endswith(".vcf.gz"):
+        stem = stem[:-7]
+    elif stem.endswith(".vcf"):
+        stem = stem[:-4]
+
+    out_vcf = out_dir / f"{stem}_phased.vcf"
+    out_csv = out_dir / f"{stem}_phased.csv"
+
+    # Lazy import so `svphaser --help` works without heavy deps
+    from svphaser.phasing.io import phase_vcf
+
+    try:
+        phase_vcf(
+            sv_vcf,
+            bam,
+            out_dir=out_dir,  # type: ignore[arg-type]
+            min_support=min_support,
+            major_delta=major_delta,
+            equal_delta=equal_delta,
+            gq_bins=gq_bins,  # type: ignore[arg-type]
+            threads=threads,
+        )
+        typer.secho(f"✔ Phased VCF → {out_vcf}", fg=typer.colors.GREEN)
+        typer.secho(f"✔ Phased CSV → {out_csv}", fg=typer.colors.GREEN)
+    except Exception:  # pragma: no cover
+        typer.secho(
+            "[SvPhaser] 💥  Unhandled error during phasing",
+            fg=typer.colors.RED,
+        )
+        raise

svphaser-2.0.1/src/svphaser/logging.py

@@ -0,0 +1,34 @@
+"""
+svphaser.logging
+================
+One-liner that gives us colour-free, concise log messages on stderr.
+
+Importing this module *once* anywhere in the program is enough.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Literal
+
+_Level = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+
+def init(level: _Level | int = "INFO") -> None:
+    """Install a basic stderr handler – safe to call multiple times."""
+    root = logging.getLogger()
+    if root.handlers:  # already initialised
+        return
+
+    logging.basicConfig(
+        level=level,
+        stream=sys.stderr,
+        format="%(levelname).1s | %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Convenience helper for module-level loggers."""
+    return logging.getLogger(name)

svphaser-2.0.1/src/svphaser/phasing/__init__.py

@@ -0,0 +1,20 @@
+# src/svphaser/phasing/__init__.py
+"""Public API for svphaser.phasing."""
+
+from __future__ import annotations
+
+import logging
+
+from .algorithms import classify_haplotype, phasing_gq
+from .io import phase_vcf
+from .types import WorkerOpts
+
+__all__ = [
+    "phase_vcf",
+    "classify_haplotype",
+    "phasing_gq",
+    "WorkerOpts",
+]
+
+# Library logging: don't emit anything unless the app configures it.
+logging.getLogger(__name__).addHandler(logging.NullHandler())

svphaser-2.0.1/src/svphaser/phasing/_workers.py

@@ -0,0 +1,106 @@
+"""
+svphaser.phasing._workers
+=========================
+Worker-process code.  Each worker:
+
+1. Opens the (possibly un-indexed) SV VCF.
+2. Scans only the records for *its* chromosome.
+3. Counts HP-tagged reads in the long-read BAM/CRAM.
+4. Classifies the haplotype + GQ, adds optional GQ-bin label.
+5. Returns a DataFrame to the parent.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+import pysam
+from cyvcf2 import Reader, Variant  # type: ignore
+
+from .algorithms import classify_haplotype
+from .types import WorkerOpts
+
+__all__ = ["_phase_chrom_worker"]
+
+
+def _count_hp_reads(
+    bam: pysam.AlignmentFile,
+    chrom: str,
+    start: int,
+    end: int,
+) -> tuple[int, int]:
+    hp1 = hp2 = 0
+    for read in bam.fetch(chrom, max(0, start - 1), end + 1):
+        if read.is_unmapped or read.is_secondary or read.is_supplementary:
+            continue
+        if not read.has_tag("HP"):
+            continue
+        tag = read.get_tag("HP")
+        if tag == 1:
+            hp1 += 1
+        elif tag == 2:
+            hp2 += 1
+    return hp1, hp2
+
+
+def _has_tabix_index(vcf_path: Path) -> bool:
+    """Return True if <file>.tbi or <file>.csi exists (supports .vcf.gz.{tbi,csi})."""
+    return (
+        vcf_path.with_suffix(vcf_path.suffix + ".tbi").exists()
+        or vcf_path.with_suffix(vcf_path.suffix + ".csi").exists()
+    )
+
+
+def _phase_chrom_worker(
+    chrom: str,
+    vcf_path: Path,
+    bam_path: Path,
+    opts: WorkerOpts,
+) -> pd.DataFrame:
+    bam = pysam.AlignmentFile(str(bam_path), "rb")
+    rdr = Reader(str(vcf_path))
+
+    rows: list[dict[str, object]] = []
+
+    # Try fast random access first, fall back to linear scan if that fails
+    use_region_iter = _has_tabix_index(vcf_path)
+    records_iter = (
+        rdr(f"{chrom}") if use_region_iter else (rec for rec in rdr if rec.CHROM == chrom)
+    )
+
+    for rec in records_iter:  # type: ignore[arg-type]
+        assert isinstance(rec, Variant)
+        sv_end = rec.end if getattr(rec, "end", None) is not None else rec.POS
+        n1, n2 = _count_hp_reads(bam, chrom, rec.POS, sv_end)
+
+        gt, gq = classify_haplotype(
+            n1,
+            n2,
+            min_support=opts.min_support,
+            major_delta=opts.major_delta,
+            equal_delta=opts.equal_delta,
+        )
+
+        row = dict(
+            chrom=chrom,
+            pos=rec.POS,  # cyvcf2 POS is already 1-based
+            id=rec.ID or ".",
+            svtype=rec.INFO.get("SVTYPE", "NA"),
+            n1=n1,
+            n2=n2,
+            gt=gt,
+            gq=gq,
+        )
+
+        if opts.gq_bins:
+            for thr, label in opts.gq_bins:
+                if gq >= thr:
+                    row["gq_label"] = label
+                    break
+
+        rows.append(row)  # type: ignore[assignment]
+
+    rdr.close()
+    bam.close()
+    return pd.DataFrame(rows)

svphaser-2.0.1/src/svphaser/phasing/algorithms.py

@@ -0,0 +1,71 @@
+"""Pure maths for SvPhaser – overflow-safe revision.
+
+1) Exact binomial tail for small depth (N ≤ 200).
+2) Continuity-corrected normal approximation for deep coverage (N > 200).
+3) Phred GQ capped at 99.
+"""
+
+from __future__ import annotations
+
+import math
+
+__all__ = ["classify_haplotype", "phasing_gq"]
+
+NORMAL_THRESHOLD = 200  # switch to Gaussian SF above this depth
+MAX_GQ = 99
+
+
+def phasing_gq(n1: int, n2: int) -> int:
+    """Return Phred-scaled Genotype Quality, overflow-safe for deep data."""
+    total = n1 + n2
+    if total == 0:
+        return 0
+
+    k = max(n1, n2)
+
+    if total > NORMAL_THRESHOLD:
+        mu = total / 2.0
+        sigma = math.sqrt(total * 0.25)
+        z = (k - 0.5 - mu) / sigma
+        p_err = 0.5 * math.erfc(z / math.sqrt(2.0))  # survival function
+    else:
+        p = 0.5
+        tail = 0.0
+        for i in range(k, total + 1):
+            tail += math.comb(total, i) * (p**i) * ((1 - p) ** (total - i))
+        p_err = tail
+
+    p_err = max(p_err, 1e-300)  # guard log(0)
+    gq = int(round(-10.0 * math.log10(p_err)))
+    return min(gq, MAX_GQ)
+
+
+def classify_haplotype(
+    n1: int,
+    n2: int,
+    *,
+    min_support: int = 10,
+    major_delta: float = 0.70,
+    equal_delta: float = 0.25,
+) -> tuple[str, int]:
+    """Return (GT, GQ) using ratio thresholds and an overflow-safe GQ."""
+    total = n1 + n2
+
+    if n1 < min_support and n2 < min_support:
+        return "./.", 0
+    if total == 0:
+        return "./.", 0
+
+    gq = phasing_gq(n1, n2)
+    r1 = n1 / total
+    r2 = n2 / total
+
+    if r1 >= major_delta:
+        gt = "1|0"
+    elif r2 >= major_delta:
+        gt = "0|1"
+    elif abs(n1 - n2) / total <= equal_delta:
+        gt = "1|1"
+    else:
+        gt = "./."
+    return gt, gq

svphaser-2.0.1/src/svphaser/phasing/io.py

@@ -0,0 +1,258 @@
+"""
+svphaser.phasing.io
+===================
+High-level “engine” – orchestrates per-chromosome workers, merges results,
+applies the global depth filter, then writes CSV + VCF.
+
+Workers receive only simple (pickle-safe) arguments; each worker opens its
+own BAM/VCF to avoid sharing handles between processes.
+"""
+
+from __future__ import annotations
+
+import logging
+import multiprocessing as mp
+from pathlib import Path
+
+import pandas as pd
+from cyvcf2 import Reader
+
+from ._workers import _phase_chrom_worker
+from .types import GQBin, WorkerOpts
+
+__all__ = ["phase_vcf"]
+
+logger = logging.getLogger(__name__)
+
+
+def phase_vcf(
+    sv_vcf: Path,
+    bam: Path,
+    *,
+    out_dir: Path,
+    min_support: int,
+    major_delta: float,
+    equal_delta: float,
+    gq_bins: str,
+    threads: int | None,
+) -> None:
+    """Phase *sv_vcf* against *bam* and write outputs to *out_dir*.
+
+    Files:
+      - *_phased.vcf
+      - *_phased.csv
+      - *_dropped_svs.csv
+    """
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1 ─ Parse --gq-bins → list[(int,label)]
+    bins: list[GQBin] = []
+    if gq_bins.strip():
+        for part in gq_bins.split(","):
+            thr_lbl = part.strip()
+            if not thr_lbl:
+                continue
+            try:
+                thr_s, lbl = thr_lbl.split(":")
+            except ValueError as err:
+                raise ValueError(
+                    f"Invalid gq-bin specifier: '{thr_lbl}'. " "Use '30:High,10:Moderate'."
+                ) from err
+            bins.append((int(thr_s), lbl))
+        bins.sort(key=lambda x: x[0], reverse=True)
+
+    # 2 ─ Build immutable options holder for workers
+    opts = WorkerOpts(
+        min_support=min_support,
+        major_delta=major_delta,
+        equal_delta=equal_delta,
+        gq_bins=bins,
+    )
+
+    # 3 ─ Discover chromosomes (cheap – no variants parsed yet)
+    rdr = Reader(str(sv_vcf))
+    chroms: tuple[str, ...] = tuple(rdr.seqnames)
+    rdr.close()
+
+    # 4 ─ Launch one worker per chromosome (or ≤threads)
+    worker_args: list[tuple[str, Path, Path, WorkerOpts]] = [(c, sv_vcf, bam, opts) for c in chroms]
+
+    threads = threads or mp.cpu_count() or 1
+    logger.info("SvPhaser ▶ workers: %d", threads)
+
+    dataframes: list[pd.DataFrame] = []
+
+    # Use 'fork' when available (fast on Linux); fall back to 'spawn' elsewhere.
+    try:
+        ctx = mp.get_context("fork")
+    except ValueError:
+        ctx = mp.get_context("spawn")
+
+    if threads == 1:
+        # Serial path is handy for debugging
+        for args in worker_args:
+            df = _phase_chrom_worker(*args)
+            dataframes.append(df)
+            chrom = df.iloc[0]["chrom"] if not df.empty else "?"
+            logger.info("chr %-6s ✔ phased %5d SVs", chrom, len(df))
+    else:
+        with ctx.Pool(processes=threads) as pool:
+            for df in pool.starmap(_phase_chrom_worker, worker_args, chunksize=1):
+                dataframes.append(df)
+                chrom = df.iloc[0]["chrom"] if not df.empty else "?"
+                logger.info("chr %-6s ✔ phased %5d SVs", chrom, len(df))
+
+    # 5 ─ Merge & apply *global* depth filter
+    if dataframes:
+        merged = pd.concat(dataframes, ignore_index=True)
+    else:
+        merged = pd.DataFrame(
+            columns=["chrom", "pos", "id", "svtype", "n1", "n2", "gt", "gq", "gq_label"]
+        )
+
+    pre = len(merged)
+    keep = ~((merged["n1"] < min_support) & (merged["n2"] < min_support))
+
+    stem = sv_vcf.name.removesuffix(".vcf.gz").removesuffix(".vcf")
+
+    # Save dropped SVs for transparency
+    dropped_csv = out_dir / f"{stem}_dropped_svs.csv"
+    merged.loc[~keep].to_csv(dropped_csv, index=False)
+    logger.info("Dropped SVs → %s (%d SVs)", dropped_csv, int((~keep).sum()))
+
+    kept = merged.loc[keep].reset_index(drop=True)
+    if dropped := pre - len(kept):
+        logger.info("Depth filter removed %d SVs", dropped)
+
+    # 6 ─ Write CSV
+    out_csv = out_dir / f"{stem}_phased.csv"
+    kept.to_csv(out_csv, index=False)
+    logger.info("CSV → %s  (%d SVs)", out_csv, len(kept))
+
+    # 7 ─ Write VCF
+    out_vcf = out_dir / f"{stem}_phased.vcf"
+    _write_phased_vcf(out_vcf, sv_vcf, kept, gqbin_in_header=bool(bins))
+    logger.info("VCF → %s", out_vcf)
+
+
+# ──────────────────────────────────────────────────────────────────────
+#  Small helpers to keep complexity down
+# ──────────────────────────────────────────────────────────────────────
+def _vcf_info_lookup(
+    in_vcf: Path,
+) -> tuple[dict[tuple[str, int, str], dict[str, object]], list[str], str]:
+    """Scan input VCF once: return (lookup, raw_header_lines, sample_name)."""
+    rdr = Reader(str(in_vcf))
+    raw_header_lines = rdr.raw_header.strip().splitlines()
+    sample_name = rdr.samples[0] if rdr.samples else "SAMPLE"
+
+    lookup: dict[tuple[str, int, str], dict[str, object]] = {}
+    for rec in rdr:
+        key = (rec.CHROM, rec.POS, rec.ID or ".")
+        info_dict: dict[str, object] = {}
+        for k in rec.INFO:
+            info_key = k[0] if isinstance(k, tuple) else k
+            v = rec.INFO.get(info_key)
+            if v is not None:
+                info_dict[info_key] = v
+        lookup[key] = {
+            "REF": rec.REF,
+            "ALT": rec.ALT[0] if rec.ALT else "<N>",
+            "QUAL": rec.QUAL if rec.QUAL is not None else ".",
+            "FILTER": rec.FILTER if rec.FILTER else "PASS",
+            "INFO": info_dict,
+        }
+    rdr.close()
+    return lookup, raw_header_lines, sample_name
+
+
+def _write_headers(
+    out,
+    raw_header_lines: list[str],
+    sample_name: str,
+    *,
+    gqbin_in_header: bool,
+) -> None:
+    """Write preserved meta headers + ensure GT/GQ/GQBIN, then the column header."""
+    have_gt = any("##FORMAT=<ID=GT" in ln for ln in raw_header_lines)
+    have_gq = any("##FORMAT=<ID=GQ" in ln for ln in raw_header_lines)
+    have_gqbin = any("##INFO=<ID=GQBIN" in ln for ln in raw_header_lines)
+
+    for line in raw_header_lines:
+        if line.startswith("##"):
+            out.write(line.rstrip() + "\n")
+
+    if not have_gt:
+        out.write('##FORMAT=<ID=GT,Number=1,Type=String,Description="Phased genotype">\n')
+    if not have_gq:
+        out.write(
+            "##FORMAT=<ID=GQ,Number=1,Type=Integer," 'Description="Genotype Quality (Phred)">\n'
+        )
+    if gqbin_in_header and not have_gqbin:
+        out.write(
+            "##INFO=<ID=GQBIN,Number=1,Type=String," 'Description="GQ bin label from SvPhaser">\n'
+        )
+
+    out.write("#CHROM\tPOS\tID\tREF\tALT\tQUAL\tFILTER\tINFO\tFORMAT\t" + sample_name + "\n")
+
+
+def _compose_info_str(
+    orig_info: dict[str, object],
+    svtype: object,
+    gq_label: object,
+) -> str:
+    """Compose the INFO string with SVTYPE first, original keys (no duplicate), then GQBIN."""
+    items: list[str] = []
+    for k, v in orig_info.items():
+        if k == "SVTYPE":
+            continue
+        items.append(f"{k}={v}")
+    if svtype:
+        items.insert(0, f"SVTYPE={svtype}")
+    if gq_label is not None and pd.notnull(gq_label):
+        items.append(f"GQBIN={gq_label}")
+    return ";".join(items) if items else "."
+
+
+def _write_phased_vcf(
+    out_vcf: Path,
+    in_vcf: Path,
+    df: pd.DataFrame,
+    *,
+    gqbin_in_header: bool,
+) -> None:
+    """Write a phased VCF: tab-delimited, compliant, with ensured GT/GQ (and GQBIN if used)."""
+    lookup, raw_header_lines, sample_name = _vcf_info_lookup(in_vcf)
+
+    with open(out_vcf, "w", newline="") as out:
+        _write_headers(out, raw_header_lines, sample_name, gqbin_in_header=gqbin_in_header)
+
+        for row in df.itertuples(index=False):
+            chrom = str(getattr(row, "chrom", "."))
+            pos = int(getattr(row, "pos", 0))
+            vid = str(getattr(row, "id", "."))
+            gt = str(getattr(row, "gt", "./."))
+            gq = str(getattr(row, "gq", "0"))
+            svtype = getattr(row, "svtype", None)
+            gq_label = getattr(row, "gq_label", None)
+
+            info = lookup.get((chrom, pos, vid))
+            if info is None:
+                logger.warning("Could not find VCF info for %s:%s %s", chrom, pos, vid)
+                continue
+
+            info_str = _compose_info_str(info["INFO"], svtype, gq_label)
+
+            fields = [
+                chrom,
+                str(pos),
+                vid,
+                str(info["REF"]),
+                str(info["ALT"]),
+                str(info["QUAL"]),
+                str(info["FILTER"]),
+                info_str,
+                "GT:GQ",
+                f"{gt}:{gq}",
+            ]
+            out.write("\t".join(fields) + "\n")

svphaser-2.0.1/src/svphaser/phasing/types.py

@@ -0,0 +1,31 @@
+"""svphaser.phasing.types
+========================
+Central place for common type aliases & lightweight data classes.
+Keeping them here avoids circular imports and MyPy noise.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import NamedTuple
+
+SVKey = tuple[str, int, str]  # (chrom, POS, ID) – ID is "." if empty
+GQBin = tuple[int, str]  # (threshold, label), e.g. (30, "High")
+
+
+@dataclass(slots=True, frozen=True)
+class WorkerOpts:
+    """Non-changing knobs passed into every worker."""
+
+    min_support: int
+    major_delta: float
+    equal_delta: float
+    gq_bins: list[GQBin]  # already parsed by cli → phase_vcf
+
+
+class CallTuple(NamedTuple):
+    """Return type per-variant from algorithms.classify_haplotype()."""
+
+    gt: str
+    gq: int
+    gq_label: str | None