Metadata-Version: 2.4
Name: skyline-plots
Version: 0.12.0b0
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
Requires-Dist: tomli>=1.1.0; python_version < "3.11"
Provides-Extra: ensembl
Requires-Dist: ensembl-rest-client; extra == "ensembl"
Provides-Extra: merit
Requires-Dist: merit>=0.5.0a0; extra == "merit"
Requires-Dist: genomic-config>=0.1.6; extra == "merit"
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.12.0b0`

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 draw into Matplotlib Axes (they are not Axes subclasses), with
hierarchical `Theme` styles and full access to Figure / Axes / Artists.
Import from the package root (`from skyline import manhattan, Theme, …`).

### Recipes vs tracks

Skyline offers two complementary surfaces:

| Layer | What it is | When to use it |
|-------|------------|----------------|
| **Recipes** | Functions (`manhattan`, `miami`, `locus_scatter`, …) that return a `PlotResult` | Common figures, pipelines, and automation — few lines to a finished plot |
| **Tracks** | 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 cover everyday plots; tracks are 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 fine-tuning
```

## 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, organised
by plot family:

1. Foundations (styles, offline GTF/GFF)
2. Genome-wide plots (Manhattan → labels → highlights → Miami → grid → GenomicScatter)
3. Locus plots (locus view → genes → LD → skyview/linkers → dual-locus panel)
4. Composition (hand-built multi-track figures)

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`.
