aquarel: Lightweight templating engine for matplotlib

0.0.7 · active · verified Sun Apr 12

Aquarel is a lightweight templating engine and wrapper around Matplotlib's rcparams designed to simplify plot styling. It enables programmatic definition and JSON serialization of themes, facilitating sharing and consistent visualization across projects. Beyond standard Matplotlib stylesheets, Aquarel introduces 'transforms' for aesthetics not achievable via rcparams alone, such as trimmed axes. The library is actively maintained with frequent minor updates.

Warnings

gotcha Aquarel 'transforms' (e.g., for trimming axes) must be applied after the plot objects (figure/axes) are created. While the context manager (`with load_theme(...)`) handles this automatically on exit, if applying a theme globally (`theme.apply()`), you must manually call `theme.apply_transforms()` after all plotting commands for the effects to take place.
Fix: Use the context manager (`with load_theme(...):`) for automatic transform application, or ensure `theme.apply_transforms()` is explicitly called after plot creation when applying themes globally.
gotcha When using a theme with transforms via the context manager, ensure `plt.show()` or `fig.savefig()` is called *outside* the `with` block. This guarantees that transforms, which modify the finished figure, are correctly applied before rendering or saving.
Fix: Place `plt.show()` or `fig.savefig()` after the `with load_theme(...):` block.
breaking Version 0.0.6 addressed an incompatibility with `MatplotlibDeprecationWarning`. Users on older `aquarel` versions might encounter issues or warnings with newer Matplotlib releases, or conversely, `aquarel` updates might require a specific Matplotlib version to resolve internal warnings.
Fix: Upgrade to `aquarel` version 0.0.6 or newer to ensure compatibility with recent Matplotlib changes and avoid deprecation warnings.
gotcha Unlike standard Matplotlib stylesheets that are applied once globally for the current plotting context, Aquarel aims to provide per-plot styling with temporary changes. The style applied within an Aquarel context manager is only active inside that block and reverts outside of it, which differs from how global `plt.style.use()` typically functions.
Fix: Understand that Aquarel's context manager provides scoped styling. For persistent global styling, `theme.apply()` can be used, but remember the implications for transforms.

Install

pip install aquarel Install with pip

Imports

load_theme
```
from aquarel import load_theme
```

Quickstart

This quickstart demonstrates how to apply an Aquarel theme using a context manager. The `load_theme()` function fetches a predefined theme, which is then applied within the `with` block. All plotting commands inside this block will adopt the specified theme. Remember that `plt.savefig()` or `plt.show()` should be called *outside* the context manager if transforms are used, to ensure they are correctly applied.

import matplotlib.pyplot as plt
import numpy as np
from aquarel import load_theme

# Define a sample plotting function
def create_plot():
    fig, ax = plt.subplots(figsize=(8, 6))
    x = np.linspace(0, 10, 100)
    y = np.sin(x)
    ax.plot(x, y, label='Sine Wave')
    ax.set_title('Sample Plot')
    ax.set_xlabel('X-axis')
    ax.set_ylabel('Y-axis')
    ax.legend()
    return fig

# Apply a theme using a context manager
with load_theme('arctic_light'):
    fig = create_plot()
    plt.savefig('arctic_light_plot.png')
    # In a non-script environment (e.g., Jupyter), you might call plt.show() here if needed

print('Plot with arctic_light theme saved to arctic_light_plot.png')

view raw JSON →