Skip to main content
gsplot logo

Documentation PyPI Python License: MIT

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 and the issue tracker before depending on behavior that is not covered by the public API.

Install

gsplot supports Python 3.10 and newer:

python -m pip install gsplot

Quick example

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.

Configuration

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

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 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:

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:

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 for formatting, type checking, packaging, and Docker instructions.

For private vulnerability reports and the supported-version policy, see 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.

Metadata

Release files for gsplot 0.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gsplot 0.4.2
File Size Uploaded Provenance Actions
gsplot-0.4.2.tar.gz 153.5 kB With provenance Details for gsplot-0.4.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gsplot 0.4.2
File Interpreter ABI Platform Actions
gsplot-0.4.2-py3-none-any.whl Python 3 none any Details for gsplot-0.4.2-py3-none-any.whl

Total release size: 362.7 kB

Release files / gsplot-0.4.2.tar.gz

Download URL gsplot-0.4.2.tar.gz
Size 153.5 kB
Tags Source
SHA-256 checksum
How to use checksums
b9f47f927a48d5bcfd4a701b0a86fa7e80f77c55f8c14f79825e91fb7656f416
BLAKE2b-256 checksum
How to use checksums
2ca66b55f80198e2ea9882ec9b2af8cba8b8e070b65b6d51e241163efa2158d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.

Transparency log

Release files / gsplot-0.4.2-py3-none-any.whl

Download URL gsplot-0.4.2-py3-none-any.whl
Size 209.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b7c1d0d432389bb02ebb62e76435575be7b4b3368f2aa960fdeec87562dd8955
BLAKE2b-256 checksum
How to use checksums
bb30cb1a8fa622d56be56e11ffbaf00205d0cf5dfb69d5135b50f59e94e36a5c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.

Transparency log

Security for gsplot 0.4.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gsplot-0.4.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page