nicefigs 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- nicefigs-1.0.0/.gitignore +26 -0
- nicefigs-1.0.0/CHANGELOG.md +44 -0
- nicefigs-1.0.0/LICENSE +21 -0
- nicefigs-1.0.0/PKG-INFO +182 -0
- nicefigs-1.0.0/README.md +128 -0
- nicefigs-1.0.0/pyproject.toml +96 -0
- nicefigs-1.0.0/src/nicefigs/__init__.py +259 -0
- nicefigs-1.0.0/src/nicefigs/animation.py +327 -0
- nicefigs-1.0.0/src/nicefigs/artists.py +285 -0
- nicefigs-1.0.0/src/nicefigs/atlas.py +220 -0
- nicefigs-1.0.0/src/nicefigs/bars.py +180 -0
- nicefigs-1.0.0/src/nicefigs/colorbars.py +195 -0
- nicefigs-1.0.0/src/nicefigs/colormaps2d.py +329 -0
- nicefigs-1.0.0/src/nicefigs/comparison.py +222 -0
- nicefigs-1.0.0/src/nicefigs/data.py +581 -0
- nicefigs-1.0.0/src/nicefigs/figure.py +302 -0
- nicefigs-1.0.0/src/nicefigs/hovmoller.py +254 -0
- nicefigs-1.0.0/src/nicefigs/images.py +440 -0
- nicefigs-1.0.0/src/nicefigs/kde.py +187 -0
- nicefigs-1.0.0/src/nicefigs/lines.py +138 -0
- nicefigs-1.0.0/src/nicefigs/maps.py +1034 -0
- nicefigs-1.0.0/src/nicefigs/palettes.py +579 -0
- nicefigs-1.0.0/src/nicefigs/panels.py +503 -0
- nicefigs-1.0.0/src/nicefigs/pareto.py +247 -0
- nicefigs-1.0.0/src/nicefigs/py.typed +0 -0
- nicefigs-1.0.0/src/nicefigs/ranking.py +252 -0
- nicefigs-1.0.0/src/nicefigs/scatter.py +224 -0
- nicefigs-1.0.0/src/nicefigs/sections.py +335 -0
- nicefigs-1.0.0/src/nicefigs/spectra.py +187 -0
- nicefigs-1.0.0/src/nicefigs/style.py +324 -0
- nicefigs-1.0.0/src/nicefigs/tables.py +330 -0
- nicefigs-1.0.0/src/nicefigs/taylor.py +212 -0
- nicefigs-1.0.0/src/nicefigs/ternary.py +364 -0
- nicefigs-1.0.0/src/nicefigs/timeseries.py +262 -0
- nicefigs-1.0.0/src/nicefigs/units.py +219 -0
- nicefigs-1.0.0/src/nicefigs/verification.py +381 -0
- nicefigs-1.0.0/tests/conftest.py +25 -0
- nicefigs-1.0.0/tests/test_agreement.py +120 -0
- nicefigs-1.0.0/tests/test_animation.py +67 -0
- nicefigs-1.0.0/tests/test_api.py +71 -0
- nicefigs-1.0.0/tests/test_api_bars.py +40 -0
- nicefigs-1.0.0/tests/test_api_comparison.py +12 -0
- nicefigs-1.0.0/tests/test_api_data.py +72 -0
- nicefigs-1.0.0/tests/test_api_lines.py +18 -0
- nicefigs-1.0.0/tests/test_api_maps_images.py +116 -0
- nicefigs-1.0.0/tests/test_api_panels.py +73 -0
- nicefigs-1.0.0/tests/test_api_pareto.py +41 -0
- nicefigs-1.0.0/tests/test_api_ranking.py +19 -0
- nicefigs-1.0.0/tests/test_api_scatter.py +17 -0
- nicefigs-1.0.0/tests/test_api_sections.py +48 -0
- nicefigs-1.0.0/tests/test_api_taylor.py +26 -0
- nicefigs-1.0.0/tests/test_api_units.py +31 -0
- nicefigs-1.0.0/tests/test_artists.py +89 -0
- nicefigs-1.0.0/tests/test_atlas.py +121 -0
- nicefigs-1.0.0/tests/test_categorical_map.py +518 -0
- nicefigs-1.0.0/tests/test_colorbars.py +92 -0
- nicefigs-1.0.0/tests/test_comparison.py +79 -0
- nicefigs-1.0.0/tests/test_extensions.py +105 -0
- nicefigs-1.0.0/tests/test_figure.py +159 -0
- nicefigs-1.0.0/tests/test_figure_helpers.py +100 -0
- nicefigs-1.0.0/tests/test_gridded_maps.py +92 -0
- nicefigs-1.0.0/tests/test_images.py +128 -0
- nicefigs-1.0.0/tests/test_maps.py +186 -0
- nicefigs-1.0.0/tests/test_palettes.py +230 -0
- nicefigs-1.0.0/tests/test_panels.py +332 -0
- nicefigs-1.0.0/tests/test_plots.py +303 -0
- nicefigs-1.0.0/tests/test_render_animation.py +61 -0
- nicefigs-1.0.0/tests/test_roles.py +190 -0
- nicefigs-1.0.0/tests/test_scatter.py +84 -0
- nicefigs-1.0.0/tests/test_skill_gap.py +173 -0
- nicefigs-1.0.0/tests/test_spectra.py +134 -0
- nicefigs-1.0.0/tests/test_style.py +162 -0
- nicefigs-1.0.0/tests/test_taylor_hovmoller_profile.py +178 -0
- nicefigs-1.0.0/tests/test_ternary.py +134 -0
- nicefigs-1.0.0/tests/test_text_overlaps.py +61 -0
- nicefigs-1.0.0/tests/test_timeseries.py +164 -0
- nicefigs-1.0.0/tests/test_units.py +140 -0
- nicefigs-1.0.0/tests/test_verification.py +239 -0
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.egg-info/
|
|
5
|
+
.eggs/
|
|
6
|
+
build/
|
|
7
|
+
dist/
|
|
8
|
+
.venv/
|
|
9
|
+
venv/
|
|
10
|
+
|
|
11
|
+
# Tooling caches
|
|
12
|
+
.pytest_cache/
|
|
13
|
+
.ruff_cache/
|
|
14
|
+
.mypy_cache/
|
|
15
|
+
.ipynb_checkpoints/
|
|
16
|
+
|
|
17
|
+
# Test / build artifacts
|
|
18
|
+
tests/baseline_new/
|
|
19
|
+
tests/result_images/
|
|
20
|
+
# mkdocs build output
|
|
21
|
+
site/
|
|
22
|
+
scratch_*.py
|
|
23
|
+
scratch_*/
|
|
24
|
+
|
|
25
|
+
# OS
|
|
26
|
+
.DS_Store
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres
|
|
5
|
+
to [Semantic Versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [1.0.0] - 2026-11-07
|
|
10
|
+
|
|
11
|
+
First public release.
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- House style: `set_theme`, the scoped `style` context manager and the `Theme`
|
|
16
|
+
presets `paper`, `paper-large`, `talk` and `poster`.
|
|
17
|
+
- Physical figure sizing: `figure`, `subplots` and `figure_size` with named
|
|
18
|
+
journal and slide widths; `save` to several formats at once;
|
|
19
|
+
`check_text_overlaps` to find colliding or clipped text.
|
|
20
|
+
- Maps: `map`, `scatter_map`, `binned_map`, `raster_map`, `categorical_map`,
|
|
21
|
+
`tri_map`, `hatch_region`, `from_xarray`, with optional cartopy projections
|
|
22
|
+
and an inset-histogram colorbar.
|
|
23
|
+
- Colour: continuous and categorical palettes (`cmap`, `categorical`,
|
|
24
|
+
`qualitative`, `elevation_cmap`, land-cover palettes), a role palette
|
|
25
|
+
(`ROLES`, `role_color`, `role_style`), artist palettes, ternary and
|
|
26
|
+
bivariate 2D colormaps with legends.
|
|
27
|
+
- Plots: `agreement`, `scatter`, `timeseries`, `lines`, `model_comparison`,
|
|
28
|
+
`taylor`, `scorecard` and `skill_gap`, `pareto`, `caterpillar`, grouped and
|
|
29
|
+
stacked bars, `heatmap`, `image_grid`, `overlay_grid`, `hovmoller`,
|
|
30
|
+
`cross_section`, `profile`, `reliability`, `rank_histogram`,
|
|
31
|
+
`precision_recall`, `spectrum` (eigenvalue decay or cumulative explained
|
|
32
|
+
variance), and the `atlas.component_panel` composite.
|
|
33
|
+
- Layout helpers: `panel_label`, `label_panels`, `colorbar`, `facet`,
|
|
34
|
+
`row_labels`, `col_labels`, `reference_line`, metric and unit labels.
|
|
35
|
+
- Animation: `animate_maps`, `save_animation`, `render_animation`,
|
|
36
|
+
`stitch_frames` (MP4 via ffmpeg, GIF fallback).
|
|
37
|
+
- Deterministic synthetic example data in `nicefigs.data`.
|
|
38
|
+
- One calling convention: plotting helpers take `ax=None` and return `ax` or
|
|
39
|
+
`(ax, extra)`; figure helpers return `(fig, axes[, extra])`; decorators take
|
|
40
|
+
the axes first. One unit-argument scheme and one "which way is better"
|
|
41
|
+
vocabulary, `DIRECTIONS`.
|
|
42
|
+
|
|
43
|
+
[Unreleased]: https://github.com/EarthyScience/nicefigs/compare/v1.0.0...HEAD
|
|
44
|
+
[1.0.0]: https://github.com/EarthyScience/nicefigs/releases/tag/v1.0.0
|
nicefigs-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Vitus Benson
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
nicefigs-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: nicefigs
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Publication-grade, modular matplotlib plotting for geoscience.
|
|
5
|
+
Project-URL: Homepage, https://github.com/EarthyScience/nicefigs
|
|
6
|
+
Project-URL: Documentation, https://earthyscience.github.io/nicefigs
|
|
7
|
+
Project-URL: Repository, https://github.com/EarthyScience/nicefigs
|
|
8
|
+
Project-URL: Issues, https://github.com/EarthyScience/nicefigs/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/EarthyScience/nicefigs/blob/main/CHANGELOG.md
|
|
10
|
+
Author-email: Vitus Benson <vitus.benson@icloud.com>
|
|
11
|
+
License-Expression: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: cartography,colormaps,earth-science,figures,geoscience,maps,matplotlib,publication,visualization
|
|
14
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
15
|
+
Classifier: Framework :: Matplotlib
|
|
16
|
+
Classifier: Intended Audience :: Science/Research
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
|
|
25
|
+
Classifier: Topic :: Scientific/Engineering :: GIS
|
|
26
|
+
Classifier: Topic :: Scientific/Engineering :: Visualization
|
|
27
|
+
Classifier: Typing :: Typed
|
|
28
|
+
Requires-Python: >=3.10
|
|
29
|
+
Requires-Dist: matplotlib>=3.7
|
|
30
|
+
Requires-Dist: numpy>=1.23
|
|
31
|
+
Requires-Dist: pillow>=9.0
|
|
32
|
+
Requires-Dist: scipy>=1.10
|
|
33
|
+
Provides-Extra: all
|
|
34
|
+
Requires-Dist: cartopy>=0.22; extra == 'all'
|
|
35
|
+
Requires-Dist: shapely>=2.0; extra == 'all'
|
|
36
|
+
Requires-Dist: xarray>=2023.1; extra == 'all'
|
|
37
|
+
Provides-Extra: dev
|
|
38
|
+
Requires-Dist: build>=1.0; extra == 'dev'
|
|
39
|
+
Requires-Dist: cartopy>=0.22; extra == 'dev'
|
|
40
|
+
Requires-Dist: pre-commit>=3.5; extra == 'dev'
|
|
41
|
+
Requires-Dist: pytest>=7.0; extra == 'dev'
|
|
42
|
+
Requires-Dist: shapely>=2.0; extra == 'dev'
|
|
43
|
+
Requires-Dist: twine>=5.0; extra == 'dev'
|
|
44
|
+
Requires-Dist: xarray>=2023.1; extra == 'dev'
|
|
45
|
+
Provides-Extra: docs
|
|
46
|
+
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
|
|
47
|
+
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
|
|
48
|
+
Provides-Extra: maps
|
|
49
|
+
Requires-Dist: cartopy>=0.22; extra == 'maps'
|
|
50
|
+
Requires-Dist: shapely>=2.0; extra == 'maps'
|
|
51
|
+
Provides-Extra: xarray
|
|
52
|
+
Requires-Dist: xarray>=2023.1; extra == 'xarray'
|
|
53
|
+
Description-Content-Type: text/markdown
|
|
54
|
+
|
|
55
|
+
<p align="center">
|
|
56
|
+
<picture>
|
|
57
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/logo/nicefigs-lockup-dark.svg">
|
|
58
|
+
<img alt="nicefigs" src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/logo/nicefigs-lockup-light.svg" width="360">
|
|
59
|
+
</picture>
|
|
60
|
+
</p>
|
|
61
|
+
|
|
62
|
+
<p align="center"><b>Publication-grade, modular matplotlib plotting for geoscience.</b></p>
|
|
63
|
+
|
|
64
|
+
<p align="center">
|
|
65
|
+
<a href="https://pypi.org/project/nicefigs/"><img src="https://img.shields.io/pypi/v/nicefigs.svg" alt="PyPI"></a>
|
|
66
|
+
<a href="https://pypi.org/project/nicefigs/"><img src="https://img.shields.io/pypi/pyversions/nicefigs.svg" alt="Python versions"></a>
|
|
67
|
+
<a href="https://github.com/EarthyScience/nicefigs/actions/workflows/ci.yml"><img src="https://github.com/EarthyScience/nicefigs/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
68
|
+
<a href="https://earthyscience.github.io/nicefigs"><img src="https://img.shields.io/badge/docs-mkdocs-teal.svg" alt="Docs"></a>
|
|
69
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
|
|
70
|
+
</p>
|
|
71
|
+
|
|
72
|
+
`nicefigs` is a thin, composable layer on top of matplotlib for figures in
|
|
73
|
+
geoscience papers. It provides one consistent house style, **physical figure
|
|
74
|
+
sizing** that keeps fonts at their point sizes across every panel, and
|
|
75
|
+
ready-made plots for the figures geoscientists draw most: global and regional
|
|
76
|
+
maps, agreement plots, model comparisons, scorecards, time series, ternary
|
|
77
|
+
compositions, verification diagrams and map animations.
|
|
78
|
+
|
|
79
|
+
Every helper takes an existing `ax` where that makes sense, so nicefigs pieces
|
|
80
|
+
drop into your own matplotlib layouts.
|
|
81
|
+
|
|
82
|
+
## Gallery
|
|
83
|
+
|
|
84
|
+
<table>
|
|
85
|
+
<tr>
|
|
86
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/01_global_map.png" alt="Global map with an inset-histogram colorbar"></td>
|
|
87
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/14_agreement.png" alt="Agreement plot with KDE density, 1:1 line, fit and metrics"></td>
|
|
88
|
+
</tr>
|
|
89
|
+
<tr>
|
|
90
|
+
<td><img src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/05_ternary_map.png" alt="Ternary-coloured map of a three-part composition"></td>
|
|
91
|
+
<td><img src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/17_model_comparison.png" alt="Model-comparison violins per metric"></td>
|
|
92
|
+
</tr>
|
|
93
|
+
<tr>
|
|
94
|
+
<td><img src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/20_scorecard.png" alt="Coloured scorecard table"></td>
|
|
95
|
+
<td><img src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/23_composite_figure.png" alt="Composite figure: map, time series and agreement panel"></td>
|
|
96
|
+
</tr>
|
|
97
|
+
</table>
|
|
98
|
+
|
|
99
|
+
The [gallery](https://earthyscience.github.io/nicefigs/gallery/) shows every
|
|
100
|
+
plot type with the code that drew it.
|
|
101
|
+
|
|
102
|
+
## Install
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
pip install nicefigs # core: matplotlib, numpy, scipy, pillow
|
|
106
|
+
pip install "nicefigs[maps]" # + cartopy map projections and ocean clipping
|
|
107
|
+
pip install "nicefigs[all]" # + cartopy and xarray
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Python 3.10 or newer. Without cartopy, maps fall back to a plain
|
|
111
|
+
equirectangular axes.
|
|
112
|
+
|
|
113
|
+
## Quick start
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
import nicefigs as nf
|
|
117
|
+
from nicefigs import data # deterministic synthetic example data
|
|
118
|
+
|
|
119
|
+
nf.set_theme("paper")
|
|
120
|
+
|
|
121
|
+
# A single-column figure; the height is solved from the aspect.
|
|
122
|
+
fig, ax = nf.subplots(width="single", aspect=0.8)
|
|
123
|
+
|
|
124
|
+
obs, pred = data.xy_agreement()
|
|
125
|
+
nf.agreement(obs, pred, ax=ax, units="mm d⁻¹") # KDE density, 1:1 line, fit, metrics
|
|
126
|
+
nf.save(fig, "agreement", formats=("pdf", "png"))
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
A global map with an inset-histogram colorbar:
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
import nicefigs as nf
|
|
133
|
+
from nicefigs import data
|
|
134
|
+
|
|
135
|
+
lon, lat, temp = data.global_points(field="temperature")
|
|
136
|
+
fig, ax, mappable = nf.map(lon, lat, temp, cmap="RdYlBu_r", colorbar_label="T [°C]")
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## Features
|
|
140
|
+
|
|
141
|
+
- **One house style.** `set_theme("paper" | "paper-large" | "talk" | "poster")`
|
|
142
|
+
globally, or `with nf.style(...):` around existing matplotlib code.
|
|
143
|
+
- **Physical figure sizing.** `width="single"`, `"double"`, `"slide"`, …
|
|
144
|
+
plus an aspect; the free dimension is solved and fonts stay at their point sizes.
|
|
145
|
+
- **Maps.** Robinson by default with Antarctica cropped, an inset histogram that
|
|
146
|
+
doubles as the colorbar, ocean clipping, point, binned, raster, categorical
|
|
147
|
+
and triangulated rendering, and regional extents.
|
|
148
|
+
- **Colour.** Geoscience colormaps and diverging norms, land-cover palettes
|
|
149
|
+
(ESA WorldCover, ESRI, MODIS), a role palette for comparison figures, artist
|
|
150
|
+
palettes, ternary and bivariate 2D colormaps with matching legends.
|
|
151
|
+
- **Evaluation plots.** Agreement plots, model-comparison violins, Taylor
|
|
152
|
+
diagrams, scorecards with a skill-gap colouring, Pareto frontiers,
|
|
153
|
+
caterpillar plots, reliability diagrams, rank histograms and
|
|
154
|
+
precision–recall curves.
|
|
155
|
+
- **Structure in space and time.** Time series with ensemble bands,
|
|
156
|
+
Hovmöller diagrams, cross-sections and vertical profiles, map animations to
|
|
157
|
+
MP4 or GIF.
|
|
158
|
+
- **Layout helpers.** Panel labels, tight shared colorbars, facets, row and
|
|
159
|
+
column labels, and `check_text_overlaps` to catch colliding text before
|
|
160
|
+
submission.
|
|
161
|
+
|
|
162
|
+
## Documentation
|
|
163
|
+
|
|
164
|
+
The full documentation, with a user guide and the API reference, is at
|
|
165
|
+
<https://earthyscience.github.io/nicefigs>.
|
|
166
|
+
|
|
167
|
+
## Contributing
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
git clone https://github.com/EarthyScience/nicefigs
|
|
171
|
+
cd nicefigs
|
|
172
|
+
uv venv && uv pip install -e ".[dev,docs]" && uv run pre-commit install
|
|
173
|
+
make check # pre-commit + tests, exactly what CI runs
|
|
174
|
+
make gallery # re-render docs/gallery and the README images
|
|
175
|
+
make docs-check # run every README/docs code example against its shown output
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
See [RELEASING.md](RELEASING.md) for how a release is cut.
|
|
179
|
+
|
|
180
|
+
## License
|
|
181
|
+
|
|
182
|
+
MIT — see [LICENSE](LICENSE).
|
nicefigs-1.0.0/README.md
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/logo/nicefigs-lockup-dark.svg">
|
|
4
|
+
<img alt="nicefigs" src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/logo/nicefigs-lockup-light.svg" width="360">
|
|
5
|
+
</picture>
|
|
6
|
+
</p>
|
|
7
|
+
|
|
8
|
+
<p align="center"><b>Publication-grade, modular matplotlib plotting for geoscience.</b></p>
|
|
9
|
+
|
|
10
|
+
<p align="center">
|
|
11
|
+
<a href="https://pypi.org/project/nicefigs/"><img src="https://img.shields.io/pypi/v/nicefigs.svg" alt="PyPI"></a>
|
|
12
|
+
<a href="https://pypi.org/project/nicefigs/"><img src="https://img.shields.io/pypi/pyversions/nicefigs.svg" alt="Python versions"></a>
|
|
13
|
+
<a href="https://github.com/EarthyScience/nicefigs/actions/workflows/ci.yml"><img src="https://github.com/EarthyScience/nicefigs/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
14
|
+
<a href="https://earthyscience.github.io/nicefigs"><img src="https://img.shields.io/badge/docs-mkdocs-teal.svg" alt="Docs"></a>
|
|
15
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
|
|
16
|
+
</p>
|
|
17
|
+
|
|
18
|
+
`nicefigs` is a thin, composable layer on top of matplotlib for figures in
|
|
19
|
+
geoscience papers. It provides one consistent house style, **physical figure
|
|
20
|
+
sizing** that keeps fonts at their point sizes across every panel, and
|
|
21
|
+
ready-made plots for the figures geoscientists draw most: global and regional
|
|
22
|
+
maps, agreement plots, model comparisons, scorecards, time series, ternary
|
|
23
|
+
compositions, verification diagrams and map animations.
|
|
24
|
+
|
|
25
|
+
Every helper takes an existing `ax` where that makes sense, so nicefigs pieces
|
|
26
|
+
drop into your own matplotlib layouts.
|
|
27
|
+
|
|
28
|
+
## Gallery
|
|
29
|
+
|
|
30
|
+
<table>
|
|
31
|
+
<tr>
|
|
32
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/01_global_map.png" alt="Global map with an inset-histogram colorbar"></td>
|
|
33
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/14_agreement.png" alt="Agreement plot with KDE density, 1:1 line, fit and metrics"></td>
|
|
34
|
+
</tr>
|
|
35
|
+
<tr>
|
|
36
|
+
<td><img src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/05_ternary_map.png" alt="Ternary-coloured map of a three-part composition"></td>
|
|
37
|
+
<td><img src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/17_model_comparison.png" alt="Model-comparison violins per metric"></td>
|
|
38
|
+
</tr>
|
|
39
|
+
<tr>
|
|
40
|
+
<td><img src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/20_scorecard.png" alt="Coloured scorecard table"></td>
|
|
41
|
+
<td><img src="https://raw.githubusercontent.com/EarthyScience/nicefigs/main/docs/assets/23_composite_figure.png" alt="Composite figure: map, time series and agreement panel"></td>
|
|
42
|
+
</tr>
|
|
43
|
+
</table>
|
|
44
|
+
|
|
45
|
+
The [gallery](https://earthyscience.github.io/nicefigs/gallery/) shows every
|
|
46
|
+
plot type with the code that drew it.
|
|
47
|
+
|
|
48
|
+
## Install
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
pip install nicefigs # core: matplotlib, numpy, scipy, pillow
|
|
52
|
+
pip install "nicefigs[maps]" # + cartopy map projections and ocean clipping
|
|
53
|
+
pip install "nicefigs[all]" # + cartopy and xarray
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Python 3.10 or newer. Without cartopy, maps fall back to a plain
|
|
57
|
+
equirectangular axes.
|
|
58
|
+
|
|
59
|
+
## Quick start
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
import nicefigs as nf
|
|
63
|
+
from nicefigs import data # deterministic synthetic example data
|
|
64
|
+
|
|
65
|
+
nf.set_theme("paper")
|
|
66
|
+
|
|
67
|
+
# A single-column figure; the height is solved from the aspect.
|
|
68
|
+
fig, ax = nf.subplots(width="single", aspect=0.8)
|
|
69
|
+
|
|
70
|
+
obs, pred = data.xy_agreement()
|
|
71
|
+
nf.agreement(obs, pred, ax=ax, units="mm d⁻¹") # KDE density, 1:1 line, fit, metrics
|
|
72
|
+
nf.save(fig, "agreement", formats=("pdf", "png"))
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
A global map with an inset-histogram colorbar:
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
import nicefigs as nf
|
|
79
|
+
from nicefigs import data
|
|
80
|
+
|
|
81
|
+
lon, lat, temp = data.global_points(field="temperature")
|
|
82
|
+
fig, ax, mappable = nf.map(lon, lat, temp, cmap="RdYlBu_r", colorbar_label="T [°C]")
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Features
|
|
86
|
+
|
|
87
|
+
- **One house style.** `set_theme("paper" | "paper-large" | "talk" | "poster")`
|
|
88
|
+
globally, or `with nf.style(...):` around existing matplotlib code.
|
|
89
|
+
- **Physical figure sizing.** `width="single"`, `"double"`, `"slide"`, …
|
|
90
|
+
plus an aspect; the free dimension is solved and fonts stay at their point sizes.
|
|
91
|
+
- **Maps.** Robinson by default with Antarctica cropped, an inset histogram that
|
|
92
|
+
doubles as the colorbar, ocean clipping, point, binned, raster, categorical
|
|
93
|
+
and triangulated rendering, and regional extents.
|
|
94
|
+
- **Colour.** Geoscience colormaps and diverging norms, land-cover palettes
|
|
95
|
+
(ESA WorldCover, ESRI, MODIS), a role palette for comparison figures, artist
|
|
96
|
+
palettes, ternary and bivariate 2D colormaps with matching legends.
|
|
97
|
+
- **Evaluation plots.** Agreement plots, model-comparison violins, Taylor
|
|
98
|
+
diagrams, scorecards with a skill-gap colouring, Pareto frontiers,
|
|
99
|
+
caterpillar plots, reliability diagrams, rank histograms and
|
|
100
|
+
precision–recall curves.
|
|
101
|
+
- **Structure in space and time.** Time series with ensemble bands,
|
|
102
|
+
Hovmöller diagrams, cross-sections and vertical profiles, map animations to
|
|
103
|
+
MP4 or GIF.
|
|
104
|
+
- **Layout helpers.** Panel labels, tight shared colorbars, facets, row and
|
|
105
|
+
column labels, and `check_text_overlaps` to catch colliding text before
|
|
106
|
+
submission.
|
|
107
|
+
|
|
108
|
+
## Documentation
|
|
109
|
+
|
|
110
|
+
The full documentation, with a user guide and the API reference, is at
|
|
111
|
+
<https://earthyscience.github.io/nicefigs>.
|
|
112
|
+
|
|
113
|
+
## Contributing
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
git clone https://github.com/EarthyScience/nicefigs
|
|
117
|
+
cd nicefigs
|
|
118
|
+
uv venv && uv pip install -e ".[dev,docs]" && uv run pre-commit install
|
|
119
|
+
make check # pre-commit + tests, exactly what CI runs
|
|
120
|
+
make gallery # re-render docs/gallery and the README images
|
|
121
|
+
make docs-check # run every README/docs code example against its shown output
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
See [RELEASING.md](RELEASING.md) for how a release is cut.
|
|
125
|
+
|
|
126
|
+
## License
|
|
127
|
+
|
|
128
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "nicefigs"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Publication-grade, modular matplotlib plotting for geoscience."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "Vitus Benson", email = "vitus.benson@icloud.com" }]
|
|
14
|
+
keywords = [
|
|
15
|
+
"matplotlib", "visualization", "geoscience", "earth-science", "cartography",
|
|
16
|
+
"publication", "maps", "colormaps", "figures",
|
|
17
|
+
]
|
|
18
|
+
classifiers = [
|
|
19
|
+
"Development Status :: 5 - Production/Stable",
|
|
20
|
+
"Intended Audience :: Science/Research",
|
|
21
|
+
"Operating System :: OS Independent",
|
|
22
|
+
"Programming Language :: Python :: 3",
|
|
23
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
24
|
+
"Programming Language :: Python :: 3.10",
|
|
25
|
+
"Programming Language :: Python :: 3.11",
|
|
26
|
+
"Programming Language :: Python :: 3.12",
|
|
27
|
+
"Programming Language :: Python :: 3.13",
|
|
28
|
+
"Framework :: Matplotlib",
|
|
29
|
+
"Topic :: Scientific/Engineering :: Atmospheric Science",
|
|
30
|
+
"Topic :: Scientific/Engineering :: GIS",
|
|
31
|
+
"Topic :: Scientific/Engineering :: Visualization",
|
|
32
|
+
"Typing :: Typed",
|
|
33
|
+
]
|
|
34
|
+
dependencies = [
|
|
35
|
+
"matplotlib>=3.7",
|
|
36
|
+
"numpy>=1.23",
|
|
37
|
+
"pillow>=9.0",
|
|
38
|
+
"scipy>=1.10",
|
|
39
|
+
]
|
|
40
|
+
|
|
41
|
+
[project.optional-dependencies]
|
|
42
|
+
maps = [
|
|
43
|
+
"cartopy>=0.22",
|
|
44
|
+
"shapely>=2.0",
|
|
45
|
+
]
|
|
46
|
+
xarray = [
|
|
47
|
+
"xarray>=2023.1",
|
|
48
|
+
]
|
|
49
|
+
all = [
|
|
50
|
+
"nicefigs[maps,xarray]",
|
|
51
|
+
]
|
|
52
|
+
docs = [
|
|
53
|
+
"mkdocs-material>=9.5",
|
|
54
|
+
"mkdocstrings[python]>=0.24",
|
|
55
|
+
]
|
|
56
|
+
dev = [
|
|
57
|
+
"nicefigs[maps,xarray]",
|
|
58
|
+
"pytest>=7.0",
|
|
59
|
+
"pre-commit>=3.5",
|
|
60
|
+
"build>=1.0",
|
|
61
|
+
"twine>=5.0",
|
|
62
|
+
]
|
|
63
|
+
|
|
64
|
+
[project.urls]
|
|
65
|
+
Homepage = "https://github.com/EarthyScience/nicefigs"
|
|
66
|
+
Documentation = "https://earthyscience.github.io/nicefigs"
|
|
67
|
+
Repository = "https://github.com/EarthyScience/nicefigs"
|
|
68
|
+
Issues = "https://github.com/EarthyScience/nicefigs/issues"
|
|
69
|
+
Changelog = "https://github.com/EarthyScience/nicefigs/blob/main/CHANGELOG.md"
|
|
70
|
+
|
|
71
|
+
[tool.hatch.version]
|
|
72
|
+
path = "src/nicefigs/__init__.py"
|
|
73
|
+
|
|
74
|
+
[tool.hatch.build.targets.wheel]
|
|
75
|
+
packages = ["src/nicefigs"]
|
|
76
|
+
|
|
77
|
+
[tool.hatch.build.targets.sdist]
|
|
78
|
+
include = [
|
|
79
|
+
"/src/nicefigs",
|
|
80
|
+
"/tests",
|
|
81
|
+
"/README.md",
|
|
82
|
+
"/CHANGELOG.md",
|
|
83
|
+
"/LICENSE",
|
|
84
|
+
]
|
|
85
|
+
|
|
86
|
+
[tool.ruff]
|
|
87
|
+
line-length = 110
|
|
88
|
+
target-version = "py310"
|
|
89
|
+
|
|
90
|
+
[tool.ruff.lint]
|
|
91
|
+
select = ["E", "F", "I", "UP", "B", "W"]
|
|
92
|
+
ignore = ["E501", "B008", "B905"]
|
|
93
|
+
|
|
94
|
+
[tool.pytest.ini_options]
|
|
95
|
+
testpaths = ["tests"]
|
|
96
|
+
filterwarnings = ["ignore::DeprecationWarning"]
|