eofigs 0.1.0__tar.gz

eofigs-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Tests and coverage
+.pytest_cache/
+.coverage
+coverage.xml
+coverage.json
+htmlcov/
+result_images/
+
+# Tools
+.ruff_cache/
+.mypy_cache/
+.ipynb_checkpoints/
+
+# Docs
+site/
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini

eofigs-0.1.0/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
+uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-08
+
+First release: journal styles and one-call export, the figure check, figure sets, the
+variable library, print-size raster handling and trend statistics, with four recipe
+figures: study area map, trend map, event composite and accuracy scatter.
+
+### Added
+
+- `study_area_map`: study area outline over a grey hillshade with semi-transparent
+  elevation colours (light `lapaz` under an overlay, `batlow` otherwise), a single-colour
+  overlay (for example tree cover) that lets the hillshade show through, labelled points,
+  graticule (at most four labels per side), north arrow to true north above or beside the
+  scale bar, legend and locator inset. The figure height follows the study area's shape up
+  to 75 % of the journal maximum; inset, legend and furniture go to the emptiest part of
+  the map, clear of the outline, points and labels, or below or beside the map; point
+  labels avoid each other and the outline. `subfigure=` draws the map as one panel of a
+  larger figure.
+- `add_north_arrow` (rotated by the grid convergence), `add_scale_bar` (true distance at
+  the map centre, round lengths) and `add_inset` (Natural Earth countries, default de facto
+  boundaries bundled; Natural Earth worldviews downloaded on request with a pinned version
+  and checksum, and cached).
+- `trend_map`: per-pixel trends (Theil–Sen, Mann–Kendall, computed at full resolution and
+  then reduced to print size; p-values are never averaged) with zero-centred colours,
+  symmetric limits at the rounded 98th percentile, significance dots or hatching where at
+  least half of the pixels in each 1.6 mm cell are significant, hatched grey for
+  non-vegetated and no-data pixels, an optional latitude profile from the full-resolution
+  slope, and a ready caption sentence with the colour limits, the clipped share and the
+  significance rule (`fig.eofigs_layout["caption"]`).
+- `event_composite`: anomaly maps before, during and after a set of events (date pairs or a
+  boolean series), averaged over the events, with a composite series. Events whose window
+  runs past the record or overlaps another are dropped with a warning; a per-pixel linear
+  trend is removed first; anomalies are taken from a monthly climatology of the non-event
+  steps at full resolution (or z-scores); significance by a t-test (or Wilcoxon test) across
+  events, marked as in `trend_map`; shared colour limits and a ready caption sentence,
+  which notes the low power of a test with fewer than 5 events. The series shades the event
+  period, darker while all events are ongoing and lighter while only some are.
+- `accuracy_scatter`: observed against predicted values (predicted on the x axis and the
+  least-squares line of observed on predicted by default, after Piñeiro et al. 2008; or
+  the reverse, or a reduced major axis line) with the 1:1 line, a statistics box (R² as the
+  squared Pearson correlation, RMSE, rRMSE, NMAD after Höhle and Höhle 2009, MAE, bias,
+  rBias, NSE, slope, intercept, n)
+  with units from the variable library, square axes with shared ticks, groups in Okabe-Ito
+  colours with distinct markers, density colours above 1 000 pairs (rasterised in vector
+  files), `ax=` for multi-panel figures and a ready caption sentence.
+- Swat ICESat-2 ATL08 terrain heights 2019–2024 (a slope-independent quality rule and a
+  random sample of 25 000 segments), converted to EGM2008 heights and paired with the
+  Copernicus DEM (built by `docs/scripts/build_swat_icesat2.py`); gallery entries for the
+  ICESat-2 comparison, with the DEM error by slope class, and for synthetic calibration and
+  validation plots.
+- Swat hot-dry events 2001–2021 from TerraClimate (built by `docs/scripts/build_swat_events.py`)
+  and a monthly 1 km NDVI series from MODIS MOD13A1 in `docs/data/swat/`; gallery entries
+  for the Swat event composite and a synthetic composite with eight events.
+- Swat growing-season NDVI 2001–2024 (MODIS MOD13A1, 500 m) in `docs/data/swat/`, built by
+  `docs/scripts/build_swat_ndvi.py`; gallery entries for the Swat trend map with and
+  without the latitude profile.
+- `check_figure` checks that single-colour overlays stay distinguishable from the colour
+  maps beneath them.
+- `fit_raster` reads http(s) and s3 URLs.
+- Swat valley sample data in `docs/data/swat/` (not in the package) with
+  `DATA_LICENSES.md`; gallery entries for the Swat study area map and a house style.
+- `eofigs.palettes`: Okabe-Ito, muted, slate and terracotta-slate palettes and neutral
+  colours; colour maps `"eofigs.slate"` and `"eofigs.terra_slate"` (and `_r`).
+- `cvd_preview`: one image showing a figure in normal vision, protan, deutan and tritan
+  simulation and greyscale.
+- `tidy_axes`: four or five ticks at round values on axes and colour bars.
+  `set_style(max_ticks=5)` sets a house tick limit, which `check_figure` then checks.
+- `set_style(panel_titles=False)`: recipes leave out panel titles and name the panels in
+  their caption sentence instead.
+- `check_figure` accepts metric-compatible free fonts (Liberation Sans, Arimo, TeX Gyre
+  Heros, Liberation Serif, Tinos, TeX Gyre Termes) in place of the journal's fonts, with a
+  note.
+- `save_figure` rasterises dense layers (mesh plots, collections with more than 2 000
+  elements) inside vector files; `rasterize_dense=False` keeps them vector.
+- Styles use a true minus sign.
+- Example gallery built from `examples/*.py` when the documentation is built, with the
+  check report and downloads for each figure.
+
+- `set_style` and the `style` context manager: journal presets for Elsevier, Springer,
+  MDPI, Wiley, Frontiers and Taylor & Francis (plus `custom`), font fallback to
+  metric-compatible free fonts with a warning, mathtext matched to the text font,
+  Okabe-Ito colour cycle, TrueType font embedding.
+- `new_figure`: figures sized in millimetres from named column widths.
+- `label_panels`: bold (a), (b), ... panel labels in several formats.
+- `save_figure`: one call writes the journal's formats (vector PDF plus TIFF/PNG/EPS) at
+  600 dpi or an exact pixel width, without trimming, with reproducible PDFs.
+- `check_figure`: size, resolution, smallest font, fonts in use or embedded, colour-blind
+  safety of categorical colours (CIEDE2000 with simulated colour-vision deficiency) and
+  colour-map lightness, for live figures and exported files.
+- Journal presets in `journals.json` with source links and check dates; documentation pages
+  for style and export, and for the presets.
+- `art=` option ("combination", "line", "halftone") for `save_figure` and `check_figure`:
+  line art is written and checked at the publisher's line-art resolution (for example
+  1000 dpi for Elsevier, 1200 dpi for Springer).
+- Variable library (`variable`, `register_variable`, `Variable`): 22 Earth observation
+  variables in `variables.json` with long names, symbols, mathtext units, cmcrameri colour
+  maps, default ranges and zero-centred anomaly and trend maps (terracotta–slate for all
+  vegetation variables: indices, productivity and structure; `vik` with the physically
+  sensible direction for water, temperature, terrain and burn severity); recognises xarray variables
+  from CF attributes and writes CF units in mathtext.
+- `fit_raster`: reduces GeoTIFFs, COGs and xarray rasters to the printed resolution (mean,
+  mode or mask fraction), ignores nodata, sets sparse pixels to NaN (`min_valid`), keeps the
+  CRS, stays lazy with dask, and reads files at the output size (integer files are averaged
+  exactly by eofigs).
+- `trend`: Theil–Sen slope and Mann–Kendall test (tie- and continuity-corrected) per pixel,
+  against real dates, with `min_valid`, a memory budget for any series length, and dask
+  support; compared with `scipy.stats.theilslopes` in the tests. The slope is labelled as a
+  trend of the input variable, and the intercept records its `reference_time`.
+- `figure_set` and `FigureSet`: manuscript figures saved as `Fig01_<name>` / `FigS01_<name>`
+  in the journal's formats, reordering with file renaming, and `figures_manifest.csv` with
+  sizes, resolution, check results and captions; resumes from the manifest.
+- `check_figure` treats single-colour contour lines as lines, not as colour maps.
+- Project structure, packaging, test and documentation workflows, with a check of the
+  built wheel and source distribution and an install test on Linux, Windows and macOS.
+- Container image workflow for GitHub Container Registry (development `dev` tag); release tags build
+  a multi-architecture image (amd64 and arm64).
+- Code of conduct (Contributor Covenant 2.1), issue templates, pull request template.
+- Citation file validation and coverage total in continuous integration.
+
+[Unreleased]: https://github.com/kmkamilkhel/eofigs/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/kmkamilkhel/eofigs/releases/tag/v0.1.0

