{"id":13478007,"url":"https://github.com/lgienapp/aquarel","last_synced_at":"2025-05-14T14:08:01.227Z","repository":{"id":54345014,"uuid":"522159839","full_name":"lgienapp/aquarel","owner":"lgienapp","description":"Styling matplotlib made easy","archived":false,"fork":false,"pushed_at":"2025-03-01T13:53:36.000Z","size":2109,"stargazers_count":788,"open_issues_count":5,"forks_count":20,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-13T11:15:09.630Z","etag":null,"topics":["data-science","data-visualization","matplotlib","plotting","theme","theme-development","theming","visualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lgienapp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-07T08:42:41.000Z","updated_at":"2025-05-02T14:44:08.000Z","dependencies_parsed_at":"2024-04-19T19:46:26.561Z","dependency_job_id":"4932a49d-76ac-4f0e-b76b-25cfea140170","html_url":"https://github.com/lgienapp/aquarel","commit_stats":{"total_commits":63,"total_committers":5,"mean_commits":12.6,"dds":"0.23809523809523814","last_synced_commit":"bc156cd88a2e7b8105e0f23dae21b9e3774220d3"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lgienapp%2Faquarel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lgienapp%2Faquarel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lgienapp%2Faquarel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lgienapp%2Faquarel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lgienapp","download_url":"https://codeload.github.com/lgienapp/aquarel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254159515,"owners_count":22024562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-science","data-visualization","matplotlib","plotting","theme","theme-development","theming","visualization"],"created_at":"2024-07-31T16:01:51.159Z","updated_at":"2025-05-14T14:08:01.207Z","avatar_url":"https://github.com/lgienapp.png","language":"Python","funding_links":[],"categories":["Python","Plotting"],"sub_categories":[],"readme":"# Aquarel 🎨\n\n[![PyPi](https://img.shields.io/pypi/v/aquarel)](https://pypi.org/project/aquarel/)\n[![License](https://img.shields.io/github/license/lgienapp/aquarel)]()\n[![Documentation Status](https://readthedocs.org/projects/aquarel/badge/?version=latest)](https://aquarel.readthedocs.io/en/latest/?badge=latest)\n\nAquarel is a lightweight templating engine and wrapper around Matplotlibs' `rcparams` to make styling plots simple.\nAquarel templates can be defined programmatically and be serialized and shared in a JSON format.\n\nFull documentation is available at [aquarel.readthedocs.io](https://aquarel.readthedocs.io/en/latest/?badge=latest).\n\n## Installation\n\nInstall via pip:\n\n```sh\npython -m pip install aquarel\n```\n\n## Usage\n\n###### Applying a style\n\nStyles can be either applied globally\n\n```python\nfrom aquarel import load_theme\n\ntheme = load_theme(\"arctic_light\")\ntheme.apply()\n# ... plotting code here\ntheme.apply_transforms()\n```\n\n...or with a context manager:\n\n```python\nfrom aquarel import load_theme\n\nwith load_theme(\"arctic_light\"):\n    figure = # ... plotting code here\n```\n\n###### Transforms\n\nThemes may specify _transforms_. Transforms are functions applied on the finished plot to achieve aesthetics that are not possibly by means of `rcparams` only.\nFor example, to trim the axes, one could apply the `trim` transform:\n\n```python\nfrom aquarel import load_theme\n\nwith load_theme(\"arctic_light\").set_transforms(trim=True):\n    figure = # ... plotting code here\n\n# plt.show() or savefig() have to be called outside the context manager to have the transforms correctly applied.\nfigure.savefig()\n```\n\nHowever, 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.\nWhen 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.\nThis 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.\n\n###### Customization \u0026 Theme Creation\n\nBesides loading a predefined theme, you can create a new theme\n\n```python\nfrom aquarel import Theme\n\ntheme = (\n    Theme(name=\"demo\", description=\"A demo theme.\")\n    .set_grid(draw=True, width=0.5)\n    .set_font(family=\"monospace\")\n    .set_color(grid_color=\"blue\")\n)\n```\n\n...modify an existing one\n\n```python\nfrom aquarel import load_theme\n\ntheme = (\n    load_theme(\"arctic_light\")\n    .set_grid(width=2)\n)\n```\n\n...and write and load your custom styles to and from disk:\n\n```python\nfrom aquarel import Theme\n\ntheme = Theme.from_file(\"custom.json\")\ntheme.save(\"custom.json\")\n```\n\nIf the simplified API of aquarel is not sufficient for your use-case, you can also directly modify the underlying `rcparams` with overrides:\n\n```python\nfrom aquarel import load_theme\n\ntheme = load_theme(\"arctic_light\").set_overrides({\n    \"ytick.minor.visible\": False,\n    \"xtick.minor.visible\": True\n})\n```\n\n## Themes\n\naquarel ships with several pre-defined themes that are designed to showcase its templating capabilities.\nAdd your own with a pull request!\n\n| Name                                                   | Description                                                                                                                                   | Preview                                                                                |\n| :----------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |\n| [`ambivalent`](https://github.com/saforem2/ambivalent) | Transparent backgrounds with grey text $\\textcolor{#838383}{\\blacksquare}$ that are accessible / legible and `{light, dark}`-mode independent | ![](https://github.com/saforem2/aquarel/blob/main/assets/ambivalent.png?raw=true)      |\n| `arctic_dark`                                          | Frosty dark theme based on the [nord](https://github.com/arcticicestudio/nord) color scheme                                                   | ![](https://github.com/lgienapp/aquarel/blob/main/assets/arctic_dark.png?raw=true)     |\n| `arctic_light`                                         | Frosty dark theme based on the [nord](https://github.com/arcticicestudio/nord) color scheme                                                   | ![](https://github.com/lgienapp/aquarel/blob/main/assets/arctic_light.png?raw=true)    |\n| `boxy_dark`                                            | Dark theme with enclosing box and grid                                                                                                        | ![](https://github.com/lgienapp/aquarel/blob/main/assets/boxy_dark.png?raw=true)       |\n| `boxy_light`                                           | Light theme with enclosing box and grid                                                                                                       | ![](https://github.com/lgienapp/aquarel/blob/main/assets/boxy_light.png?raw=true)      |\n| `gruvbox_dark`                                         | Dark theme with pastel [retro groove colors](https://github.com/morhetz/gruvbox)                                                              | ![](https://github.com/lgienapp/aquarel/blob/main/assets/gruvbox_dark.png?raw=true)    |\n| `gruvbox_light`                                        | Light theme with pastel [retro groove colors](https://github.com/morhetz/gruvbox)                                                             | ![](https://github.com/lgienapp/aquarel/blob/main/assets/gruvbox_light.png?raw=true)   |\n| `minimal_dark`                                         | Dark theme with minimal visual elements                                                                                                       | ![](https://github.com/lgienapp/aquarel/blob/main/assets/minimal_dark.png?raw=true)    |\n| `minimal_light`                                        | Light theme with minimal visual elements                                                                                                      | ![](https://github.com/lgienapp/aquarel/blob/main/assets/minimal_light.png?raw=true)   |\n| `scientific`                                           | Space-efficient and color-blind friendly theme for printing on paper                                                                          | ![](https://github.com/lgienapp/aquarel/blob/main/assets/scientific.png?raw=true)      |\n| `solarized_dark`                                       | Dark theme based on the [solarized](https://ethanschoonover.com/solarized/) color scheme                                                      | ![](https://github.com/lgienapp/aquarel/blob/main/assets/solarized_dark.png?raw=true)  |\n| `solarized_light`                                      | Light theme based on the [solarized](https://ethanschoonover.com/solarized/) color scheme                                                     | ![](https://github.com/lgienapp/aquarel/blob/main/assets/solarized_light.png?raw=true) |\n| `umbra_dark`                                           | Balanced dark theme based on the [penumbra](https://github.com/nealmckee/penumbra) color scheme                                               | ![](https://github.com/lgienapp/aquarel/blob/main/assets/umbra_dark.png?raw=true)      |\n| `umbra_light`                                          | Balanced light theme based on the [penumbra](https://github.com/nealmckee/penumbra) color scheme                                              | ![](https://github.com/lgienapp/aquarel/blob/main/assets/umbra_light.png?raw=true)     |\n\n## FAQ\n\n###### How is this different from matplotlib style sheets?\n\n`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:\n\n1. **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.\n2. **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.\n3. **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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flgienapp%2Faquarel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flgienapp%2Faquarel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flgienapp%2Faquarel/lists"}