Metadata-Version: 2.5
Name: plot_io
Version: 0.1.0
Summary: Plots for PDF, PNG and JPEG, drawn with pdf_io
Author-email: Arthur Gouhier <ajgouhier@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: pdf-io>=0.4
Provides-Extra: dev
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Description-Content-Type: text/markdown

# plot_io

Plots for PDF, PNG and JPEG in Python, drawn with [pdf_io](https://github.com/ajgouhier/pdf_io).
No other dependency.

![box plots](examples/box_plots.png)

* **Familiar:** a figure of plots; `scatter`, `line`, `fill`, `box`, `heatmap`, `bar`,
  `hist`, `kde` (1-D and 2-D), `ecdf`, `violin`, `strip`, `swarm`, `area`, `errorbar`, `stem`,
  `regression`, `hist2d`, `hexbin`, `contour`, `pie`; reference lines, spans, text and
  annotations; `color`, `marker`, `alpha`, `limits`, `scale`, `legend`, sizes in inches.
* **One way to set things:** keywords at creation or `set(...)` on any object; figure
  settings (font, palette, line width…) are inherited by plots and series.
* **Layouts:** an explicit grid of ids with spans, or automatic rows and columns; plots
  sized individually; axis lines (or plot borders) aligned across the figure; margins from
  the real text metrics; shared axes; secondary axes; facets of a table.
* **Data:** columns of any table by name (`data=`: dicts, pandas, polars, numpy), one
  series per group (`group=`), numbers given as colors or sizes, point density (scipy's
  `gaussian_kde`, in C) for colors, sizes, opacity and drawing order.
* **Axes:** linear, log, log2, log10, sqrt, exp, symlog, logit, time and category scales;
  limits such as `"0/max"` or `"q:0.01/q:0.99"`; ticks with shared decimals and ×10ᵏ
  factors, calendar ticks for dates.
* **Colors:** a colorblind-safe palette, color maps interpolated in Oklab, colorbars;
  marker sizes by area, equal for every shape.
* **Styles:** `style="matplotlib"`, `"seaborn"`, `"ggplot2"`, `"altair"`, `"matlab"`,
  `"chartjs"`, `"plotly"`, `"bokeh"`, `"observable"`, `"excel"`, `"fivethirtyeight"`,
  `"economist"`, `"tufte"` and variants give the look of those libraries; styles are
  presets of settings, and your own build on them.
* **Large data:** one million points mapped and drawn in C; `simplify="auto"` drops what
  cannot be seen, `rasterize=` turns a series into an image inside the PDF.

## Install

```sh
pip install /path/to/pdf_io      # pdf_io 0.4 or later
pip install .
```

Python 3.11+.

## Quick start

```python
import plot_io as pl

s = pl.Scatter(x, y, name="data")
s.plot.x_axis(label="Time (s)")
s.plot.save("scatter.pdf")
```

```python
fig = pl.Figure(grid=[[1, 1, 2], [3, 4, 2]])
p = fig.plot(1, title="Signal")
p.line(t, v, name="raw")
p.fill(t, upper, lower, alpha=0.3)
p.y_axis(scale="log10", label="Power")
fig.plot(2).box({"a": va, "b": vb})
h = fig.plot(3).heatmap(matrix, x=columns, y=rows, cmap="magma", colorbar=True)
fig.plot(4).scatter(x, y, c=z, cmap="viridis")
fig.save("figure.pdf")
fig.save("figure.png", dpi=200)
```

```python
fig = pl.Figure(style="ggplot2")                         # or a dict: {"base": "seaborn", "font_size": 9}
```

```python
p = pl.Plot()
p.scatter("umap_x", "umap_y", data=genes, c="density", order="density")   # columns of a table
p.scatter("x", "y", data=df, group="cluster", marker="auto")              # one series per group
fig = pl.facet(df, col="condition", row="replicate")                       # small multiples
fig.scatter("x", "y")
```

## Documentation

* [API.md](API.md): the complete reference, with every setting.
* [EXAMPLES.md](EXAMPLES.md): worked examples.

## Development

```sh
python -m unittest discover -s tests -t tests
flake8 --select F plot_io tests && mypy
python tools/bench.py --check       # timings against the targets
python tools/settings_doc.py        # regenerate the settings tables of API.md
```
