Metadata-Version: 2.4
Name: skyline-plots
Version: 0.4.2a0
Summary: Genomic plotting toolkit (Manhattan, Miami, locus-view and tracks)
Author-email: Chris Finan <c.finan@ucl.ac.uk>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://cfinan.gitlab.io/skyline/
Project-URL: Repository, https://gitlab.com/cfinan/skyline
Project-URL: Documentation, https://cfinan.gitlab.io/skyline/
Keywords: genomics,gwas,manhattan,plotting,matplotlib
Classifier: Programming Language :: Python
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 :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: <3.14,>=3.9
Description-Content-Type: text/markdown
License-File: LICENCE.txt
Requires-Dist: matplotlib>=3.5
Requires-Dist: numpy
Requires-Dist: pandas>=2
Requires-Dist: pysam
Provides-Extra: ensembl
Requires-Dist: ensembl-rest-client; extra == "ensembl"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-dependency>=0.5; extra == "dev"
Requires-Dist: bump2version; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: ensembl-rest-client; extra == "dev"
Dynamic: license-file

# Getting Started with skyline

__version__: `0.4.2a0`

The skyline package is a genomic plotting toolkit. It was initially put
together to plot Manhattan plots but can be generalised to plot general genomic
"track" based data. Currently you can:

1. Plot Manhattan style plots
2. Plot Miami style plots
3. Plot skyview plots (multiple Manhattans stacked and viewed from the top)
4. Locus view type plots
5. Link tracks together with different sorts of linkers
6. Add label tracks

## Architecture

Tracks are **first-class** objects that draw into Matplotlib Axes (they are
not Axes subclasses), with hierarchical `Theme` styles and full access to
Figure / Axes / Artists. Prefer imports from the package root
(`from skyline import manhattan, Theme, …`).

### High-level vs low-level API

Skyline offers two complementary surfaces:

| Layer | What it is | When to use it |
|-------|------------|----------------|
| **High-level** | Recipe **functions** (`manhattan`, `miami`, `locus_scatter`, …) that return a `PlotResult` | Common figures, pipelines, and automation — few lines to a finished plot |
| **Low-level** | Track / building-block **classes** (`GenomicScatter`, `GeneTrack`, linkers, rulers, grids, …) with `draw(ax)` | Custom multi-track figures and layouts recipes do not cover |
| **Shared** | Hierarchical `Theme` / role-leaf styles | Styling both recipes and hand-built tracks |

Recipes are the stable façade for everyday use; the low-level API is for
composition and control. Matplotlib remains available underneath both
(e.g. `result.scatter.ax`).

```python
from skyline import HumanGRCh38, manhattan

res = manhattan(gwas_df, HumanGRCh38())
res.savefig("manhattan.png")
res.scatter.ax.axhline(y=7.3, ls="--")  # Matplotlib escape hatch
```

## Installation

### Conda

```
conda install -c cfin -c bioconda -c conda-forge skyline-plots
```

Optional Ensembl REST helpers:

```
pip install "skyline-plots[ensembl]"
# or install ensembl-rest-client into the same environment
```

### Pip (from PyPI)

```
pip install skyline-plots
pip install "skyline-plots[ensembl]"   # optional REST features
```

The import package is still ``skyline`` (``from skyline import …``).

### From a clone (development)

```
git clone git@gitlab.com:cfinan/skyline.git
cd skyline
python -m pip install -e ".[dev]"
```

For Ensembl-backed locus features during development:

```
python -m pip install -e ".[dev,ensembl]"
```

## Example / demo data

Large example GWAS tables are **not** shipped in the installed package (they
remain in the git tree under `skyline/example_data/` for local notebooks and
scripts). A small assembly coordinate file required by
`HumanGRCh37` / `HumanGRCh38` / `HumanNCBI36` **is** installed.

A download helper or documented data archive for demos is planned; until then
use a git checkout for full examples.

## Documentation

Online: [https://cfinan.gitlab.io/skyline/](https://cfinan.gitlab.io/skyline/)

The docs home page mirrors this README. A progressive **tutorial** lives
under `resources/examples/` and the Sphinx “Tutorial” section. Notebook
titles are tagged `[high-level]`, `[low-level]`, or `[shared]` so the
layer is obvious in the sidebar:

1. High-level recipes (Manhattan, Miami, locus view)
2. Shared styles (`Theme`)
3. Low-level tracks (scatter, genes, skyview / linkers / grids)
4. Composition (recipe grids, hand-built multi-track figures, dual-locus capstone)

Local docs / CI dry-run (docker + pytest + Sphinx, HTML rsynced to pCloud):

```
cd resources/ci_cd
./build.sh
```

## Tests

```
pytest tests/
```

## Licence

GPLv3+ — see `LICENCE.txt`.
