pycmplot

Install

From PyPI

pip install pycmplot

From GitHub

git clone https://github.com/esohkevin/pycmplot.git

# or with most recent updates from development branch
# git clone -b dev https://github.com/esohkevin/pycmplot.git

cd pycmplot

pip install -e .

# or

wget https://github.com/esohkevin/pycmplot/archive/refs/tags/v0.4.2.tar.gz
tar zxvf v0.4.2.tar.gz
cd pycmplot-v0.4.2
pip install -e . 

# if you get package dependency error, use
pip install -e . --break-system-packages

Python virtual environment

Use python virtual environment if local installation is not possible

python -m venv ~/envs/pycmplot
source ~/envs/pycmplot/bin/activate

pip install --upgrade pip setuptools wheel
pip install pycmplot

Test the installation

pycmplot -V

Get Help

pycmplot -h,--help

Dependencies

Command-line usage

Linear Manhattan (default)

pycmplot \
  --mode lm \
  --sum_stats HbF.tsv.gz,MCV.txt.gz,MCH.tsv.gz \
  --labels HbF,MCV,MCH \
  --logp \
  --signif_line \
  --highlight \
  --annotate GENE \
  --output_dir ./results \
  --output_format png \
  --dpi 300

Circular Manhattan

pycmplot \
  --sum_stats HbF.tsv.gz,MCV.tsv.gz \
  --labels HbF,MCV \
  --mode cm \
  --trim_pval 0.01 \
  --logp \
  --signif_threshold \
  --plot_title "RBC Traits" \
  --output_dir ./results

Mixed genome builds

pycmplot \
  --sum_stats study_hg18.tsv.gz,study_hg19.tsv.gz,study_hg38.tsv.gz \
  --labels Study_A,Study_B,Study_C \
  --build hg18,hg19,hg38 \
  --logp \
  --annotate GENE \
  --output_dir ./results

Python API

from pycmplot import prep, load, linear, circular, qq_combined, qq_overlay, qq_separate

files  = ["HbF.tsv.gz"]
labels = ["HbF"]

# 1. Resolve per-file column names and delimiters
file_info = prep(
    sum_stats=files,
    labels=labels,
)

# 2. Load data, run liftover (if needed), extract lead SNPs,
#    build the hits table, and compute merged sector sizes
result = load(
    sum_stats=files,
    labels=labels,
    logp=True,
    trim_pval=0.01,
    file_info=file_info,
    signif_threshold=5e-8,
)

# 3. Plot curcular
circular(
    sumstats_loaded=result["dfs"],
    sector_sizes=result["sectors"],
    logp=True,
    signif_lines=result["lines"],
    hits_table=result["annot"],
    annotate="GENE",
    label_col="top_gene",
    colors=["steelblue", "silver"],
    plot_title="RBC Traits",
    output_dir="./results",
)

# 4. Plot linear
linear(
    sumstats_loaded=result["dfs"],
    logp=True,
    signif_lines=result["lines"],
    hits_table=result["annot"],
    annotate="GENE",
    label_col="top_gene",
    colors=["steelblue", "silver"],
    output_dir="./results",
)

# 5. Plot QQ

# Grid of per-track QQ panels
qq_combined(
    pval_dict=result["pvals"],
    thin=True,
    max_points=50_000,
    ncols=3,
    title="RBC Traits",
    output_path="./results/rbc_qq",
    fig_format="png",
)

# All traits overlaid on one axes, with lambda in the legend
qq_overlay(
    pval_dict=result["pvals"],
    thin=True,
    max_points=50_000,
    title="RBC Traits",
    output_path="./results/rbc_qq_overlay",
    fig_format="png",
)

# One file per trait
qq_separate(
    pval_dict=result["pvals"],
    base_name="RBC",
    thin=True,
    max_points=50_000,
    output_path="./results/rbc_qq",
    fig_format="png",
)

See docs for more.

Citation

Kevin Esoh, Fujr Osman, Cesar Fortes-Lima, Gordon A Awandare, Ambroise Wonkam, pycmplot: fast, low-memory multi-track circular and linear Manhattan plotting in Python, Bioinformatics Advances, 2026;, vbag281, https://doi.org/10.1093/bioadv/vbag281

Contributing

See how to contribute here https://github.com/esohkevin/pycmplot?tab=contributing-ov-file