eofigs-0.1.0/CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using these metadata."
+title: "eofigs: analysis-aware, publication-ready figures for Earth observation research"
+type: software
+version: 0.1.0
+date-released: "2026-11-08"
+abstract: >-
+  eofigs turns Earth observation analysis outputs (rasters, time series and validation
+  pairs) into journal-ready figures that know the analysis, the variable and the printed
+  size. It provides journal presets with one-call export to vector PDF and 600 dpi raster
+  files, a figure check (size, resolution, smallest font, font embedding, colour-blind
+  safety), a variable library with fixed colour maps and units, print-size raster handling,
+  Theil-Sen and Mann-Kendall trend statistics, and recipe figures for study area maps,
+  trend maps with significance, event composites and accuracy scatters.
+authors:
+  - family-names: Mehmood
+    given-names: Kaleem
+    orcid: "https://orcid.org/0000-0002-7996-8684"
+    affiliation: "Institute of Forest Sciences, University of Swat, Khyber Pakhtunkhwa, Pakistan"
+repository-code: "https://github.com/kmkamilkhel/eofigs"
+url: "https://kmkamilkhel.github.io/eofigs/"
+license: MIT
+keywords:
+  - remote sensing
+  - earth observation
+  - geospatial
+  - cartography
+  - scientific figures
+  - python

