Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lgienapp/aquarel
Styling matplotlib made easy
https://github.com/lgienapp/aquarel
data-science data-visualization matplotlib plotting theme theme-development theming visualization
Last synced: about 2 months ago
JSON representation
Styling matplotlib made easy
- Host: GitHub
- URL: https://github.com/lgienapp/aquarel
- Owner: lgienapp
- License: mit
- Created: 2022-08-07T08:42:41.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-19T18:44:06.000Z (5 months ago)
- Last Synced: 2024-07-27T11:45:46.440Z (about 2 months ago)
- Topics: data-science, data-visualization, matplotlib, plotting, theme, theme-development, theming, visualization
- Language: Python
- Homepage:
- Size: 1.91 MB
- Stars: 610
- Watchers: 1
- Forks: 18
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Aquarel 🎨
[](https://pypi.org/project/aquarel/)
[]()
[](https://aquarel.readthedocs.io/en/latest/?badge=latest)
Aquarel is a lightweight templating engine and wrapper around Matplotlibs' `rcparams` to make styling plots simple.
Aquarel templates can be defined programmatically and be serialized and shared in a JSON format.
Full documentation is available at [aquarel.readthedocs.io](https://aquarel.readthedocs.io/en/latest/?badge=latest).
## Installation
Install via pip:
```sh
python -m pip install aquarel
```
## Usage
###### Applying a style
Styles can be either applied globally
```python
from aquarel import load_theme
theme = load_theme("arctic_light")
theme.apply()
# ... plotting code here
theme.apply_transforms()
```
...or with a context manager:
```python
from aquarel import load_theme
with load_theme("arctic_light"):
figure = # ... plotting code here
```
###### Transforms
Themes may specify _transforms_. Transforms are functions applied on the finished plot to achieve aesthetics that are not possibly by means of `rcparams` only.
For example, to trim the axes, one could apply the `trim` transform:
```python
from aquarel import load_theme
with load_theme("arctic_light").set_transforms(trim=True):
figure = # ... plotting code here
# plt.show() or savefig() have to be called outside the context manager to have the transforms correctly applied.
figure.savefig()
```
However, there is one important thing to keep in mind: since transforms require the matplotlib figure/axes object to be present and finished, they have to be applied **after** the plotting code.
When using a theme with a context manager, this is automatically done in the `__exit__` call. If global usage is desired, `Theme.apply_transforms()` has to be called after every figure.
This also means that calls that make use of the finished figure, i.e. `plt.show` or `plt.savefig` have to commence after transform application, so **outside** the context manager.
###### Customization & Theme Creation
Besides loading a predefined theme, you can create a new theme
```python
from aquarel import Theme
theme = (
Theme(name="demo", description="A demo theme.")
.set_grid(draw=True, width=0.5)
.set_font(family="monospace")
.set_color(grid_color="blue")
)
```
...modify an existing one
```python
from aquarel import load_theme
theme = (
load_theme("arctic_light")
.set_grid(width=2)
)
```
...and write and load your custom styles to and from disk:
```python
from aquarel import Theme
theme = Theme.from_file("custom.json")
theme.save("custom.json")
```
If the simplified API of aquarel is not sufficient for your use-case, you can also directly modify the underlying `rcparams` with overrides:
```python
from aquarel import load_theme
theme = load_theme("arctic_light").set_overrides({
"ytick.minor.visible": False,
"xtick.minor.visible": True
})
```
## Themes
aquarel ships with several pre-defined themes that are designed to showcase its templating capabilities.
Add your own with a pull request!
| Name | Description | Preview |
| :-------------- | :----------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- |
| [`ambivalent`](https://github.com/saforem2/ambivalent) | Transparent backgrounds with grey text $\textcolor{#838383}{\blacksquare}$ that are accessible / legible and `{light, dark}`-mode independent |  |
| `arctic_dark` | Frosty dark theme based on the [nord](https://github.com/arcticicestudio/nord) color scheme |  |
| `arctic_light` | Frosty dark theme based on the [nord](https://github.com/arcticicestudio/nord) color scheme |  |
| `boxy_dark` | Dark theme with enclosing box and grid |  |
| `boxy_light` | Light theme with enclosing box and grid |  |
| `gruvbox_dark` | Dark theme with pastel [retro groove colors](https://github.com/morhetz/gruvbox) |  |
| `gruvbox_light` | Light theme with pastel [retro groove colors](https://github.com/morhetz/gruvbox) |  |
| `minimal_dark` | Dark theme with minimal visual elements |  |
| `minimal_light` | Light theme with minimal visual elements |  |
| `scientific` | Space-efficient and color-blind friendly theme for printing on paper |  |
| `umbra_dark` | Balanced dark theme based on the [penumbra](https://github.com/nealmckee/penumbra) color scheme |  |
| `umbra_light` | Balanced light theme based on the [penumbra](https://github.com/nealmckee/penumbra) color scheme |  |
## FAQ
###### How is this different from matplotlib style sheets?
`aquarel` is a wrapper around the stylesheets, so everything you can do with stylesheets can be achieved with `aquarel`. However there are some notable shortcomings of stylesheets that `aquarel` adresses:
1. **On-the-fly templating** – the stylesheets are applied once and are then used for every plot in the current plotting context (py-file, notebook, ipython session, ...). `aquarel` takes a different approach here and aims to provide per-plot styling with optional temporary changes. The style `aquarel` applies lasts throughout the context manager (`with aquarel.Theme:`), and switches back to whatever is the global default style outside of it. This allows you to do plot-level temporary changes. You have one plot in your notebook that needs no minor ticks? just `with theme.set_ticks():` for this plot only.
2. **Simplified templating**: matplotlib stylesheets have a lot of redundant keys for most applications. For example, you rarely want to have different colors for both axes; while possible with a stylefile, its cumbersome to change all the different keys to achieve a uniform look. `aquarel` simplifies this with e.x. a single `set_color(ticks="#eee")` call, which changes all related and relevant keys for ticks. Note that this simplifies the API, but does not restrict capabilities: the `set_overrides` method accepts every possible stylefile key if you want to access low-level styling.
3. **Transforms**: some style elements, like trimmed axes, are not achievable with stylesheets alone (see README for more informations). `aquarel` defines a few of these transforms (and hopefully many more in the future), and makes them persistable and shareable through aquarel themes. Instead of having to apply a seaborn despine after every plot, you can have a global style that specifies a trim, and have consistent styling throughout with minimal code repetition.