Metadata-Version: 2.4
Name: sunmao
Version: 0.6.0
Summary: A flexible subplot layout library for matplotlib with support for adding panels in all directions
License: MIT
License-File: LICENSE
Keywords: matplotlib,visualization,subplot,layout,plotting
Author: seqyuan
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: matplotlib (>=3.5.0,<4.0.0)
Requires-Dist: numpy (>=1.21.0,<2.0.0)
Project-URL: Documentation, https://sunmao.readthedocs.io
Project-URL: Homepage, https://github.com/seqyuan/sunmao
Project-URL: Repository, https://github.com/seqyuan/sunmao
Description-Content-Type: text/markdown

# Sunmao

[![PyPI version](https://badge.fury.io/py/sunmao.svg)](https://badge.fury.io/py/sunmao)
[![Documentation Status](https://readthedocs.org/projects/sunmao/badge/?version=latest)](https://sunmao.readthedocs.io/en/latest/?badge=latest)
[![Python Support](https://img.shields.io/pypi/pyversions/sunmao.svg)](https://pypi.org/project/sunmao/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A matplotlib layout library inspired by traditional Chinese mortise-tenon (榫卯) joinery.
Attach panels in any direction, get a standard `ax`, use any plotting library.

---

## Install

```bash
pip install sunmao
```

---

## Quick Start

```python
from sunmao import create
import numpy as np

fig, root = create(figsize=(10, 8))

top   = root.tenon('top',   size=2)    # 2-inch tall panel above root
right = root.tenon('right', size=3)    # 3-inch wide panel to the right

x = np.linspace(0, 10, 100)
root.ax.plot(x, np.sin(x))
top.ax.bar(range(8), np.random.rand(8))
right.ax.scatter(np.random.randn(50), np.random.randn(50))

fig.savefig('out.png', bbox_inches='tight')
```

Three things to know:

1. `create(figsize=...)` → `(fig, root)`, same pattern as `plt.subplots`
2. `root.tenon(pos, size)` → new panel; `size` is in **inches**
3. `.ax` → standard `matplotlib.axes.Axes`, works with any library

---

## Layout Model

```
figsize = (10, 8)

┌─────────────────────────────────┐
│           top  (size=2)         │
├──────────────────────┬──────────┤
│                      │  right   │
│       root           │ (size=3) │
│                      │          │
└──────────────────────┴──────────┘
```

`size` is always in inches — no percentages, no ratios.
If you want a panel that is 25% of figure height: `size = figsize[1] * 0.25`.

---

## Nesting

Any panel can have its own children:

```python
fig, root = create(figsize=(12, 8))

top       = root.tenon('top',  size=3)
top_left  = top.tenon('left',  size=3)   # child of top
top_right = top.tenon('right', size=3)   # child of top
```

---

## Third-Party Integration

```python
import seaborn as sns
import scanpy as sc

fig, root = create(figsize=(12, 8))
right = root.tenon('right', size=4)

sc.pl.umap(adata, ax=root.ax, show=False)
sns.violinplot(data=df, ax=right.ax)

fig.savefig('out.png', bbox_inches='tight')
```

### trackc (genome browser)

```python
import trackc.pl as pl
from sunmao import create

fig, scale = create(figsize=(12, 9))
signal = scale.tenon('top', size=1.5, pad=0.05)
genes  = scale.tenon('top', size=1.5, pad=0.05)
hic    = scale.tenon('top', size=3.0, pad=0.05)

region = 'chr18:47950000-48280000'
pl.bw_track(bw='signal.bw', ax=signal.ax, regions=region)
pl.gene_track(ax=genes.ax,  bed12='genes.bed12', regions=region)
pl.mapC(mat=hic_mat,         ax=hic.ax)
pl.scale_track(ax=scale.ax,  region=region)

fig.savefig('genome_browser.png', bbox_inches='tight')
```

---

## Documentation

- [Usage Guide](docs/usage.md) — full API reference and examples
- [Gallery](docs/gallery.md) — visual examples with code

---

## Gallery Preview

| Basic layout | Nested panels |
|---|---|
| ![basic](docs/_static/gallery_01_basic.png) | ![nested](docs/_static/gallery_02_nested.png) |

| Genome browser | seaborn / scanpy |
|---|---|
| ![genomics](docs/_static/gallery_04_genomics.png) | ![thirdparty](docs/_static/gallery_05_thirdparty.png) |

| ComplexHeatmap style | OncoPrint style |
|---|---|
| ![complexheatmap](docs/_static/gallery_07_complexheatmap.png) | ![oncoprint](docs/_static/gallery_08_oncoprint.png) |

| Multi-omics integration | |
|---|---|
| ![multiomics](docs/_static/gallery_09_multiomics.png) | |

---

## License

MIT

