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.
Files changed (78) hide show
  1. nicefigs-1.0.0/.gitignore +26 -0
  2. nicefigs-1.0.0/CHANGELOG.md +44 -0
  3. nicefigs-1.0.0/LICENSE +21 -0
  4. nicefigs-1.0.0/PKG-INFO +182 -0
  5. nicefigs-1.0.0/README.md +128 -0
  6. nicefigs-1.0.0/pyproject.toml +96 -0
  7. nicefigs-1.0.0/src/nicefigs/__init__.py +259 -0
  8. nicefigs-1.0.0/src/nicefigs/animation.py +327 -0
  9. nicefigs-1.0.0/src/nicefigs/artists.py +285 -0
  10. nicefigs-1.0.0/src/nicefigs/atlas.py +220 -0
  11. nicefigs-1.0.0/src/nicefigs/bars.py +180 -0
  12. nicefigs-1.0.0/src/nicefigs/colorbars.py +195 -0
  13. nicefigs-1.0.0/src/nicefigs/colormaps2d.py +329 -0
  14. nicefigs-1.0.0/src/nicefigs/comparison.py +222 -0
  15. nicefigs-1.0.0/src/nicefigs/data.py +581 -0
  16. nicefigs-1.0.0/src/nicefigs/figure.py +302 -0
  17. nicefigs-1.0.0/src/nicefigs/hovmoller.py +254 -0
  18. nicefigs-1.0.0/src/nicefigs/images.py +440 -0
  19. nicefigs-1.0.0/src/nicefigs/kde.py +187 -0
  20. nicefigs-1.0.0/src/nicefigs/lines.py +138 -0
  21. nicefigs-1.0.0/src/nicefigs/maps.py +1034 -0
  22. nicefigs-1.0.0/src/nicefigs/palettes.py +579 -0
  23. nicefigs-1.0.0/src/nicefigs/panels.py +503 -0
  24. nicefigs-1.0.0/src/nicefigs/pareto.py +247 -0
  25. nicefigs-1.0.0/src/nicefigs/py.typed +0 -0
  26. nicefigs-1.0.0/src/nicefigs/ranking.py +252 -0
  27. nicefigs-1.0.0/src/nicefigs/scatter.py +224 -0
  28. nicefigs-1.0.0/src/nicefigs/sections.py +335 -0
  29. nicefigs-1.0.0/src/nicefigs/spectra.py +187 -0
  30. nicefigs-1.0.0/src/nicefigs/style.py +324 -0
  31. nicefigs-1.0.0/src/nicefigs/tables.py +330 -0
  32. nicefigs-1.0.0/src/nicefigs/taylor.py +212 -0
  33. nicefigs-1.0.0/src/nicefigs/ternary.py +364 -0
  34. nicefigs-1.0.0/src/nicefigs/timeseries.py +262 -0
  35. nicefigs-1.0.0/src/nicefigs/units.py +219 -0
  36. nicefigs-1.0.0/src/nicefigs/verification.py +381 -0
  37. nicefigs-1.0.0/tests/conftest.py +25 -0
  38. nicefigs-1.0.0/tests/test_agreement.py +120 -0
  39. nicefigs-1.0.0/tests/test_animation.py +67 -0
  40. nicefigs-1.0.0/tests/test_api.py +71 -0
  41. nicefigs-1.0.0/tests/test_api_bars.py +40 -0
  42. nicefigs-1.0.0/tests/test_api_comparison.py +12 -0
  43. nicefigs-1.0.0/tests/test_api_data.py +72 -0
  44. nicefigs-1.0.0/tests/test_api_lines.py +18 -0
  45. nicefigs-1.0.0/tests/test_api_maps_images.py +116 -0
  46. nicefigs-1.0.0/tests/test_api_panels.py +73 -0
  47. nicefigs-1.0.0/tests/test_api_pareto.py +41 -0
  48. nicefigs-1.0.0/tests/test_api_ranking.py +19 -0
  49. nicefigs-1.0.0/tests/test_api_scatter.py +17 -0
  50. nicefigs-1.0.0/tests/test_api_sections.py +48 -0
  51. nicefigs-1.0.0/tests/test_api_taylor.py +26 -0
  52. nicefigs-1.0.0/tests/test_api_units.py +31 -0
  53. nicefigs-1.0.0/tests/test_artists.py +89 -0
  54. nicefigs-1.0.0/tests/test_atlas.py +121 -0
  55. nicefigs-1.0.0/tests/test_categorical_map.py +518 -0
  56. nicefigs-1.0.0/tests/test_colorbars.py +92 -0
  57. nicefigs-1.0.0/tests/test_comparison.py +79 -0
  58. nicefigs-1.0.0/tests/test_extensions.py +105 -0
  59. nicefigs-1.0.0/tests/test_figure.py +159 -0
  60. nicefigs-1.0.0/tests/test_figure_helpers.py +100 -0
  61. nicefigs-1.0.0/tests/test_gridded_maps.py +92 -0
  62. nicefigs-1.0.0/tests/test_images.py +128 -0
  63. nicefigs-1.0.0/tests/test_maps.py +186 -0
  64. nicefigs-1.0.0/tests/test_palettes.py +230 -0
  65. nicefigs-1.0.0/tests/test_panels.py +332 -0
  66. nicefigs-1.0.0/tests/test_plots.py +303 -0
  67. nicefigs-1.0.0/tests/test_render_animation.py +61 -0
  68. nicefigs-1.0.0/tests/test_roles.py +190 -0
  69. nicefigs-1.0.0/tests/test_scatter.py +84 -0
  70. nicefigs-1.0.0/tests/test_skill_gap.py +173 -0
  71. nicefigs-1.0.0/tests/test_spectra.py +134 -0
  72. nicefigs-1.0.0/tests/test_style.py +162 -0
  73. nicefigs-1.0.0/tests/test_taylor_hovmoller_profile.py +178 -0
  74. nicefigs-1.0.0/tests/test_ternary.py +134 -0
  75. nicefigs-1.0.0/tests/test_text_overlaps.py +61 -0
  76. nicefigs-1.0.0/tests/test_timeseries.py +164 -0
  77. nicefigs-1.0.0/tests/test_units.py +140 -0
  78. 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.
@@ -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).
@@ -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"]