GWAS SumStats Tools
A toolkit for processing, validating, and formatting GWAS (Genome-Wide Association Studies) summary statistics files for submission to the GWAS Catalog.
It ships as:
gwas-ssfCLI — full-featured command-line tool (Python package on PyPI)- SSF-morph — browser-based UI for formatting and validating single files (no install required)
Repository Layout
gwas-sumstats-tools/
├── src/
│ └── gwas_sumstats_tools/ # Python package (the core library and CLI)
├── apps/
│ └── ssf-morph/ # Browser web app (Pyodide-based)
├── docs/
│ ├── gwas-sumstats-tools-doc/ # Docsify documentation site
│ └── decisions/ # Architecture decision records
├── tests/ # Pytest test suite
├── deployment/ # Static site build script
├── dist/ # Built Python wheel and sdist archives
├── Dockerfile # Docker image for the CLI
├── .gitlab-ci.yml # Tests, CLI images and GitLab Pages publishing
├── DEPLOYMENT.md # End-to-end deployment guide
├── pyproject.toml # uv/PEP 621 project configuration
└── .github/ # CI/CD pipelines
Folder Descriptions
src/gwas_sumstats_tools/
The installable Python package. Exposes a gwas-ssf CLI entry-point and a public Python API.
| File / Folder | Purpose |
|---|---|
cli.py |
Typer-based CLI — read, format, validate, gen-meta commands |
read.py |
Preview a summary statistics file, extract headers or metadata |
format.py |
Convert tabular files to gwas-ssf standard format |
validate.py |
Validate a file against the gwas-ssf schema |
gen_meta.py |
Auto-generate metadata from a submission form or the GWAS Catalog API |
config.py |
Load and parse the JSON configuration file used by format |
constants.py |
Shared constants (field names, defaults) |
utils.py |
Internal helper functions |
interfaces/ |
Data-layer abstractions: data_table.py (tabular data), metadata.py (YAML metadata) |
schema/ |
Pydantic/Pandera schemas for data validation and config structure |
apps/ssf-morph/
A browser-only web app that runs the same Python formatting and validation logic in-browser via Pyodide (Python compiled to WebAssembly). No server or installation needed.
| File / Folder | Purpose |
|---|---|
index.html |
Main UI — two-mode wizard (Format / Validate) |
consumer.js |
Event handlers, config form builders, async orchestration |
py-worker.js |
Async wrapper that forwards tasks to the Web Worker |
webworker.js |
Web Worker: initialises Pyodide, mounts the local filesystem, runs Python scripts |
python_bin/ |
Python scripts executed inside the browser (read, format, validate) |
wheels/ |
Pre-built Python wheels loaded at startup by Pyodide |
Icons/ |
UI icon assets |
Requires a Chromium-based browser (Chrome, Edge). Single file, max 2 GB.
docs/gwas-sumstats-tools-doc/
A Docsify documentation site — plain Markdown files rendered client-side. Covers installation, CLI usage, the web UI guide, a tutorial, and the configuration format.
| File / Folder | Purpose |
|---|---|
index.html |
Docsify entry point |
README.md |
Homepage / overview |
install.md |
Installation instructions |
tutorial.md |
Step-by-step tutorial |
CLI_read.md |
CLI: read command reference |
CLI_format.md |
CLI: format command reference |
CLI_validate.md |
CLI: validate command reference |
CLI_gen_meta.md |
CLI: gen-meta command reference |
UI_format.md |
SSF-morph web UI guide |
edit_config.md |
How to write/edit the format config file |
img/ |
Images and GIFs used in the docs |
test_data/ |
Example input files referenced in the tutorial |
tests/
Pytest test suite covering CLI, formatting, reading, validation, and utilities.
| File | Purpose |
|---|---|
test_cli.py |
End-to-end CLI command tests |
test_format.py |
Unit tests for the format module |
test_read.py |
Unit tests for the read module |
test_validate.py |
Unit tests for the validate module |
test_utils.py |
Unit tests for helper utilities |
prep_tests.py |
Test fixtures and shared setup |
interfaces/ |
Tests for the data-layer interfaces |
deployment/
Static site packaging for GitLab Pages.
| File | Purpose |
|---|---|
build_pages.sh |
Build and check the browser app, versioned Python wheel and documentation in public/ |
docs/decisions/
Architecture Decision Records (ADRs) — lightweight design documents explaining why key technical choices were made.
| File | Purpose |
|---|---|
0001-validator.md |
Decision record for the validation approach |
0002-deployment.md |
Decision record for the deployment architecture |
0003-uv-package-manager.md |
Migration from Poetry to uv; Python 3.13 and dependency upgrades |
dist/
Pre-built Python distribution archives (wheels and source tarballs) produced by uv build. The latest wheel is also copied into apps/ssf-morph/wheels/ for use by the browser app.
Quick Start
CLI (pip)
pip install gwas-sumstats-tools # requires Python 3.13+
gwas-ssf --help
Web UI
Open SSF-morph in Chrome or Edge — no installation required.
Local development
# Install dependencies
uv sync
# Run tests
uv run pytest
# Preview the docs locally
cd docs/gwas-sumstats-tools-doc
python3 -m http.server 3000
# then open http://localhost:3000
Deployment
Two independent release flows:
| Flow | Trigger | Produces |
|---|---|---|
| PyPI | GitHub Release | Python package on PyPI |
| Docs/App | Manual GitLab CI job from the default branch (main) or a release tag; automatic publication from protected dev |
Production GitLab Pages site and separate /dev/ version |
See DEPLOYMENT.md for full details.
Citation:
If you use the NHGRI-EBI GWAS Catalog tool in your research, please refer to the "How to Cite the NHGRI-EBI GWAS Catalog, Data, or Diagrams" section on our website for proper citation guidelines.
License
Copyright © EMBL-EBI 2024. See LICENSE for details.
Metadata
Release files for gwas-sumstats-tools 2.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| gwas_sumstats_tools-2.0.2.tar.gz | 10.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| gwas_sumstats_tools-2.0.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 10.1 MB
Release files / gwas_sumstats_tools-2.0.2.tar.gz
| Download URL | gwas_sumstats_tools-2.0.2.tar.gz |
|---|---|
| Size | 10.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4151c5609c0037534419aac5d8735f723d89a810a10968b5789c46b8f67836f2
|
|
BLAKE2b-256 checksum How to use checksums |
42189573e9e745020e6a83e7e4b0caf93444815ca644b8c1aaf0efecc4bc5ed7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / gwas_sumstats_tools-2.0.2-py3-none-any.whl
| Download URL | gwas_sumstats_tools-2.0.2-py3-none-any.whl |
|---|---|
| Size | 46.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
31249b31590e6b71b19aabd5b1de279236407486ebb45bfa1ceaf8f2fd392428
|
|
BLAKE2b-256 checksum How to use checksums |
5c236bb3915a5cf8418d8afd0d46b26e625d58fbaf2eeeebbf492a194f5d8e57
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency log
