Metadata-Version: 2.4
Name: gsplot
Version: 0.4.1
Summary: Concise publication-quality scientific plotting built on Matplotlib
License-Expression: MIT
License-File: LICENSE
Keywords: matplotlib,plotting,publication,scientific
Author: Giordano Mattoni
Maintainer: Soichiro Yamane
Requires-Python: >=3.10
Classifier: Programming Language :: Python :: 3
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
Requires-Dist: matplotlib (>=3.9.0)
Requires-Dist: numpy (>=1.26.4)
Project-URL: Documentation, https://soichiroyamane.github.io/gsplot/stable/
Project-URL: Homepage, https://soichiroyamane.github.io/gsplot/
Project-URL: Issues, https://github.com/SoichiroYamane/gsplot/issues
Project-URL: Repository, https://github.com/SoichiroYamane/gsplot
Description-Content-Type: text/markdown

<div align="center">
  <img src="https://raw.githubusercontent.com/SoichiroYamane/gsplot/main/docs/_static/logo/logo_title_gsplot.png" alt="gsplot logo" width="300">
</div>

[![Documentation](https://github.com/SoichiroYamane/gsplot/actions/workflows/gh-pages-sphinx.yml/badge.svg)](https://soichiroyamane.github.io/gsplot/stable/)
[![PyPI](https://img.shields.io/pypi/v/gsplot)](https://pypi.org/project/gsplot/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green)](https://github.com/SoichiroYamane/gsplot/blob/main/LICENSE)

# gsplot

`gsplot` creates publication-quality scientific figures with a concise API on
top of Matplotlib. It adds paper-aware layouts, deterministic plotting and
styling helpers, validated JSON defaults, and lightweight build metadata while
returning ordinary Matplotlib `Figure`, `Axes`, and Artist objects.

The package is still evolving. Check the [documentation](https://soichiroyamane.github.io/gsplot/stable/)
and the [issue tracker](https://github.com/SoichiroYamane/gsplot/issues) before
depending on behavior that is not covered by the public API.

## Install

`gsplot` supports Python 3.10 and newer:

```bash
python -m pip install gsplot
```

## Quick example

```python
import gsplot as gs

fig, axes = gs.subplots("AB")
gs.line(axes["A"], [0, 1, 2], [0, 1, 4], label="quadratic")
gs.scatter(axes["B"], [0, 1, 2], [0, 1, 4], label="samples", s=15)
gs.label(axes, "x", "value", square=True, index="in")
gs.legend(axes)
gs.save(fig, "quickstart", show=False)
```

This creates a two-panel Matplotlib figure, saves `quickstart.png` and
`quickstart.pdf`, and remains compatible with regular Matplotlib operations.

The canonical helpers always receive their Figure or Axes target explicitly.
`save` writes PNG and PDF transactionally at 600 DPI with a tight crop and
displays the Figure after successful writes by default; pass `show=False` for
batch or headless output. Use `crop=False` when output dimensions must match
the Figure design canvas exactly. The advanced `savefig` helper retains its
conservative output controls.

For a complete scientific example, see the
[publication example](https://soichiroyamane.github.io/gsplot/dev/guides/examples/publication.html).

## Configuration

Configuration is optional and explicit. Load a schema-2 JSON file and pass the
immutable value to supported functions:

```python
import gsplot as gs

config = gs.load_config("path/to/gsplot.json")
fig, axes = gs.subplots(config=config)
```

When a value is specified more than once, the precedence is:

1. an argument passed directly to the function;
2. the supplied immutable `Config` value;
3. the function's default value.

Canonical code never searches the working directory or home directory for a
configuration file. See the [configuration guide](https://soichiroyamane.github.io/gsplot/dev/guides/examples/configuration.html)
for the supported schema, precedence, and backend notes.

## Development

The repository uses Poetry and targets Python 3.10 or newer. With a compatible
Python interpreter:

```bash
python -m pip install "poetry==2.4.1"
poetry install
MPLBACKEND=Agg poetry run pytest -q
MPLBACKEND=Agg poetry run sphinx-build -W -b html docs docs/_build/html
```

The scripts under `examples/` are executable documentation. Run one from its own
directory, for example:

```bash
cd examples/layouts && python mosaic.py
```

`examples/compatibility/legacy_v0.py` intentionally demonstrates the deprecated
0.x surface. All other plotting examples use the canonical explicit-target API.

See [the developer setup guide](https://soichiroyamane.github.io/gsplot/stable/reference/contribution/developer_env.html)
for formatting, type checking, packaging, and Docker instructions.

For private vulnerability reports and the supported-version policy, see
[SECURITY.md](https://github.com/SoichiroYamane/gsplot/blob/main/SECURITY.md).

## Authors and maintenance

This repository builds on the original code developed by Giordano Mattoni.

- Original author: Giordano Mattoni
- Maintainer: Soichiro Yamane

## License

This project is distributed under the
[MIT License](https://github.com/SoichiroYamane/gsplot/blob/main/LICENSE).

