GWASLab

badge badge_pip badge_commit_m

A handy Python-based toolkit for handling GWAS summary statistics (sumstats).
Each process is modularized and can be customized to your needs.
Sumstats-specific manipulations are designed as methods of a Python object, gwaslab.Sumstats.

Installation

install via pip

The latest version of GWASLab now supports Python 3.9, 3.10, 3.11, and 3.12.

pip install gwaslab

install in conda environment

Create a Python 3.9, 3.10, 3.11 or 3.12 environment and install gwaslab using pip:

conda env create -n gwaslab -c conda-forge python=3.12

conda activate gwaslab

pip install gwaslab

or create a new environment using yml file environment.yml

conda env create -n gwaslab -f environment.yml

install using docker (deprecated)

A docker file is available here for building local images.

Quick start

import gwaslab as gl

# load plink2 output
mysumstats = gl.Sumstats("sumstats.txt.gz", fmt="plink2")

# or load sumstats with auto mode (auto-detecting commonly used headers) 
# assuming ALT/A1 is EA, and frq is EAF
mysumstats = gl.Sumstats("sumstats.txt.gz", fmt="auto")

# or you can specify the columns:
mysumstats = gl.Sumstats("sumstats.txt.gz",
             snpid="SNP",
             chrom="CHR",
             pos="POS",
             ea="ALT",
             nea="REF",
             eaf="Frq",
             beta="BETA",
             se="SE",
             p="P",
             direction="Dir",
             n="N",
             build="19")

# manhattan and qq plot
mysumstats.plot_mqq()
...

Documentation and tutorials

Documentation and tutorials for GWASLab are avaiable at here.

Functions

Loading and Formatting

Loading sumstats by simply specifying the software name or format name, or specifying each column name.
Converting GWAS sumstats to specific formats:
- LDSC / MAGMA / METAL / PLINK / SAIGE / REGENIE / MR-MEGA / GWAS-SSF / FUMA / GWAS-VCF / BED...
- check available formats
Optional filtering of variants in commonly used genomic regions: Hapmap3 SNPs / High-LD regions / MHC region

Standardization & Normalization

Variant ID standardization
CHR and POS notation standardization
Variant POS and allele normalization
Genome build : Inference and Liftover

Quality control, Value conversion & Filtering

Statistics sanity check
Extreme value removal
Equivalent statistics conversion
- BETA/SE , OR/OR_95L/OR_95U
- P, Z, CHISQ, MLOG10P
Customizable value filtering

Harmonization

rsID assignment based on CHR, POS, and REF/ALT
CHR POS assignment based on rsID using a reference text file
Palindromic SNPs and indels strand inference using a reference VCF
Check allele frequency discrepancy using a reference VCF
Reference allele alignment using a reference genome sequence FASTA file

Visualization

Mqq plot: Manhattan plot, QQ plot or MQQ plot (with a bunch of customizable features including auto-annotate nearest gene names)
Miami plot: mirrored Manhattan plot
Brisbane plot: GWAS hits density plot
Regional plot: GWAS regional plot
Genetic correlation heatmap: ldsc-rg genetic correlation matrix
Scatter plot: variant effect size comparison
Scatter plot: allele frequency comparison
Scatter plot: trumpet plot (plot of MAF and effect size with power lines)

Visualization Examples

Other Utilities

Read ldsc h2 or rg outputs directly as DataFrames (auto-parsing).
Extract lead variants given a sliding window size.
Extract novel loci given a list of known lead variants / or known loci obtained from GWAS Catalog.
Logging: keep a complete record of manipulations applied to the sumstats.
Sumstats summary: give you a quick overview of the sumstats.
...

Issues

GWASLab is currently under active development, with frequent updates.
Note: Known issues are documented at https://cloufield.github.io/gwaslab/KnownIssues/.

How to cite

GWASLab preprint: He, Y., Koido, M., Shimmori, Y., Kamatani, Y. (2023). GWASLab: a Python package for processing and visualizing GWAS summary statistics. Preprint at Jxiv, 2023-5. https://doi.org/10.51094/jxiv.370

Sample data used for tutorial

Sample GWAS data used in GWASLab is obtained from: http://jenger.riken.jp/ (Suzuki, Ken, et al. "Identification of 28 new susceptibility loci for type 2 diabetes in the Japanese population." Nature genetics 51.3 (2019): 379-386.).

Acknowledgement

Thanks to @sup3rgiu, @soumickmj and @gmauro for their contributions to the source codes.

Contacts

Github: https://github.com/Cloufield/gwaslab
Blog (in Chinese): https://gwaslab.com/
Email: gwaslab@gmail.com
Stats: https://pypistats.org/packages/gwaslab

Release files for gwaslab 4.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gwaslab 4.2.3
File	Size	Uploaded
gwaslab-4.2.3.tar.gz	27.1 MB	Sep 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for gwaslab 4.2.3
File	Interpreter	ABI	Platform	Reset
gwaslab-4.2.3-py3-none-any.whl 26.9 MB Sep 25, 2026	Python 3	none	any	Details

Total release size: 54.0 MB

Release files / gwaslab-4.2.3.tar.gz

Download URL	gwaslab-4.2.3.tar.gz
Size	27.1 MB
Tags	Source
SHA-256 checksum How to use checksums	`2c3be32ed4c0dcc45519df2af202bbabfeecd0eea323370bb593a543dd9c4691`
BLAKE2b-256 checksum How to use checksums	`c5c20172c52a87faf0eface3fd6f0a12034477f1e4874cb0d500cfe9c16d5538`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.0`

Release files / gwaslab-4.2.3-py3-none-any.whl

Download URL	gwaslab-4.2.3-py3-none-any.whl
Size	26.9 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`f21e5e06c0464f3a29eed602958a4ebe192c62f9eba41c508ebfad683b00eebb`
BLAKE2b-256 checksum How to use checksums	`639b628ecedd9c313ba8bad95ac4a9abb7aab772cc15f7197252b9cd12e2906c`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.0`