allelign 0.1.0__py3-none-any.whl

allelign-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: allelign
+Version: 0.1.0
+Summary: Read, align and quality-control GWAS summary statistics and PGS weights
+Author: bvilhjal
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bvilhjal/allelign
+Project-URL: Repository, https://github.com/bvilhjal/allelign
+Project-URL: Issues, https://github.com/bvilhjal/allelign/issues
+Project-URL: Documentation, https://github.com/bvilhjal/allelign/blob/main/docs/guide.md
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Provides-Extra: fast
+Requires-Dist: numba>=0.59; extra == "fast"
+Requires-Dist: scipy>=1.7; extra == "fast"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: scipy>=1.7; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff>=0.5; extra == "lint"
+Dynamic: license-file
+
+# allelign
+
+[![CI](https://github.com/bvilhjal/allelign/actions/workflows/ci.yml/badge.svg)](https://github.com/bvilhjal/allelign/actions/workflows/ci.yml)
+
+Read, align and quality-control GWAS summary statistics and PGS effect sizes.
+
+Every method in this family starts the same way: parse a summary-statistics file in one of many dialects, get the effect alleles right against a reference, and catch bad input before it turns into a confident wrong number. allelign does those steps once, for all of them. It is extracted from ldpred3, plus the PGS Catalog reader from multipgs and the long-range LD table from bipred. On the inputs ldpred3 already handles it reproduces ldpred3 bit for bit; `tests/test_parity_ldpred3.py` checks that.
+
+NumPy is the only dependency. Numba speeds up the parser about threefold, and SciPy provides float32 eigensolves for the LD screen; both are optional (`[fast]`).
+
+## Install
+
+From GitHub:
+
+```bash
+pip install "allelign[fast] @ git+https://github.com/bvilhjal/allelign.git"
+```
+
+From a sibling checkout, as with the rest of the family:
+
+```bash
+pip install -e "../allelign[fast]"
+```
+
+## Quick start
+
+```python
+import allelign as al
+
+ss = al.read_sumstats("gwas.tsv.gz")                  # any common dialect
+keep, qc_log = al.qc_sumstats(ss)                     # validity, duplicates, N, MAF, INFO
+ref = al.read_bim("reference.bim").freeze()           # or read_pvar, or al.Variants(...)
+h = al.harmonize(ss.subset(keep), ref)                # beta now counts ref.a1
+print(al.coverage_message(al.reference_coverage(ss.subset(keep), ref, h)) or "coverage ok")
+
+# Checks against the reference panel (af_ref: frequency of ref.a1).
+sd_keep, sd_log, _ = al.sd_consistency_mask(h.beta, h.se, h.n_eff, af_ref[h.var_index])
+
+# LD consistency: z-scores their LD neighbours contradict. LD comes from the
+# reference's genotypes, one block at a time; or pass your own [(R, idx), ...]
+# blocks to al.ld_consistency_screen.
+bed = al.Bed("reference.bed", variants=ref, samples=eur_iids)
+ld_keep = al.ld_consistency_screen_genotypes(bed, h.var_index, h.beta / h.se)
+
+# PGS effect sizes
+score = al.read_scoring_file("PGS000001_hmPOS_GRCh37.txt.gz")
+w = al.harmonize_weights(score, ref)                  # also aligns AF, reports matched weight mass
+```
+
+Every filter can stamp a per-row status array (`al.new_status(len(ss))`, passed as `status=`), so you can see which stage dropped each variant and write the table with `al.write_status_table`.
+
+## Command line
+
+```bash
+allelign inspect gwas.tsv.gz
+allelign clean gwas.tsv.gz -o clean.tsv.gz --status-out status.tsv
+allelign align gwas.tsv.gz --reference ref.bim -o aligned.tsv.gz --sumstats-build GRCh38 --reference-build GRCh37 --reanchor-on-identifier
+allelign align gwas.tsv.gz --reference ref.bim -o aligned.tsv.gz --ld-screen --ld-keep eur_samples.txt --status-out status.tsv
+allelign pgs-export prs.weights.tsv -o PGS_my.txt --genome-build GRCh37
+allelign download GCST91000728 -o gwas.h.tsv.gz                # GWAS Catalog
+allelign download FINNGEN:R11:I9_AF -o finngen.tsv.gz          # FinnGen, and the providers below
+allelign download EQTL:QTS000001:QTD000001:ENSG00000008128 -o eqtl.tsv.gz
+allelign download GCST91000728 -o gwas.h.tsv.gz --keep-ids ref.bim
+allelign download PGS000337 -o score.txt.gz --build GRCh38 --dry-run
+```
+
+Each command writes `<out>.log.json` with the parse, QC, harmonisation and coverage records; `download` writes a `<out>.meta.json` provenance sidecar (URL, provider, trait, SHA-256, filter counts) instead.
+
+## What it covers
+
+- **Reading.** ldpred3's alias table and dialect rules (SAIGE, BOLT, METAL, GWAS-SSF, PGC), OR to log-OR, SE recovered from p without underflow. allelign adds:
+  - PLINK2 `A1` against `REF`/`ALT` or `OMITTED`;
+  - REGENIE `GENPOS` and `LOG10P`;
+  - GWAS Catalog `hm_` columns as one consistent set;
+  - PGC `FRQ_U_*`;
+  - Neale `chr:pos:ref:alt`;
+  - FinnGen;
+  - effective N from case and control counts.
+- **Downloading.** `allelign download` resolves a published study by reference — GWAS Catalog (`GCST…`), PGS Catalog (`PGS…`), FinnGen, COVID-HGI, GBMI, eQTL Catalogue — checks the URL, streams it locally with a provenance sidecar, and can keep only the rows a reference can match.
+- **Alignment.** ldpred3's harmoniser:
+  - identifier matching with coordinate checks, so a build mix-up is unmatched rather than silently accepted;
+  - strand flips;
+  - ambiguous pairs dropped;
+  - multi-allelic sites;
+  - coverage diagnosis that names a build mismatch;
+  - identifier re-anchoring;
+  - a declared-build check.
+- **QC.**
+  - File-level filters.
+  - SD consistency against reference frequencies.
+  - Allele-frequency concordance, with a safety valve for ancestry mismatch.
+  - Imputed per-variant N, the genomic-control undo, implied N, λGC and long-range LD regions.
+  - The split-half LD-consistency screen (DENTIST-style) with full-window confirmation, on dense, int8, low-rank or lazily provided LD, or on LD formed block by block from a PLINK `.bed` reference.
+- **Effect sizes.** ldpred3 weight tables, PGS Catalog reading and writing, and alignment of either to a reference.
+
+[docs/guide.md](docs/guide.md) has the rules, defaults and the deliberate differences from ldpred3. A hands-on pass over download → inspect → clean → align is [docs/walkthrough.md](docs/walkthrough.md), with the same flow as a notebook in [docs/walkthrough.ipynb](docs/walkthrough.ipynb).
+
+## Consumers
+
+- **ldpred3** reads, aligns, QCs and writes weights through allelign. Its modules re-export allelign under their old names, so sibling imports keep working. It keeps the pipeline-specific parts: whole-block DENTIST with low-rank Woodbury updates, the BLAS gate for a pooled screen, its float32 eigensolver (passed to the screen), and the qc_log report blocks. allelign's parity tests are the contract.
+- **ppb** takes chromosome labels, reverse complements and strand ambiguity from `allelign.alleles` and keeps its own position-only join.
+- **bipred** takes the region table, long-range mask, strict implied-N diagnostic and weight-file I/O from allelign. Its wrapper includes APOE by default; its LDpred2-style SD diagnostic stays in bipred. Trait preparation still goes through ldpred3.
+- **gwfm, multipgs and SMARTpred** use allelign for reading, alignment, QC and weight-file I/O. multipgs aligns both scoring files and fitted weights with `harmonize_weights`. SMARTpred and the LDpred3 harvester share the header-only `resolve_gwas_catalog_columns` rules while retaining streamed filtering. LD caches, prepared traits, the fit and pipeline reports stay in ldpred3.
+
+## References
+
+The methods allelign implements:
+
+- Chen W, Wu Y, Zheng Z, et al. [Improved analyses of GWAS summary
+  statistics by reducing data heterogeneity and
+  errors](https://doi.org/10.1038/s41467-021-27438-7). *Nature
+  Communications* (2021). The DENTIST statistic behind the LD-consistency
+  screen.
+- Privé F, Arbel J, Aschard H, et al. [Identifying and correcting for
+  misspecifications in GWAS summary statistics and polygenic
+  scores](https://doi.org/10.1016/j.xhgg.2022.100136). *HGG Advances*
+  (2022). The SD-consistency and frequency checks, and the per-variant N
+  imputation.
+- Lambert SA, Gil L, Jupp S, et al. [The Polygenic Score Catalog as an open
+  database for reproducibility and systematic
+  evaluation](https://doi.org/10.1038/s41588-021-00783-5). *Nature
+  Genetics* (2021). The scoring-file format `read_scoring_file` parses.
+- Sollis E, Mosaku A, Abid A, et al. [The NHGRI-EBI GWAS Catalog:
+  knowledgebase and deposition
+  resource](https://doi.org/10.1093/nar/gkac1010). *Nucleic Acids Research*
+  (2023). The harmonised `hm_` deposit layout.
+- Yengo L, Vedantam S, Marouli E, et al. [A saturated map of common genetic
+  variants associated with human
+  height](https://doi.org/10.1038/s41586-022-05275-y). *Nature* (2022).
+  The LD-screen example in the guide.
+
+## AI assistance
+
+Parts of allelign's code and documentation were generated with the assistance
+of AI tools and reviewed by the maintainer. As with any analysis software,
+validate its behaviour on inputs you understand before relying on it; see the
+[LICENSE](LICENSE) for the warranty terms.
+
+## Status
+
+Version 0.1.0. MIT licence. If you use allelign, please cite it — see
+[CITATION.cff](CITATION.cff).

allelign-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+allelign/__init__.py,sha256=K02oT4iSnGfBDI_TeRyOral4hzZIlMnZPkSgueapY8c,3684
+allelign/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+allelign/_common.py,sha256=qCRGxMyyFHc4QzlznHdhGWadqTLjto3CEHagZFQ7MHg,3398
+allelign/_numba.py,sha256=QogvpGChjwTxTo1C_ehGBKDDR90S6rIm5ulS1ICwhWc,722
+allelign/align.py,sha256=VzVq3TLLKEKHW4sxLD6IwYPY4zsZLgNPGsjjnM_9Rzs,49930
+allelign/alleles.py,sha256=VMY0VhoWxH-5KXrsLmjAey-OKmxs4lucgW2imbiI3XY,3470
+allelign/build.py,sha256=DuuN2DG90HUQr-UWKAh5uRR_2qObRK65ZpF7R72O-dA,2293
+allelign/catalog.py,sha256=_a5v16oEjSEm8rRa-gGHTHjxfGV90T3mX8PNZk-Lka8,4229
+allelign/cli.py,sha256=OmQSwZVYnjp_yoXoXyUDYuJUdZ6no69606_-rpBGC8w,13705
+allelign/download.py,sha256=_7f7ahwuh2Vhh_fZffYf7VW8sst7qOxTYi_4EFwz51I,21849
+allelign/genotypes.py,sha256=0WlEzZ6wgB2eEHz5efRmL-_rvcSvnY0iaRLzgacjWIQ,10999
+allelign/ldcheck.py,sha256=5L6v13--WZ3lQFKJMXL2n_xHHassUSY3icQIQdLdB94,34418
+allelign/qc.py,sha256=G5FJy5a4HaqyrX19_gZJX_GJbBcEDAHxVZ57GMCFrvY,27721
+allelign/status.py,sha256=cripSLjAnfgN7nasNIMZ_WZFZVXsQzTBQtvZByIHE90,5397
+allelign/sumstats.py,sha256=aa_AFqOlLnqRRfktqCUpD4Xm7kVTXKJrbiGX4DXNfaU,49906
+allelign/variants.py,sha256=eeHEt2lI0oEeiiSLGfCGZyEWk9t2oniCwUfwB-wFryw,5796
+allelign/warning_markers.py,sha256=cZaAOHPUFxempsIWLk7waKhCG5khF9e77fbaY1pWRHY,663
+allelign/weights.py,sha256=aNq4GgxricsAelxpCsMhhyG2FxkXc4qrOJ0j3BSmY5w,26839
+allelign-0.1.0.dist-info/licenses/LICENSE,sha256=9a8DTdnidoIJuGl05RzKVKee7y99of1ZgEa8wt1ylC8,1077
+allelign-0.1.0.dist-info/METADATA,sha256=4tIlJNjoTIFtmwkENNzzvWLjtGTGDqsSuOcq2a18Xc0,9663
+allelign-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+allelign-0.1.0.dist-info/entry_points.txt,sha256=xOp0unYr6_8QtArk_611NGH6MrxTGc61HZku1U5dl_4,47
+allelign-0.1.0.dist-info/top_level.txt,sha256=CyHIWG7HWTXhlH7a-ENkJS66D0y3K0FfeC7L-2E8kAU,9
+allelign-0.1.0.dist-info/RECORD,,

allelign-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

allelign-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+allelign = allelign.cli:main

allelign-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bjarni Vilhjálmsson
+
+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.

allelign-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+allelign