allelix 1.8.4__tar.gz → 1.9.0__tar.gz

{allelix-1.8.4 → allelix-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 1.8.4
+Version: 1.9.0
 Summary: Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first.
 Author-email: dial481 <dial481@users.noreply.github.com>
 License-Expression: AGPL-3.0-or-later
@@ -44,8 +44,8 @@ Open-source command-line toolkit for analyzing raw genotype files from consumer
 > 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. **Latest: v1.8.4** —
-> `--no-cadd` flag for licensing exclusion parity.
+> No regex on prose anywhere in production. **Latest: v1.9.0** —
+> `--filter-file` flag for custom-panel filtering on `analyze`.
 > Release notes:
 > [`CHANGELOG.md`](https://github.com/dial481/allelix/blob/main/CHANGELOG.md).
 
@@ -61,6 +61,9 @@ allelix db update
 
 # Analyze a genotype file
 allelix analyze your_genotype_file.txt --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
 ```
 
 Requires Python 3.11+. See [Development](#development) for source installs and running tests.

{allelix-1.8.4 → allelix-1.9.0}/README.md

@@ -10,8 +10,8 @@ Open-source command-line toolkit for analyzing raw genotype files from consumer
 > 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. **Latest: v1.8.4** —
-> `--no-cadd` flag for licensing exclusion parity.
+> No regex on prose anywhere in production. **Latest: v1.9.0** —
+> `--filter-file` flag for custom-panel filtering on `analyze`.
 > Release notes:
 > [`CHANGELOG.md`](https://github.com/dial481/allelix/blob/main/CHANGELOG.md).
 
@@ -27,6 +27,9 @@ allelix db update
 
 # Analyze a genotype file
 allelix analyze your_genotype_file.txt --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
 ```
 
 Requires Python 3.11+. See [Development](#development) for source installs and running tests.

{allelix-1.8.4 → allelix-1.9.0}/allelix/cli.py

@@ -5,6 +5,7 @@
 from __future__ import annotations
 
 import logging
+import re
 import sys
 import time
 from pathlib import Path
@@ -195,6 +196,35 @@ def _format_from_path(output: Path, override: str | None) -> str:
     )
 
 
+_RSID_PATTERN = re.compile(r"^rs\d+$", re.IGNORECASE)
+
+
+def _parse_filter_file(path: Path) -> tuple[frozenset[str], frozenset[str]]:
+    r"""Parse a filter file into ``(gene_names, rsids)``.
+
+    Lines matching ``^rs\d+$`` (case-insensitive) are rsIDs. Everything
+    else is a gene name. Lines starting with ``#`` and blank lines are
+    ignored. Gene names starting with ``RS`` (e.g., RSPO1, RSF1) are
+    correctly classified as gene names, not rsIDs.
+
+    Input is case-tolerant; output is canonical: rsIDs are normalized to
+    lowercase (``rs1801133``), gene names to uppercase (``MTHFR``). The
+    filter recorded in JSON output therefore looks identical regardless
+    of how the user typed the entries in the filter file.
+    """
+    genes: set[str] = set()
+    rsids: set[str] = set()
+    for raw in path.read_text().splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if _RSID_PATTERN.match(line):
+            rsids.add(line.lower())
+        else:
+            genes.add(line.upper())
+    return frozenset(genes), frozenset(rsids)
+
+
 def _run_analysis_command(
     file_path: Path,
     fmt: str | None,
@@ -204,6 +234,7 @@ def _run_analysis_command(
     min_magnitude: float,
     category: str | None,
     genes: frozenset[str] | None,
+    rsids: frozenset[str] | None = None,
     build: str | None = None,
     include_benign: bool = False,
     gwas_min_magnitude: float | None = None,
@@ -335,6 +366,7 @@ def _run_analysis_command(
             min_magnitude=min_magnitude,
             category=category,
             genes=genes,
+            rsids=rsids,
             source_min_magnitudes=source_floors,
         )
         from allelix.reports._pipeline import rollup_gwas_duplicates
@@ -356,6 +388,7 @@ def _run_analysis_command(
                 min_magnitude=min_magnitude,
                 category=category,
                 genes=genes,
+                rsids=rsids,
                 source_min_magnitudes=source_floors,
             )
     else:
@@ -373,6 +406,7 @@ def _run_analysis_command(
                 min_magnitude=min_magnitude,
                 category=category,
                 genes=genes,
+                rsids=rsids,
                 source_min_magnitudes=source_floors,
                 diff=diff_result,
                 high_value_no_calls=hv_dicts,
@@ -384,6 +418,7 @@ def _run_analysis_command(
                 min_magnitude=min_magnitude,
                 category=category,
                 genes=genes,
+                rsids=rsids,
                 source_min_magnitudes=source_floors,
                 diff=diff_result,
                 high_value_no_calls=hv_warning_lines,
@@ -560,6 +595,16 @@ _DIFF_OPT = click.option(
         "Not a monitoring tool — use for version-to-version validation."
     ),
 )
+_FILTER_FILE_OPT = click.option(
+    "--filter-file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help=(
+        "Plain text file with rsIDs and/or gene names (one per line) to "
+        "filter the report. Lines matching '^rs\\d+$' are rsIDs; everything "
+        "else is a gene name. Comments (#) and blank lines are ignored."
+    ),
+)
 _NO_UPDATE_OPT = click.option(
     "--no-update",
     is_flag=True,
@@ -677,6 +722,7 @@ def _emit_build_diagnostics(result: object) -> None:
 @_GWAS_ALL_OPT
 @_EXCLUDE_SNPEDIA_OPT
 @_DIFF_OPT
+@_FILTER_FILE_OPT
 @_NO_UPDATE_OPT
 @_NO_GNOMAD_OPT
 @_NO_ALPHAMISSENSE_OPT
@@ -696,12 +742,20 @@ def analyze(
     gwas_all: bool,
     exclude_snpedia: bool,
     diff_path: Path | None,
+    filter_file: Path | None,
     no_update: bool,
     no_gnomad: bool,
     no_alphamissense: bool,
     no_cadd: bool,
 ) -> None:
     """Annotate a genotype file against all ready reference databases."""
+    filter_genes: frozenset[str] | None = None
+    filter_rsids: frozenset[str] | None = None
+    if filter_file is not None:
+        filter_genes, filter_rsids = _parse_filter_file(filter_file)
+        # Empty sets (file had only comments/blanks) still apply — they
+        # mean "match nothing", producing an empty report.
+
     _run_analysis_command(
         file_path=file_path,
         fmt=fmt,
@@ -710,7 +764,8 @@ def analyze(
         report_format=report_format,
         min_magnitude=min_magnitude,
         category=category,
-        genes=None,
+        genes=filter_genes,
+        rsids=filter_rsids,
         build=_normalize_cli_build(build),
         include_benign=include_benign,
         gwas_min_magnitude=gwas_min_magnitude,

{allelix-1.8.4 → allelix-1.9.0}/allelix/reports/_pipeline.py

@@ -105,6 +105,7 @@ class AnalysisResult:
         min_magnitude: float = 0.0,
         category: str | None = None,
         genes: Iterable[str] | None = None,
+        rsids: Iterable[str] | None = None,
         source_min_magnitudes: dict[str, float] | None = None,
     ) -> list[Annotation]:
         """Apply the standard filters and return a sorted list of annotations.
@@ -117,8 +118,14 @@ class AnalysisResult:
         entry, that value IS the floor for that source — it can raise OR
         lower the global ``min_magnitude``. Sources without an entry use
         the global floor.
+
+        `genes` and `rsids` combine with OR: when either is provided, an
+        annotation passes if it matches the gene set OR the rsid set.
+        Empty collections (vs None) mean "match nothing" — an empty
+        filter file produces an empty report.
         """
-        gene_set = {g.upper() for g in genes} if genes else None
+        gene_set = {g.upper() for g in genes} if genes is not None else None
+        rsid_set = {r.lower() for r in rsids} if rsids is not None else None
         out: list[Annotation] = []
         for a in self.annotations:
             if (
@@ -133,8 +140,11 @@ class AnalysisResult:
                 continue
             if category is not None and a.category != category:
                 continue
-            if gene_set is not None and (a.gene or "").upper() not in gene_set:
-                continue
+            if gene_set is not None or rsid_set is not None:
+                gene_match = gene_set is not None and (a.gene or "").upper() in gene_set
+                rsid_match = rsid_set is not None and a.rsid.lower() in rsid_set
+                if not gene_match and not rsid_match:
+                    continue
             out.append(a)
         out.sort(key=lambda a: (-a.magnitude, a.rsid))
         return out

{allelix-1.8.4 → allelix-1.9.0}/allelix/reports/html.py

@@ -951,6 +951,7 @@ def render_html(
     min_magnitude: float = 0.0,
     category: str | None = None,
     genes: Iterable[str] | None = None,
+    rsids: Iterable[str] | None = None,
     source_min_magnitudes: dict[str, float] | None = None,
     title: str = "Allelix Genotype Report",
     diff: DiffResult | None = None,
@@ -961,6 +962,7 @@ def render_html(
         min_magnitude=min_magnitude,
         category=category,
         genes=genes,
+        rsids=rsids,
         source_min_magnitudes=source_min_magnitudes,
     )
     filtered = rollup_gwas_duplicates(filtered)

{allelix-1.8.4 → allelix-1.9.0}/allelix/reports/json_report.py

@@ -103,6 +103,7 @@ def render_json(
     min_magnitude: float = 0.0,
     category: str | None = None,
     genes: Iterable[str] | None = None,
+    rsids: Iterable[str] | None = None,
     source_min_magnitudes: dict[str, float] | None = None,
     diff: DiffResult | None = None,
     high_value_no_calls: list[dict[str, str]] | None = None,
@@ -112,6 +113,7 @@ def render_json(
         min_magnitude=min_magnitude,
         category=category,
         genes=genes,
+        rsids=rsids,
         source_min_magnitudes=source_min_magnitudes,
     )
     filtered = rollup_gwas_duplicates(filtered)
@@ -134,7 +136,8 @@ def render_json(
         "filters": {
             "min_magnitude": min_magnitude,
             "category": category,
-            "genes": sorted(genes) if genes else None,
+            "genes": sorted(genes) if genes is not None else None,
+            "rsids": sorted(rsids) if rsids is not None else None,
         },
         "annotations": [_annotation_dict(a) for a in filtered],
     }

{allelix-1.8.4 → allelix-1.9.0}/allelix/reports/terminal.py

@@ -27,6 +27,7 @@ def render_terminal(
     min_magnitude: float = 0.0,
     category: str | None = None,
     genes: Iterable[str] | None = None,
+    rsids: Iterable[str] | None = None,
     source_min_magnitudes: dict[str, float] | None = None,
 ) -> int:
     """Render an AnalysisResult as a Rich table. Returns annotation count.
@@ -38,6 +39,7 @@ def render_terminal(
         min_magnitude=min_magnitude,
         category=category,
         genes=genes,
+        rsids=rsids,
         source_min_magnitudes=source_min_magnitudes,
     )
     filtered = rollup_gwas_duplicates(filtered)

{allelix-1.8.4 → allelix-1.9.0}/allelix.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 1.8.4
+Version: 1.9.0
 Summary: Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first.
 Author-email: dial481 <dial481@users.noreply.github.com>
 License-Expression: AGPL-3.0-or-later
@@ -44,8 +44,8 @@ Open-source command-line toolkit for analyzing raw genotype files from consumer
 > 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. **Latest: v1.8.4** —
-> `--no-cadd` flag for licensing exclusion parity.
+> No regex on prose anywhere in production. **Latest: v1.9.0** —
+> `--filter-file` flag for custom-panel filtering on `analyze`.
 > Release notes:
 > [`CHANGELOG.md`](https://github.com/dial481/allelix/blob/main/CHANGELOG.md).
 
@@ -61,6 +61,9 @@ allelix db update
 
 # Analyze a genotype file
 allelix analyze your_genotype_file.txt --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
 ```
 
 Requires Python 3.11+. See [Development](#development) for source installs and running tests.

{allelix-1.8.4 → allelix-1.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "allelix"
-version = "1.8.4"
+version = "1.9.0"
 description = "Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first."
 readme = "README.md"
 requires-python = ">=3.11"

{allelix-1.8.4 → allelix-1.9.0}/tests/test_cli.py

@@ -1579,6 +1579,201 @@ class TestNoCaddFlag:
         assert captured["no_cadd"] is True
 
 
+class TestParseFilterFile:
+    """Unit tests for _parse_filter_file (parser classification)."""
+
+    def test_rsid_lowercase(self, tmp_path):
+        from allelix.cli import _parse_filter_file
+
+        f = tmp_path / "filter.txt"
+        f.write_text("rs1801133\n")
+        genes, rsids = _parse_filter_file(f)
+        assert genes == frozenset()
+        assert rsids == frozenset({"rs1801133"})
+
+    def test_rsid_uppercase_normalized_to_lowercase(self, tmp_path):
+        """Input case-tolerant, output canonical: RS1801133 → rs1801133."""
+        from allelix.cli import _parse_filter_file
+
+        f = tmp_path / "filter.txt"
+        f.write_text("RS1801133\n")
+        genes, rsids = _parse_filter_file(f)
+        assert genes == frozenset()
+        assert rsids == frozenset({"rs1801133"})
+
+    def test_gene_lowercase_normalized_to_uppercase(self, tmp_path):
+        """Input case-tolerant, output canonical: mthfr → MTHFR."""
+        from allelix.cli import _parse_filter_file
+
+        f = tmp_path / "filter.txt"
+        f.write_text("mthfr\n")
+        genes, rsids = _parse_filter_file(f)
+        assert genes == frozenset({"MTHFR"})
+        assert rsids == frozenset()
+
+    def test_mixed_messy_case_normalized(self, tmp_path):
+        """End-to-end case-mixing across rsIDs and genes."""
+        from allelix.cli import _parse_filter_file
+
+        f = tmp_path / "filter.txt"
+        f.write_text("Rs1801133\ncomt\nRSPO1\nRS4680\nmThFr\n")
+        genes, rsids = _parse_filter_file(f)
+        assert genes == frozenset({"COMT", "RSPO1", "MTHFR"})
+        assert rsids == frozenset({"rs1801133", "rs4680"})
+
+    def test_gene_only(self, tmp_path):
+        from allelix.cli import _parse_filter_file
+
+        f = tmp_path / "filter.txt"
+        f.write_text("MTHFR\n")
+        genes, rsids = _parse_filter_file(f)
+        assert genes == frozenset({"MTHFR"})
+        assert rsids == frozenset()
+
+    def test_gene_starting_with_rs_prefix_is_gene_not_rsid(self, tmp_path):
+        """RSPO1, RSF1, RSC1A1 are real gene names — must not be classified as rsIDs."""
+        from allelix.cli import _parse_filter_file
+
+        f = tmp_path / "filter.txt"
+        f.write_text("RSPO1\nRSF1\nRSC1A1\n")
+        genes, rsids = _parse_filter_file(f)
+        assert genes == frozenset({"RSPO1", "RSF1", "RSC1A1"})
+        assert rsids == frozenset()
+
+    def test_mixed(self, tmp_path):
+        from allelix.cli import _parse_filter_file
+
+        f = tmp_path / "filter.txt"
+        f.write_text("rs1801133\nMTHFR\nrs4680\nCOMT\n")
+        genes, rsids = _parse_filter_file(f)
+        assert genes == frozenset({"MTHFR", "COMT"})
+        assert rsids == frozenset({"rs1801133", "rs4680"})
+
+    def test_comments_and_blanks_ignored(self, tmp_path):
+        from allelix.cli import _parse_filter_file
+
+        f = tmp_path / "filter.txt"
+        f.write_text("# this is a comment\n\nMTHFR\n\n# another\nrs1801133\n")
+        genes, rsids = _parse_filter_file(f)
+        assert genes == frozenset({"MTHFR"})
+        assert rsids == frozenset({"rs1801133"})
+
+    def test_empty_file_returns_empty_sets(self, tmp_path):
+        from allelix.cli import _parse_filter_file
+
+        f = tmp_path / "filter.txt"
+        f.write_text("")
+        genes, rsids = _parse_filter_file(f)
+        assert genes == frozenset()
+        assert rsids == frozenset()
+
+    def test_comments_only_returns_empty_sets(self, tmp_path):
+        from allelix.cli import _parse_filter_file
+
+        f = tmp_path / "filter.txt"
+        f.write_text("# only a comment\n# another\n\n")
+        genes, rsids = _parse_filter_file(f)
+        assert genes == frozenset()
+        assert rsids == frozenset()
+
+
+class TestFilterFileOnAnalyze:
+    """--filter-file is only on analyze; threads through _run_analysis_command."""
+
+    def test_analyze_rsid_only(self, mock_mhg_path, tmp_path, monkeypatch):
+        captured: dict = {}
+
+        def fake_run(**kwargs):
+            captured.update(kwargs)
+
+        monkeypatch.setattr("allelix.cli._run_analysis_command", fake_run)
+        f = tmp_path / "filter.txt"
+        f.write_text("rs1801133\n")
+        runner = CliRunner()
+        result = runner.invoke(main, ["analyze", str(mock_mhg_path), "--filter-file", str(f)])
+        assert result.exit_code == 0, result.output
+        assert captured["genes"] == frozenset()
+        assert captured["rsids"] == frozenset({"rs1801133"})
+
+    def test_analyze_gene_only(self, mock_mhg_path, tmp_path, monkeypatch):
+        captured: dict = {}
+
+        def fake_run(**kwargs):
+            captured.update(kwargs)
+
+        monkeypatch.setattr("allelix.cli._run_analysis_command", fake_run)
+        f = tmp_path / "filter.txt"
+        f.write_text("MTHFR\n")
+        runner = CliRunner()
+        result = runner.invoke(main, ["analyze", str(mock_mhg_path), "--filter-file", str(f)])
+        assert result.exit_code == 0, result.output
+        assert captured["genes"] == frozenset({"MTHFR"})
+        assert captured["rsids"] == frozenset()
+
+    def test_analyze_mixed_or_combination(self, mock_mhg_path, tmp_path, monkeypatch):
+        captured: dict = {}
+
+        def fake_run(**kwargs):
+            captured.update(kwargs)
+
+        monkeypatch.setattr("allelix.cli._run_analysis_command", fake_run)
+        f = tmp_path / "filter.txt"
+        f.write_text("rs1801133\nCOMT\n")
+        runner = CliRunner()
+        result = runner.invoke(main, ["analyze", str(mock_mhg_path), "--filter-file", str(f)])
+        assert result.exit_code == 0, result.output
+        assert captured["genes"] == frozenset({"COMT"})
+        assert captured["rsids"] == frozenset({"rs1801133"})
+
+    def test_analyze_empty_filter_passes_empty_sets(self, mock_mhg_path, tmp_path, monkeypatch):
+        """Empty filter file (only comments/blanks) threads empty frozensets through.
+
+        The empty-set → match-nothing semantic on AnalysisResult.filter()
+        is covered by a direct unit test in tests/test_pipeline_filter.py;
+        here we verify only that the CLI layer forwards empty frozensets,
+        not None.
+        """
+        captured: dict = {}
+
+        def fake_run(**kwargs):
+            captured.update(kwargs)
+
+        monkeypatch.setattr("allelix.cli._run_analysis_command", fake_run)
+        f = tmp_path / "filter.txt"
+        f.write_text("# only comments\n\n")
+        runner = CliRunner()
+        result = runner.invoke(main, ["analyze", str(mock_mhg_path), "--filter-file", str(f)])
+        assert result.exit_code == 0, result.output
+        assert captured["genes"] == frozenset()
+        assert captured["rsids"] == frozenset()
+
+    def test_analyze_filter_file_nonexistent_path_errors(self, mock_mhg_path):
+        runner = CliRunner()
+        result = runner.invoke(
+            main,
+            ["analyze", str(mock_mhg_path), "--filter-file", "/does/not/exist.txt"],
+        )
+        assert result.exit_code != 0
+
+    def test_methylation_does_not_have_filter_file(self, mock_mhg_path):
+        runner = CliRunner()
+        result = runner.invoke(
+            main,
+            ["methylation", str(mock_mhg_path), "--filter-file", "/tmp/x.txt"],
+        )
+        assert result.exit_code != 0
+        assert "no such option" in result.output.lower()
+
+    def test_pharmacogenomics_does_not_have_filter_file(self, mock_mhg_path):
+        runner = CliRunner()
+        result = runner.invoke(
+            main,
+            ["pharmacogenomics", str(mock_mhg_path), "--filter-file", "/tmp/x.txt"],
+        )
+        assert result.exit_code != 0
+        assert "no such option" in result.output.lower()
+
+
 class TestHighValueNoCalls:
     def test_stats_flags_dpyd_no_call(self, mock_mhg_path):
         """The MHG fixture has rs3918290 (DPYD) as a no-call; stats should flag it."""