Metadata-Version: 2.4
Name: omicsplot
Version: 0.1.0
Summary: Publication-quality matplotlib figures for omics data
Project-URL: Homepage, https://github.com/gitbamboo42/omicsplot
Project-URL: Repository, https://github.com/gitbamboo42/omicsplot
Project-URL: Issues, https://github.com/gitbamboo42/omicsplot/issues
Author: gitbamboo42
License: MIT
License-File: LICENSE
Keywords: bioinformatics,complexheatmap,genomics,heatmap,matplotlib,omics,publication,visualization
Classifier: Development Status :: 3 - Alpha
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.7
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: seaborn>=0.12
Description-Content-Type: text/markdown

# omicsplot

Publication-quality matplotlib figures for omics data, with two focuses:

- **`omicsplot.heatmap`** — ComplexHeatmap-style heatmaps where the body is
  specified in **absolute physical units** (mm, cm, inch, pt). Surrounding
  panels (dendrograms, annotations, labels, colorbar, legend) grow outward
  without shrinking the body. Multi-panel composition with `|` (side-by-side)
  and `/` (stacked) keeps body positions exactly aligned across panels.
  Includes a chromosome-aware `genomic_heatmap` for binned signals
  (methylation, expression, copy number, accessibility).

- **`omicsplot.tracks`** — genome-wide track plots stacked vertically across
  per-chromosome subplot axes sized **proportionally to chromosome lengths**.
  Built-in track types: scatter, line segments, bar, step coverage, SV
  triangles. Trivially extensible by subclassing `_BaseTrack`.

Both submodules share a unit system inspired by R's `grid::unit()`:
absolute (`mm`, `cm`, `inch`, `pt`), relative (`npc`), and flexible (`null`).

## Install

```bash
pip install omicsplot
```

Requires Python ≥ 3.10. Depends on numpy, pandas, matplotlib, scipy, seaborn.

## Quick start

The snippets below show the API for each value proposition. Complete
runnable examples — including synthetic data generation — are in
[docs/scripts/render_readme.py](docs/scripts/render_readme.py), which
produces the figures shown here.

### Heatmap with absolute physical sizing

```python
from omicsplot import unit
from omicsplot.heatmap import Heatmap, HeatmapAnnotation

hm = Heatmap(
    df,
    width=unit(120, 'mm'),
    height=unit(50, 'mm'),
    row_dendrogram_size=unit(12, 'mm'),
    col_dendrogram_size=unit(10, 'mm'),
    z_score=0,                 # row-wise normalization
    cmap='RdBu_r',
    center=0,
)
hm.add_top_annotation(HeatmapAnnotation(
    group=sample_groups,
    batch=sample_batch,
    height=unit(3, 'mm'),
))
hm.draw()
```

![heatmap with absolute physical sizing](https://raw.githubusercontent.com/gitbamboo42/omicsplot/main/docs/images/heatmap_basic.png)

### Multi-panel composition

Use `|` for side-by-side and `/` for stacked. With `share_row_order=True`
(side-by-side) or `share_col_order=True` (stacked), bodies stay aligned
across panels.

```python
hm_a = Heatmap(mat_a, width=unit(40, 'mm'), height=unit(45, 'mm'),
               cmap='RdBu_r', center=0, name='Expression',
               show_row_names=False)
hm_a.add_left_annotation(HeatmapAnnotation(
    Group=groups, colors=group_colors, width=unit(4, 'mm'),
))

hm_b = Heatmap(mat_b, width=unit(25, 'mm'), height=unit(45, 'mm'),
               cmap='YlOrRd', col_cluster=False, name='Copy number',
               show_row_names=False)

(hm_a | hm_b).draw(share_row_order=True)
```

![side-by-side composition with aligned bodies](https://raw.githubusercontent.com/gitbamboo42/omicsplot/main/docs/images/heatmap_compose.png)

Compound layouts also work: `(A | B) / C`, `A | B | C`, etc.

### Chromosome-aware genomic heatmap

`genomic_heatmap` takes a long-form matrix with `chrom`/`start`/`end`
columns and arranges the columns into chromosome-proportional segments.
The optional cluster-of-clusters dendrogram (`row_cluster_dendrogram`)
shows relationships between groups, not individual rows.

```python
from omicsplot.heatmap import genomic_heatmap

genomic_heatmap(
    matrix,                    # columns: chrom, start, end, then per-cell
    chrom_col='chrom',
    cmap='bwr', vmin=0, vmax=4, center=2,
    row_cluster=False,
    show_row_names=False,
    row_annotation={'Cluster': cluster_labels},
    row_annotation_colors={'Cluster': palette},
    row_gap=unit(2, 'mm'),
    row_cluster_dendrogram=cluster_link,             # leaves are groups
    row_cluster_dendrogram_size=unit(10, 'mm'),
)
```

![chromosome-aware genomic heatmap with cluster dendrogram](https://raw.githubusercontent.com/gitbamboo42/omicsplot/main/docs/images/genomic_heatmap.png)

### Genome-wide tracks

Each chromosome gets its own subplot axis sized proportionally to its
length. `genome_range` returns chromosome lengths for common builds.

```python
from omicsplot import genome_range
from omicsplot.tracks import ScatterTrack, plot_tracks

gs = genome_range(genome='hg38')

scatter = ScatterTrack(
    points, x_column='start', y_column='value',
    ylabel='logR', ylim=(-1.5, 1.5),
    s=1, alpha=0.4,
)
plot_tracks(scatter, gs, figsize=(10, 0.8))
```

![genome-wide tracks with chromosome-proportional axes](https://raw.githubusercontent.com/gitbamboo42/omicsplot/main/docs/images/tracks.png)

## Status

Alpha. API may change before 1.0.

## License

MIT.