eofigs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaleem Mehmood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eofigs-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: eofigs
+Version: 0.1.0
+Summary: Analysis-aware, publication-ready figures for Earth observation research.
+Project-URL: Homepage, https://kmkamilkhel.github.io/eofigs/
+Project-URL: Documentation, https://kmkamilkhel.github.io/eofigs/
+Project-URL: Source, https://github.com/kmkamilkhel/eofigs
+Project-URL: Issues, https://github.com/kmkamilkhel/eofigs/issues
+Project-URL: Changelog, https://github.com/kmkamilkhel/eofigs/blob/main/CHANGELOG.md
+Author-email: Kaleem Mehmood <kaleemmehmood73@gmail.com>
+Maintainer-email: Kaleem Mehmood <kaleemmehmood73@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cartography,earth observation,geospatial,maps,matplotlib,remote sensing,scientific figures
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cartopy>=0.23
+Requires-Dist: cmcrameri>=1.9
+Requires-Dist: geopandas>=1.0
+Requires-Dist: matplotlib-scalebar>=0.8
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Dist: pyproj>=3.6
+Requires-Dist: rioxarray>=0.15
+Requires-Dist: scipy>=1.11
+Requires-Dist: shapely>=2.0
+Requires-Dist: xarray>=2024.6
+Provides-Extra: dask
+Requires-Dist: dask[array]>=2024.6; extra == 'dask'
+Requires-Dist: tqdm>=4.66; extra == 'dask'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: dask[array]>=2024.6; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'dev'
+Requires-Dist: pre-commit>=4; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest-mpl>=0.17; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.17; extra == 'dev'
+Requires-Dist: tqdm>=4.66; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: dask[array]>=2024.6; extra == 'test'
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest-mpl>=0.17; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Provides-Extra: xee
+Requires-Dist: earthengine-api>=1.0; extra == 'xee'
+Requires-Dist: xee>=0.1; extra == 'xee'
+Description-Content-Type: text/markdown
+
+# eofigs
+
+[![Tests](https://github.com/kmkamilkhel/eofigs/actions/workflows/tests.yml/badge.svg)](https://github.com/kmkamilkhel/eofigs/actions/workflows/tests.yml)
+[![Docs](https://github.com/kmkamilkhel/eofigs/actions/workflows/docs.yml/badge.svg)](https://kmkamilkhel.github.io/eofigs/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Analysis-aware, publication-ready figures for Earth observation research.
+
+eofigs turns Earth observation analysis outputs (rasters, time series, validation pairs) into
+journal-ready figures that know the analysis, the variable and the printed size:
+
+- **Recipe figures** for common analyses: trend with significance, event composites, and later
+  recovery, burn severity, disturbance and divergence.
+- **A variable library** with fixed colour maps, symbols and units, so NDVI, LST or GPP look the
+  same in every figure, and their anomalies and trends get zero-centred diverging colours.
+- **Print-size rendering**: rasters are read and reduced to the pixels the printed figure needs,
+  from its width in mm and its dpi, keeping memory use and PDF size small.
+- **Journal presets and one-call export** to vector PDF plus 600 dpi PNG or TIFF, with a check
+  of size, resolution, smallest font, font embedding and colour-blind safety.
+
+## Gallery
+
+<table>
+<tr>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/study_area_swat/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/study_area_swat.png" alt="Study area map: Swat valley"></a><br><b>Study area map: Swat valley</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/study_area_single_column/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/study_area_single_column.png" alt="Study area map: single column"></a><br><b>Study area map: single column</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/house_style/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/house_style.png" alt="House style"></a><br><b>House style</b></td>
+</tr>
+<tr>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/style_export/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/style_export.png" alt="Journal style and export"></a><br><b>Journal style and export</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/large_raster/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/large_raster.png" alt="Large raster at print size"></a><br><b>Large raster at print size</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/trend_significance/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/trend_significance.png" alt="Trend and significance"></a><br><b>Trend and significance</b></td>
+</tr>
+<tr>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/trend_map_swat/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/trend_map_swat.png" alt="Trend map: Swat valley NDVI 2001–2024"></a><br><b>Trend map: Swat valley NDVI 2001–2024</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/trend_profile_swat/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/trend_profile_swat.png" alt="Trend map with latitude profile"></a><br><b>Trend map with latitude profile</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/palettes/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/palettes.png" alt="Built-in palettes"></a><br><b>Built-in palettes</b></td>
+</tr>
+<tr>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/event_composite_swat/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/event_composite_swat.png" alt="Event composite: Swat hot-dry months"></a><br><b>Event composite: Swat hot-dry months</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/event_composite_synthetic/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/event_composite_synthetic.png" alt="Event composite with significance"></a><br><b>Event composite with significance</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/accuracy_scatter_icesat2/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/accuracy_scatter_icesat2.png" alt="Accuracy scatter: ICESat-2 against a DEM"></a><br><b>Accuracy scatter: ICESat-2 against a DEM</b></td>
+</tr>
+<tr>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/accuracy_scatter_synthetic/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/accuracy_scatter_synthetic.png" alt="Accuracy scatter: calibration and validation"></a><br><b>Accuracy scatter: calibration and validation</b></td>
+<td width="33%"></td>
+<td width="33%"></td>
+</tr>
+</table>
+
+More in the [gallery](https://kmkamilkhel.github.io/eofigs/gallery/), with the code for
+each figure.
+
+## Installation
+
+```bash
+pip install eofigs
+```
+
+eofigs needs Python 3.11 or newer. On Windows and macOS, conda-forge is the simplest source
+of its geospatial libraries; see the
+[installation guide](https://kmkamilkhel.github.io/eofigs/installation/).
+
+## Quick start
+
+```python
+import numpy as np
+import eofigs
+
+eofigs.set_style("elsevier")  # fonts, sizes and widths of the journal
+rng = np.random.default_rng(1)
+field = rng.gamma(5, 30, 300)  # observed aboveground biomass (Mg ha⁻¹)
+model = 0.9 * field + rng.normal(10, 20, 300)  # predicted
+fig = eofigs.accuracy_scatter(field, model, variable="agb")
+print(fig.eofigs_layout["caption"])  # a ready caption sentence
+print(eofigs.check_figure(fig))  # size, dpi, smallest font, fonts, colour-blind safety
+eofigs.save_figure(fig, "fig_agb")  # vector PDF and a 600 dpi raster
+```
+
+More in the [quickstart](https://kmkamilkhel.github.io/eofigs/quickstart/) and the
+[gallery](https://kmkamilkhel.github.io/eofigs/gallery/).
+
+## Run with Docker
+
+A container image with eofigs and its geospatial stack (cartopy, rioxarray, geopandas, fonts)
+is published on GitHub Container Registry for each release (`0.1.0`, `latest`; `dev` follows
+the main branch):
+
+```bash
+docker run --rm -v "$PWD":/work ghcr.io/kmkamilkhel/eofigs:0.1.0 python script.py
+```
+
+## Roadmap
+
+Available in v0.1: `set_style`, `style`, `new_figure`, `label_panels`,
+`save_figure`, `check_figure`, `cvd_preview`, `tidy_axes`, `palettes`, `variable`,
+`register_variable`, `fit_raster`, `trend`, `figure_set`, `study_area_map`,
+`add_north_arrow`, `add_scale_bar`, `add_inset`, `trend_map`, `event_composite` and
+`accuracy_scatter`.
+
+
+**v0.1**
+
+| Function | Purpose |
+|---|---|
+| `set_style`, `new_figure`, `save_figure` | Journal presets (Elsevier, Springer, MDPI, Wiley, Frontiers, Taylor & Francis), widths in mm, one-call export |
+| `check_figure`, `cvd_preview` | Size, dpi, smallest font, embedded fonts, colour-blind safety; preview as seen with colour-vision deficiencies |
+| `palettes`, `tidy_axes` | Built-in palettes and colour maps; a few ticks at round values |
+| `figure_set` | Manuscript figure set with automatic Fig/FigS numbering and a manifest |
+| `variable`, `register_variable` | Variable library: colour map, symbol, unit, range |
+| `fit_raster` | Reduce large rasters to the pixels the printed figure needs |
+| `trend` | Theil–Sen slope with Mann–Kendall test on a time-series cube |
+| `study_area_map` | DEM hillshade, overlay, labelled points, locator inset, graticule, north arrow to true north, scale bar, legend; automatic layout |
+| `trend_map` | Trend map with zero-centred colours, significance dots, optional latitude profile |
+| `event_composite` | Before/during/after anomaly maps with a composite time series |
+| `accuracy_scatter` | Observed against predicted values with the 1:1 line, a fitted line (Piñeiro et al. 2008), R², RMSE, NMAD and bias, density colours or groups |
+
+**v0.2**: burn severity, recovery and disturbance recipes, SHAP and partial dependence styling,
+confusion matrix, Google Earth Engine input through Xee at print scale.
+
+**v0.3**: R package with matching function names.
+
+## Contributing
+
+Questions and ideas are welcome in [Discussions](https://github.com/kmkamilkhel/eofigs/discussions);
+bugs and feature requests in [Issues](https://github.com/kmkamilkhel/eofigs/issues).
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Citation
+
+If you use eofigs, please cite it using the metadata in [CITATION.cff](CITATION.cff).
+
+## License
+
+MIT. See [LICENSE](LICENSE). Data files have their own licences, listed in
+[DATA_LICENSES.md](DATA_LICENSES.md).

eofigs-0.1.0/README.md

@@ -0,0 +1,136 @@
+# eofigs
+
+[![Tests](https://github.com/kmkamilkhel/eofigs/actions/workflows/tests.yml/badge.svg)](https://github.com/kmkamilkhel/eofigs/actions/workflows/tests.yml)
+[![Docs](https://github.com/kmkamilkhel/eofigs/actions/workflows/docs.yml/badge.svg)](https://kmkamilkhel.github.io/eofigs/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Analysis-aware, publication-ready figures for Earth observation research.
+
+eofigs turns Earth observation analysis outputs (rasters, time series, validation pairs) into
+journal-ready figures that know the analysis, the variable and the printed size:
+
+- **Recipe figures** for common analyses: trend with significance, event composites, and later
+  recovery, burn severity, disturbance and divergence.
+- **A variable library** with fixed colour maps, symbols and units, so NDVI, LST or GPP look the
+  same in every figure, and their anomalies and trends get zero-centred diverging colours.
+- **Print-size rendering**: rasters are read and reduced to the pixels the printed figure needs,
+  from its width in mm and its dpi, keeping memory use and PDF size small.
+- **Journal presets and one-call export** to vector PDF plus 600 dpi PNG or TIFF, with a check
+  of size, resolution, smallest font, font embedding and colour-blind safety.
+
+## Gallery
+
+<table>
+<tr>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/study_area_swat/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/study_area_swat.png" alt="Study area map: Swat valley"></a><br><b>Study area map: Swat valley</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/study_area_single_column/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/study_area_single_column.png" alt="Study area map: single column"></a><br><b>Study area map: single column</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/house_style/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/house_style.png" alt="House style"></a><br><b>House style</b></td>
+</tr>
+<tr>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/style_export/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/style_export.png" alt="Journal style and export"></a><br><b>Journal style and export</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/large_raster/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/large_raster.png" alt="Large raster at print size"></a><br><b>Large raster at print size</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/trend_significance/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/trend_significance.png" alt="Trend and significance"></a><br><b>Trend and significance</b></td>
+</tr>
+<tr>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/trend_map_swat/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/trend_map_swat.png" alt="Trend map: Swat valley NDVI 2001–2024"></a><br><b>Trend map: Swat valley NDVI 2001–2024</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/trend_profile_swat/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/trend_profile_swat.png" alt="Trend map with latitude profile"></a><br><b>Trend map with latitude profile</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/palettes/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/palettes.png" alt="Built-in palettes"></a><br><b>Built-in palettes</b></td>
+</tr>
+<tr>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/event_composite_swat/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/event_composite_swat.png" alt="Event composite: Swat hot-dry months"></a><br><b>Event composite: Swat hot-dry months</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/event_composite_synthetic/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/event_composite_synthetic.png" alt="Event composite with significance"></a><br><b>Event composite with significance</b></td>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/accuracy_scatter_icesat2/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/accuracy_scatter_icesat2.png" alt="Accuracy scatter: ICESat-2 against a DEM"></a><br><b>Accuracy scatter: ICESat-2 against a DEM</b></td>
+</tr>
+<tr>
+<td width="33%"><a href="https://kmkamilkhel.github.io/eofigs/gallery/accuracy_scatter_synthetic/"><img src="https://kmkamilkhel.github.io/eofigs/gallery/thumbs/accuracy_scatter_synthetic.png" alt="Accuracy scatter: calibration and validation"></a><br><b>Accuracy scatter: calibration and validation</b></td>
+<td width="33%"></td>
+<td width="33%"></td>
+</tr>
+</table>
+
+More in the [gallery](https://kmkamilkhel.github.io/eofigs/gallery/), with the code for
+each figure.
+
+## Installation
+
+```bash
+pip install eofigs
+```
+
+eofigs needs Python 3.11 or newer. On Windows and macOS, conda-forge is the simplest source
+of its geospatial libraries; see the
+[installation guide](https://kmkamilkhel.github.io/eofigs/installation/).
+
+## Quick start
+
+```python
+import numpy as np
+import eofigs
+
+eofigs.set_style("elsevier")  # fonts, sizes and widths of the journal
+rng = np.random.default_rng(1)
+field = rng.gamma(5, 30, 300)  # observed aboveground biomass (Mg ha⁻¹)
+model = 0.9 * field + rng.normal(10, 20, 300)  # predicted
+fig = eofigs.accuracy_scatter(field, model, variable="agb")
+print(fig.eofigs_layout["caption"])  # a ready caption sentence
+print(eofigs.check_figure(fig))  # size, dpi, smallest font, fonts, colour-blind safety
+eofigs.save_figure(fig, "fig_agb")  # vector PDF and a 600 dpi raster
+```
+
+More in the [quickstart](https://kmkamilkhel.github.io/eofigs/quickstart/) and the
+[gallery](https://kmkamilkhel.github.io/eofigs/gallery/).
+
+## Run with Docker
+
+A container image with eofigs and its geospatial stack (cartopy, rioxarray, geopandas, fonts)
+is published on GitHub Container Registry for each release (`0.1.0`, `latest`; `dev` follows
+the main branch):
+
+```bash
+docker run --rm -v "$PWD":/work ghcr.io/kmkamilkhel/eofigs:0.1.0 python script.py
+```
+
+## Roadmap
+
+Available in v0.1: `set_style`, `style`, `new_figure`, `label_panels`,
+`save_figure`, `check_figure`, `cvd_preview`, `tidy_axes`, `palettes`, `variable`,
+`register_variable`, `fit_raster`, `trend`, `figure_set`, `study_area_map`,
+`add_north_arrow`, `add_scale_bar`, `add_inset`, `trend_map`, `event_composite` and
+`accuracy_scatter`.
+
+
+**v0.1**
+
+| Function | Purpose |
+|---|---|
+| `set_style`, `new_figure`, `save_figure` | Journal presets (Elsevier, Springer, MDPI, Wiley, Frontiers, Taylor & Francis), widths in mm, one-call export |
+| `check_figure`, `cvd_preview` | Size, dpi, smallest font, embedded fonts, colour-blind safety; preview as seen with colour-vision deficiencies |
+| `palettes`, `tidy_axes` | Built-in palettes and colour maps; a few ticks at round values |
+| `figure_set` | Manuscript figure set with automatic Fig/FigS numbering and a manifest |
+| `variable`, `register_variable` | Variable library: colour map, symbol, unit, range |
+| `fit_raster` | Reduce large rasters to the pixels the printed figure needs |
+| `trend` | Theil–Sen slope with Mann–Kendall test on a time-series cube |
+| `study_area_map` | DEM hillshade, overlay, labelled points, locator inset, graticule, north arrow to true north, scale bar, legend; automatic layout |
+| `trend_map` | Trend map with zero-centred colours, significance dots, optional latitude profile |
+| `event_composite` | Before/during/after anomaly maps with a composite time series |
+| `accuracy_scatter` | Observed against predicted values with the 1:1 line, a fitted line (Piñeiro et al. 2008), R², RMSE, NMAD and bias, density colours or groups |
+
+**v0.2**: burn severity, recovery and disturbance recipes, SHAP and partial dependence styling,
+confusion matrix, Google Earth Engine input through Xee at print scale.
+
+**v0.3**: R package with matching function names.
+
+## Contributing
+
+Questions and ideas are welcome in [Discussions](https://github.com/kmkamilkhel/eofigs/discussions);
+bugs and feature requests in [Issues](https://github.com/kmkamilkhel/eofigs/issues).
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Citation
+
+If you use eofigs, please cite it using the metadata in [CITATION.cff](CITATION.cff).
+
+## License
+
+MIT. See [LICENSE](LICENSE). Data files have their own licences, listed in
+[DATA_LICENSES.md](DATA_LICENSES.md).

eofigs-0.1.0/conftest.py

@@ -0,0 +1,24 @@
+"""Test set-up shared by the test suite and the docstring examples."""
+
+import matplotlib
+
+matplotlib.use("Agg")
+
+import matplotlib.pyplot as plt  # noqa: E402
+import pytest  # noqa: E402
+
+from eofigs import styling, variables  # noqa: E402
+
+
+@pytest.fixture(autouse=True)
+def _clean_state():
+    """Run every test and example with fresh matplotlib settings, eofigs defaults and library."""
+    saved_style = dict(styling._STATE)
+    saved_registry = dict(variables._REGISTERED)
+    with matplotlib.rc_context():
+        yield
+    plt.close("all")
+    styling._STATE.clear()
+    styling._STATE.update(saved_style)
+    variables._REGISTERED.clear()
+    variables._REGISTERED.update(saved_registry)