allelign 0.1.0__tar.gz

allelign-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "claude/**"]
+  pull_request:
+    branches: [main]
+
+env:
+  OPENBLAS_NUM_THREADS: "1"
+  OMP_NUM_THREADS: "1"
+  MKL_NUM_THREADS: "1"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[lint]"
+      - run: ruff check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # The floor ldpred3's own CI tests: py3.9 with numpy 1.20, no Numba.
+          - python-version: "3.9"
+            extras: "test"
+            pins: "numpy==1.20.3"
+          - python-version: "3.12"
+            extras: "test,fast"
+            pins: ""
+    name: py${{ matrix.python-version }} · ${{ matrix.extras }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[${{ matrix.extras }}]" ${{ matrix.pins }}
+      # The parity tests skip themselves without ldpred3, which is private;
+      # they run locally against the sibling checkout.
+      - run: pytest -q

allelign-0.1.0/.github/workflows/pypi.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+# Trusted publishing: create the "allelign" project on PyPI once and register
+# this workflow as a trusted publisher there (repository bvilhjal/allelign,
+# environment "pypi", workflow file .github/workflows/pypi.yml). Until then
+# this workflow only runs when a GitHub release is published.
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

allelign-0.1.0/AGENTS.md

@@ -0,0 +1,11 @@
+# Agent notes
+
+- Environment: editable install in the `ldpred3-accelerate` conda env (`~/anaconda3/envs/ldpred3-accelerate/bin/python`, 3.14), with Numba and SciPy.
+- Run Python with `-P` when the working directory is `REPOS/`. Otherwise the `allelign/` repo directory shadows the installed package as a namespace package, and `import allelign` finds no `__version__`.
+- Tests: `pytest -q`, with `OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 MKL_NUM_THREADS=1` for deterministic numerics. Markers:
+  - `parity`: compares against ldpred3; skipped without it;
+  - `numba`: needs the JIT.
+- `NUMBA_DISABLE_JIT=1 pytest -m "not parity"` checks the pure-Python fallback.
+- The parity tests are the contract for moving ldpred3 and its siblings onto allelign. A change that breaks them needs a deliberate decision, recorded in docs/guide.md section 5.
+- Lint is `ruff check .`, pyflakes rules only. Do not add style rules or reformat long lines.
+- Status codes, warning-marker strings and the AF safety-valve wording are read by other repos (SMARTpred). Change them only together with their consumers.

allelign-0.1.0/CHANGELOG.md

@@ -0,0 +1,183 @@
+# Changelog
+
+All notable changes are recorded here, in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) style.
+
+## [Unreleased]
+
+### Changed
+
+- Package authorship metadata (`pyproject.toml`, `CITATION.cff`) records the
+  bvilhjal account rather than a personal name; the LICENSE keeps the
+  copyright name.
+
+### Added
+
+- `allelign download` (and `parse_ref`, `resolve_ref`, `download_ref`,
+  `read_keep_ids`): resolve and fetch published summary statistics and PGS
+  scores — GWAS Catalog harmonised accessions, PGS Catalog scores
+  (harmonised preferred), FinnGen endpoints, COVID-19 HGI analyses, GBMI
+  ancestry strata and eQTL Catalogue molecular traits (row-filtered at
+  download). Downloads are streamed and atomic with a `<out>.meta.json`
+  provenance sidecar; `--keep-ids` restricts a download to a reference's
+  variants; `--dry-run` prints the resolved plan. `all_meta_af` (GBMI,
+  COVID-HGI) joins the frequency aliases. The suite stays offline through
+  an injectable opener; endpoints were verified against the live services.
+- An AI-assistance disclaimer in the README and the guide: parts of the code
+  and documentation were generated with AI tools and reviewed by the
+  maintainer.
+- A hands-on walkthrough (docs/walkthrough.md: download → inspect → clean →
+  align → scores, with the records each step writes) and the same flow as an
+  executable notebook (docs/walkthrough.ipynb), both linked from the README
+  and shipped in sdists.
+- References: README and docs/guide.md cite the methods implemented — DENTIST
+  (the LD-consistency screen), the SD/AF checks and per-variant N imputation,
+  the PGS Catalog scoring format, the GWAS Catalog `hm_` layout, and the
+  height-GWAS screen example.
+## [0.1.0] - 2026-10-29
+
+### Added
+
+- First public release, consolidating 0.1.0.dev1 through 0.1.0.dev8
+  (recorded below).
+- Public-release packaging: a PyPI publish workflow on GitHub releases
+  (PyPI trusted publishing), README install-from-GitHub instructions and CI
+  badge, trove classifiers and project URLs in `pyproject.toml`, and a
+  `MANIFEST.in` so sdists carry the changelog, citation file and guide.
+
+## [0.1.0.dev8] - 2026-10-28
+
+### Fixed
+
+- Parse only additive `TEST` rows (`ADD`, `ADD-CONDTL`), with matching Python
+  and compiled paths, a warning and parse counts for discarded tests.
+- Keep streamed Catalog alleles, effects and OR/z-score fallbacks in one
+  orientation, including provider overrides; reject incomplete sets.
+- Permit the documented CLI cross-build identifier reanchoring while retaining
+  declared, reference and output builds in its log.
+- Determine PGS coordinate build independently of the rsID column; mixed
+  coordinates and undeclared harmonised builds remain unknown.
+- Give exactly constant fractional dosage columns zero off-diagonal LD,
+  including missing calls, without removing small real variation.
+- `stats_out` on `ld_consistency_screen` records one trait. Several z
+  columns raise and point at `return_stats`, instead of leaving the last
+  column's counts in the caller's dict.
+- `af_concordance_mask` checks `status` even when the safety valve drops
+  nothing.
+- `impute_n_eff` rejects an `anchor_quantile` outside [0, 1] and a
+  non-integer `anchor_bins` with the usual control errors.
+- `read_pvar` builds its column map once per header, not once per data row.
+- An infinite position in an unmatched row is treated as missing by the
+  coverage diagnosis, as the coordinate matcher already does.
+- `read_scoring_file` counts unparsable positions
+  (`n_unparsable_position`). They still become position 0.
+- `write_weights` writes floats with `repr`, so `read_weights` gets the
+  same bits back. Files written at 8 significant digits still parse.
+- `write_pgs_scoring_file` no longer stamps `#variants_genome_wide` equal
+  to the row count. `#variants_number` is that count; the genome-wide
+  field would claim a chromosome subset or a hits list is the full score.
+- `read_sumstats` documents that comma-separated files are not CSV-quoted.
+
+## [0.1.0.dev7] - 2026-10-17
+
+### Fixed
+
+- Header-only inspection reports missing sample size and accepts the reader's
+  scalar N and case/control arguments, including validation and precedence.
+  `allelign inspect` accepts `--n-eff`, `--n-cases` and `--n-controls`.
+- The header and reference row parser strip CRLF line endings when called
+  directly, matching the normalised line endings of file reads.
+- BED size errors report the full `.fam` sample count, even with a selection.
+- CLI JSON logs are published atomically; failed writes preserve existing logs.
+- The citation version matches the package version.
+
+## [0.1.0.dev6] - 2026-10-16
+
+### Added
+
+- Header-only `resolve_gwas_catalog_columns` for streamed Catalog normalisers,
+  including provider overrides, OR/z-score fallback columns and the rule
+  against pairing submitted frequencies with harmonised alleles.
+- Public `SCORING_COLUMNS` for PGS download validators. The old private name
+  remains an alias for early consumers.
+- Per-variant `reported_n` and an explicit `strict=True` policy in
+  `implied_sample_size`, preserving bipred's input checks, arithmetic and
+  median over all implied estimates. The default still uses positive finite
+  estimates; both compare against the median reported N.
+- Legacy benchmark aliases (`SNPname`, `logOR`, `hm_standard_error`,
+  `samplesize`, `n_sample`, `total_sample_size`) in the shared GWAS vocabulary.
+
+### Fixed
+
+- Long-range LD masks preserve scalar and multidimensional input shapes while
+  normalising chromosome labels. Region endpoints remain inclusive.
+- `implied_sample_size` rejects nonboolean `binary` controls and mismatched
+  `reported_n` vectors instead of relying on array truth values.
+
+## [0.1.0.dev5] - 2026-10-13
+
+### Fixed
+
+- Explicit case/control column mappings take precedence over auto-detected N,
+  including effective-N columns. Both counts must resolve; a scalar N or an
+  explicit `n_eff` mapping still wins. Reading and header-only inspection agree.
+
+## [0.1.0.dev4] - 2026-10-12
+
+### Fixed
+
+- `read_sumstats`, `detect_columns` and `inspect_columns` take N from an effective-N
+  column (`Effective_N`, `N_effective`, `all_inv_var_meta_effective`) beside a total-N
+  column such as `N`, as documented. They used to read the total, ~2.8x too high at 10% cases.
+
+## [0.1.0.dev3] - 2026-10-12
+
+### Changed
+
+- Gzip weight and status tables use compression level 1 to reduce writing
+  time. Decompressed text and atomic publication remain unchanged.
+
+## [0.1.0.dev2] - 2026-10-10
+
+### Added (0.1.0.dev2)
+
+- `read_scoring_file(keep=...)` prefilters rows a reference cannot match, as multipgs's private `_reference_filter` did. `harmonize_weights` takes the weight mass over the whole file and counts the skipped rows as unmatched. `ScoringFile` gains `trait` and `__str__`, and `scoring_file_id` is public: multipgs now reads PGS Catalog files through allelign.
+- Public `variant_indices`, the identifier index `harmonize` caches per table, for callers that look up identifiers against a reference.
+
+### Fixed (0.1.0.dev2)
+
+- A GWAS Catalog file read through its `hm_` columns without `hm_effect_allele_frequency` no longer pairs the submitted frequency with the harmonised alleles. The frequency is dropped and `parse_log["layout"]["eaf_dropped"]` says why.
+
+### Added (0.1.0.dev1)
+
+- First version, extracted from ldpred3 0.9.x with pieces of multipgs and bipred:
+  - summary-statistics reader with the alias table, OR-to-beta, SE from p, and the optional Numba block parser;
+  - harmoniser with both the vectorised join and the row loop, coverage and match diagnostics, and identifier re-anchoring;
+  - file-level and reference QC (SD consistency, allele-frequency concordance with its safety valve, imputed N, genomic-control undo, implied N);
+  - the split-half LD-consistency screen with full-window confirmation;
+  - ldpred3 weight tables, PGS Catalog reading (from multipgs) and writing;
+  - the per-variant status vocabulary;
+  - the GRCh37 long-range LD regions (from bipred).
+- Beyond ldpred3:
+  - effective N from per-variant case and control counts;
+  - PLINK2 `A1` resolved against `REF`/`ALT` (or `OMITTED`) row by row;
+  - REGENIE `GENPOS` as position;
+  - SE from `-log10 p` (`LOG10P`, `mlogp`);
+  - GWAS Catalog `hm_` columns used as one consistent set;
+  - PGC `FRQ_U_*` as the effect-allele frequency;
+  - Neale `chr:pos:ref:alt` variant strings.
+- `.bim`/`.pvar` readers, `harmonize_weights` (aligns frequencies and reports matched weight mass), `genomic_inflation`, LD blocks from reference genotypes, and a CLI (`inspect`, `clean`, `align`, `pgs-export`).
+- `Bed`, a NumPy-only PLINK 1 `.bed` reader. It reads selected variants with coalesced seeks and can restrict to some samples (IIDs, indices or a mask).
+- `ld_consistency_screen_genotypes` screens with LD formed block by block from a `.bed`, so a genome-wide reference never holds more than one block of LD. It is also available as `allelign align --ld-screen [--ld-keep FILE]`.
+- Hooks ldpred3 uses to consume the screen: `ld_consistency_screen_selected` (screen a sparse selection without materialising it), `ncores` block pooling, `stats_out`, and a private eigensolver hook.
+- CI (lint; py3.9 with numpy 1.20 and no Numba; py3.12 with Numba).
+
+### Consumers
+
+- ldpred3 0.9.9 imports allelign for reading, harmonisation, QC, weights and the split-half screen.
+- ppb 0.0.1.dev10 takes its chromosome, reverse-complement and strand-ambiguity rules from `allelign.alleles`.
+- bipred, gwfm, multipgs and SMARTpred (from 0.1.0.dev2) import reading, alignment, QC and weight-file I/O directly; multipgs's PGS Catalog reader is allelign's.
+
+### Fixed (relative to the ldpred3 originals)
+
+- The PGS Catalog export no longer claims `#sd_source=empirical` for a weights table that records no SD source; it writes `unspecified` and warns.
+- The long-range LD mask normalises chromosome labels, so `chr6` matches.

allelign-0.1.0/CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+message: "If you use allelign, please cite this software."
+type: software
+title: allelign
+authors:
+  - name: bvilhjal
+version: "0.1.0"
+repository-code: "https://github.com/bvilhjal/allelign"
+license: MIT

allelign-0.1.0/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/MANIFEST.in

@@ -0,0 +1,10 @@
+include CHANGELOG.md
+include CITATION.cff
+include LICENSE
+include README.md
+include AGENTS.md
+include .github/workflows/ci.yml
+include .github/workflows/pypi.yml
+recursive-include docs *.md *.ipynb
+recursive-include tests *.py
+global-exclude *.py[cod]

allelign-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,142 @@
+# 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).