Metadata-Version: 2.4
Name: pycmplot
Version: 0.4.3
Summary: Multi-track circular and linear Manhattan plot generation for GWAS summary statistics
Author: Kevin Esoh
Author-email: Kevin Esoh <kesohku1@jh.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/esohkevin/pycmplot
Project-URL: Issues, https://github.com/esohkevin/pycmplot/issues
Project-URL: Docs, https://pycmplot.readthedocs.io/en/latest/
Project-URL: Cite, https://doi.org/10.1093/bioadv/vbag281
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Requires-Dist: matplotlib>=3.6
Requires-Dist: pillow>=9.0
Requires-Dist: liftover>=1.4.1
Requires-Dist: natsort>=8.0
Requires-Dist: adjustText>=0.8
Requires-Dist: pyarrow>=23.0.1
Requires-Dist: fastparquet>=2025.12.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: towncrier; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Dynamic: license-file

# pycmplot


<div>
  <h1 align="center">Multi-track circular and linear Manhattan plotting in Python.</h1>
</div>

<p align="center">

  [![Python](https://img.shields.io/badge/python-3.9%20%7C%203.13-blue)](https://www.python.org/)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  [![Status](https://img.shields.io/badge/Status-Latest-orange)](#)
  [![Static Badge](https://img.shields.io/badge/10.1093-bioadv-vbag281?style=flat&logo=doi)](https://doi.org/10.1093/bioadv/vbag281)

</p>

----------------------------------------------

# Install

## From PyPI
```bash
pip install pycmplot
```

## From GitHub
```bash
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

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

pip install --upgrade pip setuptools wheel
pip install pycmplot
```


## Test the installation
```bash
pycmplot -V
```

## Get Help
```
pycmplot -h,--help
```

## Dependencies

| Package | Purpose |
|---------|---------|
| pandas, numpy | Data loading & statistics |
| matplotlib | Plotting backend |
| pycirclize | Circular (Circos-style) tracks |
| natsort | Natural chromosome sorting |
| adjustText | Label collision avoidance |
| liftover | hg18/hg19 to hg38 coordinate conversion |
| Pillow | Image utilities |
| pyarrow, fastparquet | Data load and compression engine |

---


## Command-line usage
### Linear Manhattan (default)
```bash
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
```bash
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
```python
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](https://pycmplot.readthedocs.io/en/latest/) 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
