allelix 1.8.2__tar.gz → 1.8.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 1.8.2
+Version: 1.8.4
 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,55 +44,27 @@ 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.2** — HTML
-> report redesign with dark mode, PLINK export, and automated PyPI
-> publishing. Release notes:
-> [`CHANGELOG.md`](CHANGELOG.md).
+> No regex on prose anywhere in production. **Latest: v1.8.4** —
+> `--no-cadd` flag for licensing exclusion parity.
+> Release notes:
+> [`CHANGELOG.md`](https://github.com/dial481/allelix/blob/main/CHANGELOG.md).
 
 ## Quickstart
 
-Requires Python 3.11+.
-
 ```bash
-git clone https://github.com/dial481/allelix
-cd allelix
-python -m venv .venv
-source .venv/bin/activate
-pip install -e ".[dev]"
-
-# Generate a synthetic test fixture
-python tests/generate_mock_data.py
-
-# Show summary statistics for a genotype file
-allelix stats tests/fixtures/mock_myhappygenes.txt
+pip install allelix
 
-# Download reference databases. First run downloads all sources (~15GB
-# on disk with gnomAD + AlphaMissense). Use --no-gnomad / --no-alphamissense
-# to skip the large enrichment databases. Re-runs skip unchanged sources.
+# Download reference databases (~15GB with all sources).
+# Use --no-gnomad / --no-alphamissense to skip the large ones.
 # CADD is opt-in: allelix db update --cadd
 allelix db update
-allelix db status   # see what's cached
 
-# Analyze a genotype file against all ready databases
-allelix analyze tests/fixtures/mock_myhappygenes.txt --min-magnitude 5
-
-# Same data, focused subsets
-allelix methylation tests/fixtures/mock_myhappygenes.txt
-allelix pharmacogenomics tests/fixtures/mock_myhappygenes.txt
-
-# Compare two genotype files (coverage, concordance, strand-flip detection)
-allelix compare file1.txt file2.txt
-
-# Export to PLINK1 binary format (.bed/.bim/.fam) for plink2, ADMIXTURE, PRSice
-# Expect ~60% monomorphic markers (A2=0) — genotyping chips probe many
-# intronic/intergenic sites outside gnomAD's exome coverage.
-allelix export plink genotype_file.txt -o output_prefix --build grch37
-
-# Output to a self-contained HTML or JSON report
-allelix analyze tests/fixtures/mock_myhappygenes.txt --output report.html
-allelix analyze tests/fixtures/mock_myhappygenes.txt --output report.json
+# Analyze a genotype file
+allelix analyze your_genotype_file.txt --output report.html
 ```
 
+Requires Python 3.11+. See [Development](#development) for source installs and running tests.
+
 ## Supported Formats
 
 | Format | Status | Notes |
@@ -126,7 +98,7 @@ Adding a new format means adding one file to `allelix/parsers/` and registering
 | GWAS Catalog | ✓ | Public domain (EBI/NHGRI). Trait–SNP associations with p-values and effect sizes. Carrier rule (ADR-0007) requires the user to carry the risk allele. P-value magnitude scoring (ADR-0024) maps continuous p-values to the 0–10 scale; unknown-risk-allele entries fire on rsID match alone but are capped at 3.0. |
 | gnomAD | ✓ | ODbL v1.0. **Enrichment annotator** — adds population allele frequency context to existing annotations. Shows how common each variant is in the general population (~16M exome variants from 730K individuals). A pathogenic variant that 35% of people carry reads very differently from one seen in 0.001%. Pre-built cache downloaded via `db update` (~6GB on disk). Use `--no-gnomad` to skip. |
 | AlphaMissense | ✓ | CC BY 4.0. **Enrichment annotator** — adds DeepMind's protein-structure-based pathogenicity predictions to existing annotations. Scores 71M missense variants on a 0–1 scale: <0.34 = likely benign, >0.564 = likely pathogenic. Complements ClinVar's expert classifications with computational predictions — especially valuable for variants ClinVar hasn't reviewed yet. Pre-built cache downloaded via `db update` (~8GB on disk). Use `--no-alphamissense` to skip. |
-| CADD | ✓ | LicenseRef-CADD (non-commercial). **Enrichment annotator** — adds PHRED-scaled deleteriousness scores from CADD v1.7. Ranks how deleterious any single-nucleotide variant is using 100+ annotation tracks (coding, non-coding, regulatory). PHRED 10 = top 10% most deleterious, 20 = top 1%, 30 = top 0.1%. **Opt-in** — disabled by default (`sources.cadd = false`). Enable via `allelix db update --cadd` or `allelix config set sources.cadd true`. Pre-built cache (~5 GB on disk, ~120M variant keys). Full mode available via pysam for GRCh38 data (`options.cadd_full = true`). Cache mode covers the large majority of variants present in gnomAD, AlphaMissense, and ClinVar — nearly every position allelix can annotate from its other databases. For genotyping chip data (23andMe, AncestryDNA, MyHappyGenes, etc.), cache and full mode produce effectively identical results because chip probes overwhelmingly target known, cataloged variants. Full mode adds coverage for novel or private variants that appear only in whole-genome or whole-exome sequencing data and are not in any pre-computed database. If your input is a genotyping chip file, cache mode is all you need. |
+| CADD | ✓ | LicenseRef-CADD (non-commercial). **Enrichment annotator** — adds PHRED-scaled deleteriousness scores from CADD v1.7. Ranks how deleterious any single-nucleotide variant is using 100+ annotation tracks (coding, non-coding, regulatory). PHRED 10 = top 10% most deleterious, 20 = top 1%, 30 = top 0.1%. **Opt-in** — disabled by default (`sources.cadd = false`). Enable via `allelix db update --cadd` or `allelix config set sources.cadd true`. Use `--no-cadd` to skip enrichment for a single run. Pre-built cache (~5 GB on disk, ~120M variant keys). Full mode available via pysam for GRCh38 data (`options.cadd_full = true`). Cache mode covers the large majority of variants present in gnomAD, AlphaMissense, and ClinVar — nearly every position allelix can annotate from its other databases. For genotyping chip data (23andMe, AncestryDNA, MyHappyGenes, etc.), cache and full mode produce effectively identical results because chip probes overwhelmingly target known, cataloged variants. Full mode adds coverage for novel or private variants that appear only in whole-genome or whole-exome sequencing data and are not in any pre-computed database. If your input is a genotyping chip file, cache mode is all you need. |
 
 ### Known PharmGKB limitation: reference-genotype rows where ClinVar and CPIC both lack data
 
@@ -183,7 +155,7 @@ allelix config set license.commercial true
 allelix config set license.cadd true
 ```
 
-CLI flags (`--no-gnomad`, `--no-alphamissense`, `--exclude-snpedia`, `--cadd`) override the config for a single run. The config sets the baseline; flags override per-invocation.
+CLI flags (`--no-gnomad`, `--no-alphamissense`, `--no-cadd`, `--exclude-snpedia`, `--cadd`) override the config for a single run. The config sets the baseline; flags override per-invocation.
 
 ### Database sizes and download times
 
@@ -215,7 +187,7 @@ Allelix source code is licensed under the **GNU Affero General Public License v3
 | SNPedia | snpedia.com | CC BY-NC-SA 3.0 US | Attribution required, **non-commercial only**. Use `--exclude-snpedia` to omit. |
 | gnomAD | gnomad.broadinstitute.org | ODbL v1.0 | Attribution required. Population allele frequencies for context; not a clinical annotator. Use `--no-gnomad` to omit. |
 | AlphaMissense | zenodo.org/records/10813168 | CC BY 4.0 | Attribution required. Cheng et al., Science 2023. Missense variant pathogenicity predictions. Use `--no-alphamissense` to omit. |
-| CADD | cadd.gs.washington.edu | LicenseRef-CADD | Attribution required, **non-commercial by default**. Commercial licenses available from UW CoMotion. Opt-in via `allelix db update --cadd`. |
+| CADD | cadd.gs.washington.edu | LicenseRef-CADD | Attribution required, **non-commercial by default**. Commercial licenses available from UW CoMotion. Opt-in via `allelix db update --cadd`. Use `--no-cadd` to omit. |
 
 **Commercial users:** When `license.commercial = true`, non-commercial sources are gated by a three-state permission model. SNPedia is permanently blocked (no commercial license is available). CADD is blocked by default but can be unlocked — the University of Washington offers commercial licenses at `https://els2.comotion.uw.edu/product/cadd-scores`; after purchasing, assert your license with `allelix config set license.cadd true` to re-enable CADD in commercial mode. All other databases (ClinVar, PharmGKB, GWAS Catalog, gnomAD, AlphaMissense) are compatible with commercial use. `allelix config show` displays the permission state for each source.
 
@@ -246,7 +218,7 @@ None of these are scraping errors. They are editorial inconsistencies on the sou
 
 ## Architecture & Design Decisions
 
-The "why" behind major design choices lives in [`docs/adr/`](docs/adr/README.md) as Architecture Decision Records. Read these before proposing changes that touch the parser/annotator interfaces, the regulatory posture, or the data-handling model.
+The "why" behind major design choices lives in [`docs/adr/`](https://github.com/dial481/allelix/blob/main/docs/adr/README.md) as Architecture Decision Records. Read these before proposing changes that touch the parser/annotator interfaces, the regulatory posture, or the data-handling model.
 
 Notable load-bearing ADRs:
 
@@ -256,7 +228,7 @@ Notable load-bearing ADRs:
 - **ADR-0009 — PharmGKB matches the user's exact normalized diploid call.**
 - **ADR-0015 — Mock data generators are the contract.** Fixture shape must mirror real data shape; invariants tested.
 
-Release history: see [`CHANGELOG.md`](CHANGELOG.md).
+Release history: see [`CHANGELOG.md`](https://github.com/dial481/allelix/blob/main/CHANGELOG.md).
 
 ## Development
 

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

@@ -10,55 +10,27 @@ 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.2** — HTML
-> report redesign with dark mode, PLINK export, and automated PyPI
-> publishing. Release notes:
-> [`CHANGELOG.md`](CHANGELOG.md).
+> No regex on prose anywhere in production. **Latest: v1.8.4** —
+> `--no-cadd` flag for licensing exclusion parity.
+> Release notes:
+> [`CHANGELOG.md`](https://github.com/dial481/allelix/blob/main/CHANGELOG.md).
 
 ## Quickstart
 
-Requires Python 3.11+.
-
 ```bash
-git clone https://github.com/dial481/allelix
-cd allelix
-python -m venv .venv
-source .venv/bin/activate
-pip install -e ".[dev]"
-
-# Generate a synthetic test fixture
-python tests/generate_mock_data.py
-
-# Show summary statistics for a genotype file
-allelix stats tests/fixtures/mock_myhappygenes.txt
+pip install allelix
 
-# Download reference databases. First run downloads all sources (~15GB
-# on disk with gnomAD + AlphaMissense). Use --no-gnomad / --no-alphamissense
-# to skip the large enrichment databases. Re-runs skip unchanged sources.
+# Download reference databases (~15GB with all sources).
+# Use --no-gnomad / --no-alphamissense to skip the large ones.
 # CADD is opt-in: allelix db update --cadd
 allelix db update
-allelix db status   # see what's cached
 
-# Analyze a genotype file against all ready databases
-allelix analyze tests/fixtures/mock_myhappygenes.txt --min-magnitude 5
-
-# Same data, focused subsets
-allelix methylation tests/fixtures/mock_myhappygenes.txt
-allelix pharmacogenomics tests/fixtures/mock_myhappygenes.txt
-
-# Compare two genotype files (coverage, concordance, strand-flip detection)
-allelix compare file1.txt file2.txt
-
-# Export to PLINK1 binary format (.bed/.bim/.fam) for plink2, ADMIXTURE, PRSice
-# Expect ~60% monomorphic markers (A2=0) — genotyping chips probe many
-# intronic/intergenic sites outside gnomAD's exome coverage.
-allelix export plink genotype_file.txt -o output_prefix --build grch37
-
-# Output to a self-contained HTML or JSON report
-allelix analyze tests/fixtures/mock_myhappygenes.txt --output report.html
-allelix analyze tests/fixtures/mock_myhappygenes.txt --output report.json
+# Analyze a genotype file
+allelix analyze your_genotype_file.txt --output report.html
 ```
 
+Requires Python 3.11+. See [Development](#development) for source installs and running tests.
+
 ## Supported Formats
 
 | Format | Status | Notes |
@@ -92,7 +64,7 @@ Adding a new format means adding one file to `allelix/parsers/` and registering
 | GWAS Catalog | ✓ | Public domain (EBI/NHGRI). Trait–SNP associations with p-values and effect sizes. Carrier rule (ADR-0007) requires the user to carry the risk allele. P-value magnitude scoring (ADR-0024) maps continuous p-values to the 0–10 scale; unknown-risk-allele entries fire on rsID match alone but are capped at 3.0. |
 | gnomAD | ✓ | ODbL v1.0. **Enrichment annotator** — adds population allele frequency context to existing annotations. Shows how common each variant is in the general population (~16M exome variants from 730K individuals). A pathogenic variant that 35% of people carry reads very differently from one seen in 0.001%. Pre-built cache downloaded via `db update` (~6GB on disk). Use `--no-gnomad` to skip. |
 | AlphaMissense | ✓ | CC BY 4.0. **Enrichment annotator** — adds DeepMind's protein-structure-based pathogenicity predictions to existing annotations. Scores 71M missense variants on a 0–1 scale: <0.34 = likely benign, >0.564 = likely pathogenic. Complements ClinVar's expert classifications with computational predictions — especially valuable for variants ClinVar hasn't reviewed yet. Pre-built cache downloaded via `db update` (~8GB on disk). Use `--no-alphamissense` to skip. |
-| CADD | ✓ | LicenseRef-CADD (non-commercial). **Enrichment annotator** — adds PHRED-scaled deleteriousness scores from CADD v1.7. Ranks how deleterious any single-nucleotide variant is using 100+ annotation tracks (coding, non-coding, regulatory). PHRED 10 = top 10% most deleterious, 20 = top 1%, 30 = top 0.1%. **Opt-in** — disabled by default (`sources.cadd = false`). Enable via `allelix db update --cadd` or `allelix config set sources.cadd true`. Pre-built cache (~5 GB on disk, ~120M variant keys). Full mode available via pysam for GRCh38 data (`options.cadd_full = true`). Cache mode covers the large majority of variants present in gnomAD, AlphaMissense, and ClinVar — nearly every position allelix can annotate from its other databases. For genotyping chip data (23andMe, AncestryDNA, MyHappyGenes, etc.), cache and full mode produce effectively identical results because chip probes overwhelmingly target known, cataloged variants. Full mode adds coverage for novel or private variants that appear only in whole-genome or whole-exome sequencing data and are not in any pre-computed database. If your input is a genotyping chip file, cache mode is all you need. |
+| CADD | ✓ | LicenseRef-CADD (non-commercial). **Enrichment annotator** — adds PHRED-scaled deleteriousness scores from CADD v1.7. Ranks how deleterious any single-nucleotide variant is using 100+ annotation tracks (coding, non-coding, regulatory). PHRED 10 = top 10% most deleterious, 20 = top 1%, 30 = top 0.1%. **Opt-in** — disabled by default (`sources.cadd = false`). Enable via `allelix db update --cadd` or `allelix config set sources.cadd true`. Use `--no-cadd` to skip enrichment for a single run. Pre-built cache (~5 GB on disk, ~120M variant keys). Full mode available via pysam for GRCh38 data (`options.cadd_full = true`). Cache mode covers the large majority of variants present in gnomAD, AlphaMissense, and ClinVar — nearly every position allelix can annotate from its other databases. For genotyping chip data (23andMe, AncestryDNA, MyHappyGenes, etc.), cache and full mode produce effectively identical results because chip probes overwhelmingly target known, cataloged variants. Full mode adds coverage for novel or private variants that appear only in whole-genome or whole-exome sequencing data and are not in any pre-computed database. If your input is a genotyping chip file, cache mode is all you need. |
 
 ### Known PharmGKB limitation: reference-genotype rows where ClinVar and CPIC both lack data
 
@@ -149,7 +121,7 @@ allelix config set license.commercial true
 allelix config set license.cadd true
 ```
 
-CLI flags (`--no-gnomad`, `--no-alphamissense`, `--exclude-snpedia`, `--cadd`) override the config for a single run. The config sets the baseline; flags override per-invocation.
+CLI flags (`--no-gnomad`, `--no-alphamissense`, `--no-cadd`, `--exclude-snpedia`, `--cadd`) override the config for a single run. The config sets the baseline; flags override per-invocation.
 
 ### Database sizes and download times
 
@@ -181,7 +153,7 @@ Allelix source code is licensed under the **GNU Affero General Public License v3
 | SNPedia | snpedia.com | CC BY-NC-SA 3.0 US | Attribution required, **non-commercial only**. Use `--exclude-snpedia` to omit. |
 | gnomAD | gnomad.broadinstitute.org | ODbL v1.0 | Attribution required. Population allele frequencies for context; not a clinical annotator. Use `--no-gnomad` to omit. |
 | AlphaMissense | zenodo.org/records/10813168 | CC BY 4.0 | Attribution required. Cheng et al., Science 2023. Missense variant pathogenicity predictions. Use `--no-alphamissense` to omit. |
-| CADD | cadd.gs.washington.edu | LicenseRef-CADD | Attribution required, **non-commercial by default**. Commercial licenses available from UW CoMotion. Opt-in via `allelix db update --cadd`. |
+| CADD | cadd.gs.washington.edu | LicenseRef-CADD | Attribution required, **non-commercial by default**. Commercial licenses available from UW CoMotion. Opt-in via `allelix db update --cadd`. Use `--no-cadd` to omit. |
 
 **Commercial users:** When `license.commercial = true`, non-commercial sources are gated by a three-state permission model. SNPedia is permanently blocked (no commercial license is available). CADD is blocked by default but can be unlocked — the University of Washington offers commercial licenses at `https://els2.comotion.uw.edu/product/cadd-scores`; after purchasing, assert your license with `allelix config set license.cadd true` to re-enable CADD in commercial mode. All other databases (ClinVar, PharmGKB, GWAS Catalog, gnomAD, AlphaMissense) are compatible with commercial use. `allelix config show` displays the permission state for each source.
 
@@ -212,7 +184,7 @@ None of these are scraping errors. They are editorial inconsistencies on the sou
 
 ## Architecture & Design Decisions
 
-The "why" behind major design choices lives in [`docs/adr/`](docs/adr/README.md) as Architecture Decision Records. Read these before proposing changes that touch the parser/annotator interfaces, the regulatory posture, or the data-handling model.
+The "why" behind major design choices lives in [`docs/adr/`](https://github.com/dial481/allelix/blob/main/docs/adr/README.md) as Architecture Decision Records. Read these before proposing changes that touch the parser/annotator interfaces, the regulatory posture, or the data-handling model.
 
 Notable load-bearing ADRs:
 
@@ -222,7 +194,7 @@ Notable load-bearing ADRs:
 - **ADR-0009 — PharmGKB matches the user's exact normalized diploid call.**
 - **ADR-0015 — Mock data generators are the contract.** Fixture shape must mirror real data shape; invariants tested.
 
-Release history: see [`CHANGELOG.md`](CHANGELOG.md).
+Release history: see [`CHANGELOG.md`](https://github.com/dial481/allelix/blob/main/CHANGELOG.md).
 
 ## Development
 

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

@@ -214,6 +214,7 @@ def _run_analysis_command(
     no_update: bool = False,
     no_gnomad: bool = False,
     no_alphamissense: bool = False,
+    no_cadd: bool = False,
 ) -> None:
     resolved = resolve_data_dir(data_dir)
     if not no_update:
@@ -256,12 +257,13 @@ def _run_analysis_command(
     ready = [a for a in ready if a.name != "alphamissense"]
 
     cadd_annotator = None
-    from allelix.annotators.cadd import CaddAnnotator
+    if not no_cadd:
+        from allelix.annotators.cadd import CaddAnnotator
 
-    for a in ready:
-        if isinstance(a, CaddAnnotator):
-            cadd_annotator = a
-            break
+        for a in ready:
+            if isinstance(a, CaddAnnotator):
+                cadd_annotator = a
+                break
     ready = [a for a in ready if a.name != "cadd"]
 
     if not_ready:
@@ -576,6 +578,12 @@ _NO_ALPHAMISSENSE_OPT = click.option(
     default=False,
     help="Skip AlphaMissense variant pathogenicity enrichment.",
 )
+_NO_CADD_OPT = click.option(
+    "--no-cadd",
+    is_flag=True,
+    default=False,
+    help="Skip CADD deleteriousness score enrichment.",
+)
 _BUILD_OPT = click.option(
     "--build",
     type=click.Choice(["grch37", "grch38", "auto"], case_sensitive=False),
@@ -672,6 +680,7 @@ def _emit_build_diagnostics(result: object) -> None:
 @_NO_UPDATE_OPT
 @_NO_GNOMAD_OPT
 @_NO_ALPHAMISSENSE_OPT
+@_NO_CADD_OPT
 def analyze(
     file_path: Path,
     fmt: str | None,
@@ -690,6 +699,7 @@ def analyze(
     no_update: bool,
     no_gnomad: bool,
     no_alphamissense: bool,
+    no_cadd: bool,
 ) -> None:
     """Annotate a genotype file against all ready reference databases."""
     _run_analysis_command(
@@ -711,6 +721,7 @@ def analyze(
         no_update=no_update,
         no_gnomad=no_gnomad,
         no_alphamissense=no_alphamissense,
+        no_cadd=no_cadd,
     )
 
 
@@ -868,6 +879,7 @@ def compare(file1: Path, file2: Path, fmt1: str | None, fmt2: str | None) -> Non
 @_NO_UPDATE_OPT
 @_NO_GNOMAD_OPT
 @_NO_ALPHAMISSENSE_OPT
+@_NO_CADD_OPT
 def methylation(
     file_path: Path,
     fmt: str | None,
@@ -886,6 +898,7 @@ def methylation(
     no_update: bool,
     no_gnomad: bool,
     no_alphamissense: bool,
+    no_cadd: bool,
 ) -> None:
     """Methylation-pathway-focused report (MTHFR, MTR, MTRR, COMT, CBS, …)."""
     excluded: set[str] = set()
@@ -912,6 +925,7 @@ def methylation(
         no_update=no_update,
         no_gnomad=no_gnomad,
         no_alphamissense=no_alphamissense,
+        no_cadd=no_cadd,
     )
 
 
@@ -933,6 +947,7 @@ def methylation(
 @_NO_UPDATE_OPT
 @_NO_GNOMAD_OPT
 @_NO_ALPHAMISSENSE_OPT
+@_NO_CADD_OPT
 def pharmacogenomics(
     file_path: Path,
     fmt: str | None,
@@ -951,6 +966,7 @@ def pharmacogenomics(
     no_update: bool,
     no_gnomad: bool,
     no_alphamissense: bool,
+    no_cadd: bool,
 ) -> None:
     """Pharmacogenomics-focused report (annotations from PharmGKB-style sources)."""
     excluded: set[str] = set()
@@ -977,6 +993,7 @@ def pharmacogenomics(
         no_update=no_update,
         no_gnomad=no_gnomad,
         no_alphamissense=no_alphamissense,
+        no_cadd=no_cadd,
     )
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 1.8.2
+Version: 1.8.4
 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,55 +44,27 @@ 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.2** — HTML
-> report redesign with dark mode, PLINK export, and automated PyPI
-> publishing. Release notes:
-> [`CHANGELOG.md`](CHANGELOG.md).
+> No regex on prose anywhere in production. **Latest: v1.8.4** —
+> `--no-cadd` flag for licensing exclusion parity.
+> Release notes:
+> [`CHANGELOG.md`](https://github.com/dial481/allelix/blob/main/CHANGELOG.md).
 
 ## Quickstart
 
-Requires Python 3.11+.
-
 ```bash
-git clone https://github.com/dial481/allelix
-cd allelix
-python -m venv .venv
-source .venv/bin/activate
-pip install -e ".[dev]"
-
-# Generate a synthetic test fixture
-python tests/generate_mock_data.py
-
-# Show summary statistics for a genotype file
-allelix stats tests/fixtures/mock_myhappygenes.txt
+pip install allelix
 
-# Download reference databases. First run downloads all sources (~15GB
-# on disk with gnomAD + AlphaMissense). Use --no-gnomad / --no-alphamissense
-# to skip the large enrichment databases. Re-runs skip unchanged sources.
+# Download reference databases (~15GB with all sources).
+# Use --no-gnomad / --no-alphamissense to skip the large ones.
 # CADD is opt-in: allelix db update --cadd
 allelix db update
-allelix db status   # see what's cached
 
-# Analyze a genotype file against all ready databases
-allelix analyze tests/fixtures/mock_myhappygenes.txt --min-magnitude 5
-
-# Same data, focused subsets
-allelix methylation tests/fixtures/mock_myhappygenes.txt
-allelix pharmacogenomics tests/fixtures/mock_myhappygenes.txt
-
-# Compare two genotype files (coverage, concordance, strand-flip detection)
-allelix compare file1.txt file2.txt
-
-# Export to PLINK1 binary format (.bed/.bim/.fam) for plink2, ADMIXTURE, PRSice
-# Expect ~60% monomorphic markers (A2=0) — genotyping chips probe many
-# intronic/intergenic sites outside gnomAD's exome coverage.
-allelix export plink genotype_file.txt -o output_prefix --build grch37
-
-# Output to a self-contained HTML or JSON report
-allelix analyze tests/fixtures/mock_myhappygenes.txt --output report.html
-allelix analyze tests/fixtures/mock_myhappygenes.txt --output report.json
+# Analyze a genotype file
+allelix analyze your_genotype_file.txt --output report.html
 ```
 
+Requires Python 3.11+. See [Development](#development) for source installs and running tests.
+
 ## Supported Formats
 
 | Format | Status | Notes |
@@ -126,7 +98,7 @@ Adding a new format means adding one file to `allelix/parsers/` and registering
 | GWAS Catalog | ✓ | Public domain (EBI/NHGRI). Trait–SNP associations with p-values and effect sizes. Carrier rule (ADR-0007) requires the user to carry the risk allele. P-value magnitude scoring (ADR-0024) maps continuous p-values to the 0–10 scale; unknown-risk-allele entries fire on rsID match alone but are capped at 3.0. |
 | gnomAD | ✓ | ODbL v1.0. **Enrichment annotator** — adds population allele frequency context to existing annotations. Shows how common each variant is in the general population (~16M exome variants from 730K individuals). A pathogenic variant that 35% of people carry reads very differently from one seen in 0.001%. Pre-built cache downloaded via `db update` (~6GB on disk). Use `--no-gnomad` to skip. |
 | AlphaMissense | ✓ | CC BY 4.0. **Enrichment annotator** — adds DeepMind's protein-structure-based pathogenicity predictions to existing annotations. Scores 71M missense variants on a 0–1 scale: <0.34 = likely benign, >0.564 = likely pathogenic. Complements ClinVar's expert classifications with computational predictions — especially valuable for variants ClinVar hasn't reviewed yet. Pre-built cache downloaded via `db update` (~8GB on disk). Use `--no-alphamissense` to skip. |
-| CADD | ✓ | LicenseRef-CADD (non-commercial). **Enrichment annotator** — adds PHRED-scaled deleteriousness scores from CADD v1.7. Ranks how deleterious any single-nucleotide variant is using 100+ annotation tracks (coding, non-coding, regulatory). PHRED 10 = top 10% most deleterious, 20 = top 1%, 30 = top 0.1%. **Opt-in** — disabled by default (`sources.cadd = false`). Enable via `allelix db update --cadd` or `allelix config set sources.cadd true`. Pre-built cache (~5 GB on disk, ~120M variant keys). Full mode available via pysam for GRCh38 data (`options.cadd_full = true`). Cache mode covers the large majority of variants present in gnomAD, AlphaMissense, and ClinVar — nearly every position allelix can annotate from its other databases. For genotyping chip data (23andMe, AncestryDNA, MyHappyGenes, etc.), cache and full mode produce effectively identical results because chip probes overwhelmingly target known, cataloged variants. Full mode adds coverage for novel or private variants that appear only in whole-genome or whole-exome sequencing data and are not in any pre-computed database. If your input is a genotyping chip file, cache mode is all you need. |
+| CADD | ✓ | LicenseRef-CADD (non-commercial). **Enrichment annotator** — adds PHRED-scaled deleteriousness scores from CADD v1.7. Ranks how deleterious any single-nucleotide variant is using 100+ annotation tracks (coding, non-coding, regulatory). PHRED 10 = top 10% most deleterious, 20 = top 1%, 30 = top 0.1%. **Opt-in** — disabled by default (`sources.cadd = false`). Enable via `allelix db update --cadd` or `allelix config set sources.cadd true`. Use `--no-cadd` to skip enrichment for a single run. Pre-built cache (~5 GB on disk, ~120M variant keys). Full mode available via pysam for GRCh38 data (`options.cadd_full = true`). Cache mode covers the large majority of variants present in gnomAD, AlphaMissense, and ClinVar — nearly every position allelix can annotate from its other databases. For genotyping chip data (23andMe, AncestryDNA, MyHappyGenes, etc.), cache and full mode produce effectively identical results because chip probes overwhelmingly target known, cataloged variants. Full mode adds coverage for novel or private variants that appear only in whole-genome or whole-exome sequencing data and are not in any pre-computed database. If your input is a genotyping chip file, cache mode is all you need. |
 
 ### Known PharmGKB limitation: reference-genotype rows where ClinVar and CPIC both lack data
 
@@ -183,7 +155,7 @@ allelix config set license.commercial true
 allelix config set license.cadd true
 ```
 
-CLI flags (`--no-gnomad`, `--no-alphamissense`, `--exclude-snpedia`, `--cadd`) override the config for a single run. The config sets the baseline; flags override per-invocation.
+CLI flags (`--no-gnomad`, `--no-alphamissense`, `--no-cadd`, `--exclude-snpedia`, `--cadd`) override the config for a single run. The config sets the baseline; flags override per-invocation.
 
 ### Database sizes and download times
 
@@ -215,7 +187,7 @@ Allelix source code is licensed under the **GNU Affero General Public License v3
 | SNPedia | snpedia.com | CC BY-NC-SA 3.0 US | Attribution required, **non-commercial only**. Use `--exclude-snpedia` to omit. |
 | gnomAD | gnomad.broadinstitute.org | ODbL v1.0 | Attribution required. Population allele frequencies for context; not a clinical annotator. Use `--no-gnomad` to omit. |
 | AlphaMissense | zenodo.org/records/10813168 | CC BY 4.0 | Attribution required. Cheng et al., Science 2023. Missense variant pathogenicity predictions. Use `--no-alphamissense` to omit. |
-| CADD | cadd.gs.washington.edu | LicenseRef-CADD | Attribution required, **non-commercial by default**. Commercial licenses available from UW CoMotion. Opt-in via `allelix db update --cadd`. |
+| CADD | cadd.gs.washington.edu | LicenseRef-CADD | Attribution required, **non-commercial by default**. Commercial licenses available from UW CoMotion. Opt-in via `allelix db update --cadd`. Use `--no-cadd` to omit. |
 
 **Commercial users:** When `license.commercial = true`, non-commercial sources are gated by a three-state permission model. SNPedia is permanently blocked (no commercial license is available). CADD is blocked by default but can be unlocked — the University of Washington offers commercial licenses at `https://els2.comotion.uw.edu/product/cadd-scores`; after purchasing, assert your license with `allelix config set license.cadd true` to re-enable CADD in commercial mode. All other databases (ClinVar, PharmGKB, GWAS Catalog, gnomAD, AlphaMissense) are compatible with commercial use. `allelix config show` displays the permission state for each source.
 
@@ -246,7 +218,7 @@ None of these are scraping errors. They are editorial inconsistencies on the sou
 
 ## Architecture & Design Decisions
 
-The "why" behind major design choices lives in [`docs/adr/`](docs/adr/README.md) as Architecture Decision Records. Read these before proposing changes that touch the parser/annotator interfaces, the regulatory posture, or the data-handling model.
+The "why" behind major design choices lives in [`docs/adr/`](https://github.com/dial481/allelix/blob/main/docs/adr/README.md) as Architecture Decision Records. Read these before proposing changes that touch the parser/annotator interfaces, the regulatory posture, or the data-handling model.
 
 Notable load-bearing ADRs:
 
@@ -256,7 +228,7 @@ Notable load-bearing ADRs:
 - **ADR-0009 — PharmGKB matches the user's exact normalized diploid call.**
 - **ADR-0015 — Mock data generators are the contract.** Fixture shape must mirror real data shape; invariants tested.
 
-Release history: see [`CHANGELOG.md`](CHANGELOG.md).
+Release history: see [`CHANGELOG.md`](https://github.com/dial481/allelix/blob/main/CHANGELOG.md).
 
 ## Development
 

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

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

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

@@ -1527,6 +1527,58 @@ class TestExcludeSnpedia:
         assert captured["exclude_sources"] == frozenset({"snpedia", "gwas"})
 
 
+class TestNoCaddFlag:
+    """--no-cadd wires through to no_cadd on all three analysis commands."""
+
+    def test_analyze_passes_no_cadd(self, mock_mhg_path, monkeypatch):
+        captured: dict = {}
+
+        def fake_run(**kwargs):
+            captured.update(kwargs)
+
+        monkeypatch.setattr("allelix.cli._run_analysis_command", fake_run)
+        runner = CliRunner()
+        result = runner.invoke(main, ["analyze", str(mock_mhg_path), "--no-cadd"])
+        assert result.exit_code == 0, result.output
+        assert captured["no_cadd"] is True
+
+    def test_analyze_default_no_cadd_false(self, mock_mhg_path, monkeypatch):
+        captured: dict = {}
+
+        def fake_run(**kwargs):
+            captured.update(kwargs)
+
+        monkeypatch.setattr("allelix.cli._run_analysis_command", fake_run)
+        runner = CliRunner()
+        result = runner.invoke(main, ["analyze", str(mock_mhg_path)])
+        assert result.exit_code == 0, result.output
+        assert captured["no_cadd"] is False
+
+    def test_methylation_passes_no_cadd(self, mock_mhg_path, monkeypatch):
+        captured: dict = {}
+
+        def fake_run(**kwargs):
+            captured.update(kwargs)
+
+        monkeypatch.setattr("allelix.cli._run_analysis_command", fake_run)
+        runner = CliRunner()
+        result = runner.invoke(main, ["methylation", str(mock_mhg_path), "--no-cadd"])
+        assert result.exit_code == 0, result.output
+        assert captured["no_cadd"] is True
+
+    def test_pharmacogenomics_passes_no_cadd(self, mock_mhg_path, monkeypatch):
+        captured: dict = {}
+
+        def fake_run(**kwargs):
+            captured.update(kwargs)
+
+        monkeypatch.setattr("allelix.cli._run_analysis_command", fake_run)
+        runner = CliRunner()
+        result = runner.invoke(main, ["pharmacogenomics", str(mock_mhg_path), "--no-cadd"])
+        assert result.exit_code == 0, result.output
+        assert captured["no_cadd"] is True
+
+
 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."""