allelix 2.2.3__tar.gz → 2.3.0__tar.gz

{allelix-2.2.3 → allelix-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.2.3
+Version: 2.3.0
 Summary: Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first.
 Author: Allelix
 Maintainer-email: dial481 <dial481@users.noreply.github.com>
@@ -43,7 +43,7 @@ Dynamic: license-file
 
 **Open-source genotype analysis. Format-agnostic. Offline-first.**
 
-[Website](https://allelix.io) · [Quickstart](#quickstart) · [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md)
+[Website](https://allelix.io) · [Demo](https://analyze.allelix.io) · [Quickstart](#quickstart) · [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md)
 
 [![python](https://img.shields.io/pypi/pyversions/allelix.svg)](https://www.python.org/downloads/)
 [![pypi](https://img.shields.io/pypi/v/allelix.svg)](https://pypi.org/project/allelix/)
@@ -55,7 +55,7 @@ Dynamic: license-file
 
 # Allelix
 
-> **Status:** Production. Eight parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three enrichment sources (gnomAD + AlphaMissense + CADD), licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports, methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. Build auto-detection from position data (ADR-0021). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
+> **Status:** Production. Eight parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three enrichment sources (gnomAD + AlphaMissense + CADD), licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports and annotated VCF output for pipeline integration (v2.3.0+), methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. Build auto-detection from position data (ADR-0021). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
 
 ## Quickstart
 
@@ -80,6 +80,11 @@ allelix analyze trio.vcf.gz --sample HG002 --output report.html
 
 # Filter to a custom panel (rsIDs + gene names, one per line; '#' comments and blank lines ignored)
 allelix analyze your_genotype_file.txt --filter-file my_panel.txt --output report.html
+
+# Annotated VCF output — VCF-in / VCF-out for pipeline integration
+# Writes a valid VCF with annotations as INFO fields + full provenance in the header.
+# Refuses to overwrite; requires VCF or gVCF input.
+allelix analyze your_wgs.vcf.gz --vcf-out annotated.vcf
 ```
 
 See [Development](#development) for source installs and running tests, [Managing your data](#managing-your-data) for cache locations and cleanup, and [Troubleshooting](#troubleshooting) for common failure states.

{allelix-2.2.3 → allelix-2.3.0}/README.md

@@ -4,7 +4,7 @@
 
 **Open-source genotype analysis. Format-agnostic. Offline-first.**
 
-[Website](https://allelix.io) · [Quickstart](#quickstart) · [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md)
+[Website](https://allelix.io) · [Demo](https://analyze.allelix.io) · [Quickstart](#quickstart) · [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md)
 
 [![python](https://img.shields.io/pypi/pyversions/allelix.svg)](https://www.python.org/downloads/)
 [![pypi](https://img.shields.io/pypi/v/allelix.svg)](https://pypi.org/project/allelix/)
@@ -16,7 +16,7 @@
 
 # Allelix
 
-> **Status:** Production. Eight parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three enrichment sources (gnomAD + AlphaMissense + CADD), licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports, methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. Build auto-detection from position data (ADR-0021). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
+> **Status:** Production. Eight parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three enrichment sources (gnomAD + AlphaMissense + CADD), licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports and annotated VCF output for pipeline integration (v2.3.0+), methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. Build auto-detection from position data (ADR-0021). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
 
 ## Quickstart
 
@@ -41,6 +41,11 @@ allelix analyze trio.vcf.gz --sample HG002 --output report.html
 
 # Filter to a custom panel (rsIDs + gene names, one per line; '#' comments and blank lines ignored)
 allelix analyze your_genotype_file.txt --filter-file my_panel.txt --output report.html
+
+# Annotated VCF output — VCF-in / VCF-out for pipeline integration
+# Writes a valid VCF with annotations as INFO fields + full provenance in the header.
+# Refuses to overwrite; requires VCF or gVCF input.
+allelix analyze your_wgs.vcf.gz --vcf-out annotated.vcf
 ```
 
 See [Development](#development) for source installs and running tests, [Managing your data](#managing-your-data) for cache locations and cleanup, and [Troubleshooting](#troubleshooting) for common failure states.

{allelix-2.2.3 → allelix-2.3.0}/allelix/cli/_helpers.py

@@ -496,12 +496,29 @@ def _run_analysis_command(
     no_alphamissense: bool = False,
     no_cadd: bool = False,
     sample: str | None = None,
+    vcf_out: Path | None = None,
 ) -> None:
     resolved = resolve_data_dir(data_dir)
     if not no_update:
         _maybe_refresh_databases(resolved)
     parser = _resolve_parser(file_path, fmt, sample=sample)
 
+    # #150: --vcf-out preflight. Bail before any expensive setup so a
+    # user who mistyped the flag or aimed it at a 23andMe file finds
+    # out immediately, not after the analyze pipeline runs.
+    if vcf_out is not None:
+        if parser.name != "vcf":
+            raise click.ClickException(
+                f"--vcf-out requires VCF or gVCF input; got {parser.display_name} "
+                f"({parser.name!r}). Convert to VCF first, or drop --vcf-out to "
+                "produce the default report."
+            )
+        if vcf_out.exists():
+            raise click.ClickException(
+                f"--vcf-out refuses to overwrite an existing file: {vcf_out}. "
+                "Move or delete the existing file, or choose a different path."
+            )
+
     from allelix.config import load_config
 
     cfg = load_config(resolved)
@@ -554,6 +571,7 @@ def _run_analysis_command(
             cadd=cast("CaddAnnotator | None", cadd_annotator),
             high_value_rsids=hv_rsids,
             panel_rsids=rsids,
+            collect_vcf_write_inputs=vcf_out is not None,
         )
     finally:
         _unwire_parser_logging(counter, stderr_handler, snapshot)
@@ -650,6 +668,26 @@ def _run_analysis_command(
             )
         console.print(f"[green]Wrote {rendered:,} annotation(s) to {output}[/green]")
 
+    if vcf_out is not None:
+        from allelix.reports.vcf import render_vcf
+
+        # Pipeline populates result.vcf_write_inputs whenever the
+        # ``collect_vcf_write_inputs`` flag is set — which the preflight
+        # above guarantees for this branch — so the None case here is
+        # a defensive assert, not a runtime path.
+        assert result.vcf_write_inputs is not None
+        stamped = render_vcf(
+            input_path=file_path,
+            output_path=vcf_out,
+            build=result.build,
+            annotators_used=result.annotators_used,
+            annotations_by_key=result.vcf_write_inputs.annotations_by_key,
+            recovered_rsids=result.vcf_write_inputs.recovered_rsids,
+        )
+        console.print(
+            f"[green]Wrote annotated VCF with {stamped:,} stamped row(s) to {vcf_out}[/green]"
+        )
+
     console.print(
         f"[dim]{len(result.annotations):,} total annotation(s) from {len(ready)} "
         f"database(s) across {result.total_variants:,} variant(s).[/dim]"

{allelix-2.2.3 → allelix-2.3.0}/allelix/cli/_options.py

@@ -169,3 +169,17 @@ _SAMPLE_OPT = click.option(
         "or any plain VCF tool to list available samples."
     ),
 )
+# #150: annotated VCF output. Requires VCF/gVCF input (any other format
+# errors out early). Existing output paths are refused (no clobber, no
+# --force in v2.3.0). See ADR-0036 for the output contract.
+_VCF_OUT_OPT = click.option(
+    "--vcf-out",
+    "vcf_out",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help=(
+        "Write an annotated VCF at this path (v2.3.0+; experimental output "
+        "contract, ADR-0036). Requires VCF or gVCF input. Refuses to "
+        "overwrite an existing file."
+    ),
+)

{allelix-2.2.3 → allelix-2.3.0}/allelix/cli/analyze.py

@@ -29,6 +29,7 @@ from allelix.cli._options import (
     _REPORT_FORMAT_OPT,
     _SAMPLE_OPT,
     _SNPEDIA_MIN_MAG_OPT,
+    _VCF_OUT_OPT,
 )
 
 if TYPE_CHECKING:
@@ -61,6 +62,7 @@ if TYPE_CHECKING:
 @_NO_ALPHAMISSENSE_OPT
 @_NO_CADD_OPT
 @_SAMPLE_OPT
+@_VCF_OUT_OPT
 def analyze(
     file_path: Path,
     fmt: str | None,
@@ -82,6 +84,7 @@ def analyze(
     no_alphamissense: bool,
     no_cadd: bool,
     sample: str | None,
+    vcf_out: Path | None,
 ) -> None:
     """Annotate a genotype file against all ready reference databases."""
     filter_genes: frozenset[str] | None = None
@@ -113,4 +116,5 @@ def analyze(
         no_alphamissense=no_alphamissense,
         no_cadd=no_cadd,
         sample=sample,
+        vcf_out=vcf_out,
     )

{allelix-2.2.3 → allelix-2.3.0}/allelix/reports/_pipeline.py

@@ -39,6 +39,7 @@ if TYPE_CHECKING:
     from allelix.annotators.gnomad import GnomadAnnotator
     from allelix.models import Annotation, Variant
     from allelix.parsers.base import GenotypeParser
+    from allelix.reports.vcf import VcfWriteInputs
 
 
 # How many input variants to buffer while waiting for detection to
@@ -155,6 +156,12 @@ class AnalysisResult:
     # Used by the CLI to surface the GRCh38 rsID-less undercount
     # warning until #62's dbSNP resolution lands.
     rsidless_variant_count: int = 0
+    # #150: pipeline-produced inputs for the annotated VCF writer.
+    # Populated only when ``run_analysis`` is called with
+    # ``collect_vcf_write_inputs=True`` — the ``--vcf-out`` code path.
+    # None on every other analyze run (zero memory / CPU overhead on the
+    # default path). Consumed by ``allelix.reports.vcf.render_vcf``.
+    vcf_write_inputs: VcfWriteInputs | None = None
 
     def panel_coverage(
         self, filtered_annotations: list[Annotation] | None = None
@@ -439,6 +446,7 @@ def run_analysis(
     cadd: CaddAnnotator | None = None,
     high_value_rsids: set[str] | None = None,
     panel_rsids: frozenset[str] | None = None,
+    collect_vcf_write_inputs: bool = False,
 ) -> AnalysisResult:
     """Stream the file once; batch-annotate; return a fully-populated result.
 
@@ -515,6 +523,13 @@ def run_analysis(
     # back to position-keyed gnomAD / AlphaMissense lookups for resolved
     # rsIDs that don't appear in those caches' rsid index.
     resolved_coords: dict[str, tuple[str, int, str, str]] = {}
+    # #150: annotation dict keyed by (chrom, pos, ref, alt) for the
+    # annotated-VCF writer. Populated per batch inside ``_flush`` when
+    # ``collect_vcf_write_inputs`` is True. Values are references to the
+    # Annotation objects in ``annotations`` — enrichment mutations
+    # (gnomAD AF, AlphaMissense, CADD) that happen after streaming are
+    # visible through these refs without a per-annotation copy.
+    vcf_annotations_by_key: dict[tuple[str, int, str, str], list[Annotation]] = {}
 
     with contextlib.ExitStack() as stack:
         bound = [stack.enter_context(a) for a in annotators]
@@ -617,8 +632,29 @@ def run_analysis(
             nonlocal no_ref_total, rsidless_total
             no_ref_total += sum(1 for v in batch_buf if v.ref is None)
             rsidless_total += sum(1 for v in batch_buf if not v.rsid.startswith("rs"))
+            batch_new: list[Annotation] = []
             for annotator in bound:
-                annotations.extend(annotator.batch_annotate(batch_buf))
+                batch_new.extend(annotator.batch_annotate(batch_buf))
+            annotations.extend(batch_new)
+            # #150: collect writer inputs for this batch. Only touches
+            # variants whose ``ref`` is populated (VCF inputs; array
+            # data with ref=None can't produce a well-formed VCF key).
+            # Skips annotations with empty ``alt`` — GWAS rows keyed by
+            # rsID alone can't be VCF-stamped without allele context.
+            if collect_vcf_write_inputs:
+                rsid_to_coords: dict[str, tuple[str, int, str]] = {
+                    v.rsid: (v.chromosome, v.position, v.ref)
+                    for v in batch_buf
+                    if v.ref is not None
+                }
+                for a in batch_new:
+                    if not a.alt:
+                        continue
+                    coords = rsid_to_coords.get(a.rsid)
+                    if coords is None:
+                        continue
+                    chrom, pos, ref = coords
+                    vcf_annotations_by_key.setdefault((chrom, pos, ref, a.alt), []).append(a)
             batch_buf.clear()
 
         def _accept(v: Variant) -> None:
@@ -733,6 +769,21 @@ def run_analysis(
         result_annotated = None
         result_genotypes = None
 
+    vcf_write_inputs: VcfWriteInputs | None = None
+    if collect_vcf_write_inputs:
+        # Import here to avoid a top-level cycle with allelix.reports.vcf
+        # (which reaches into the annotator registry for attribution).
+        from allelix.reports.vcf import VcfWriteInputs as _VcfWriteInputs
+
+        vcf_recovered_rsids = {
+            (chrom, pos, ref, alt): rsid
+            for rsid, (chrom, pos, ref, alt) in resolved_coords.items()
+        }
+        vcf_write_inputs = _VcfWriteInputs(
+            annotations_by_key=vcf_annotations_by_key,
+            recovered_rsids=vcf_recovered_rsids,
+        )
+
     return AnalysisResult(
         file_path=file_path,
         parser_name=parser.name,
@@ -751,6 +802,7 @@ def run_analysis(
         panel_genotypes=result_genotypes,
         no_ref_variant_count=no_ref_total,
         rsidless_variant_count=rsidless_total,
+        vcf_write_inputs=vcf_write_inputs,
     )