ClimateGraph 0.4.0__py3-none-any.whl

ClimateGraph/utils/resample_engine.py

@@ -0,0 +1,156 @@
+"""Pluggable spatial resampling backends.
+
+A protocol plus the pyresample implementation, so another backend can be added
+without changing the code that calls for a resample.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Protocol, runtime_checkable
+
+import numpy as np
+from pyresample import kd_tree
+
+
+@runtime_checkable
+class ResampleEngine(Protocol):
+    """Protocol for spatial resampling backends.
+
+    Two-step design: ``prepare`` computes reusable indices/weights from the
+    source and destination geometries (expensive, done once per geometry pair),
+    and ``make_resampler`` returns a callable that applies those to a single
+    2-D array (cheap, called per variable per timestep via apply_ufunc).
+    """
+
+    def prepare(
+        self,
+        src_geom,
+        dst_geom,
+        radius_of_influence: int,
+        **kwargs,
+    ) -> Any:
+        """Compute resampling info (indices, weights, etc.).
+
+        The returned object is opaque — it is passed back into
+        ``make_resampler`` without inspection by the caller.
+        """
+        ...
+
+    def make_resampler(
+        self,
+        info: Any,
+        dst_shape: tuple,
+        src_shape: tuple,
+    ) -> Callable[[np.ndarray], np.ndarray]:
+        """Return a function ``f(block) -> resampled`` using precomputed info.
+
+        ``block`` carries the source spatial dims *last* (``(*lead, *src_shape)``,
+        the layout ``xr.apply_ufunc`` hands a non-vectorized ufunc); any leading
+        dims (time, z, …) are batched into a single pyresample call. A bare
+        ``src_shape`` block (no leading dims) is the 2-D legacy case.
+        """
+        ...
+
+
+class PyresampleEngine:
+    """Pyresample KD-tree backend. Supports nearest and gaussian methods."""
+
+    def __init__(
+        self,
+        method: str = "nearest",
+        sigmas: float = 10000,
+        neighbours: int | None = None,
+    ):
+        """Configure the engine with the resampling method and its options."""
+        self.method = method
+        self.sigmas = sigmas
+        self.neighbours = neighbours or (1 if method == "nearest" else 8)
+
+    def prepare(self, src_geom, dst_geom, radius_of_influence: int, **kwargs) -> tuple:
+        """Build whatever the backend needs before resampling onto a geometry."""
+        return kd_tree.get_neighbour_info(
+            src_geom,
+            dst_geom,
+            radius_of_influence=radius_of_influence,
+            neighbours=self.neighbours,
+        )
+
+    def make_resampler(
+        self, info: tuple, dst_shape: tuple, src_shape: tuple
+    ) -> Callable:
+        """Return a callable that resamples one array onto the target geometry."""
+        valid_input, valid_output, index_array, dist_array = info
+
+        if self.method == "nearest":
+
+            def _run(data: np.ndarray) -> np.ndarray:
+                return kd_tree.get_sample_from_neighbour_info(
+                    "nn",
+                    dst_shape,
+                    data,
+                    valid_input,
+                    valid_output,
+                    index_array,
+                    dist_array,
+                    fill_value=np.nan,
+                )
+
+        elif self.method == "gaussian":
+            sigma = self.sigmas
+            n_neighbours = index_array.shape[1] if index_array.ndim > 1 else 1
+
+            def _weight(dist):
+                return np.exp(-(dist**2) / (2 * sigma**2))
+
+            def _run(data: np.ndarray) -> np.ndarray:
+                return kd_tree.get_sample_from_neighbour_info(
+                    "custom",
+                    dst_shape,
+                    data,
+                    valid_input,
+                    valid_output,
+                    index_array,
+                    dist_array,
+                    weight_funcs=[_weight] * n_neighbours,
+                    fill_value=np.nan,
+                )
+
+        else:
+            raise ValueError(
+                f"PyresampleEngine does not support method {self.method!r}. "
+                f"Available: nearest, gaussian."
+            )
+
+        src_ndim = len(src_shape)
+
+        def _resample(block: np.ndarray) -> np.ndarray:
+            lead = block.shape[: block.ndim - src_ndim]
+            if not lead:
+                return _run(block)
+            k = int(np.prod(lead))
+            moved = np.moveaxis(block, range(len(lead)), range(-len(lead), 0))
+            out = _run(moved.reshape((*src_shape, k)))
+            out = out.reshape((*dst_shape, *lead))
+            return np.moveaxis(out, range(-len(lead), 0), range(len(lead)))
+
+        return _resample
+
+
+ENGINES: dict[str, type] = {
+    "pyresample": PyresampleEngine,
+}
+
+
+def get_engine(
+    backend: str | ResampleEngine = "pyresample", **kwargs
+) -> ResampleEngine:
+    """Resolve an engine by backend name or return an already-instantiated one."""
+    if isinstance(backend, str):
+        cls = ENGINES.get(backend.lower())
+        if cls is None:
+            raise ValueError(
+                f"Unknown resample backend {backend!r}. Available: {list(ENGINES)}"
+            )
+        return cls(**kwargs)
+    return backend

climategraph-0.4.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: ClimateGraph
+Version: 0.4.0
+Summary: A CLI tool for graphing Climate Data
+Author-email: Antonio Andrés Torga Mellado <antonio.torga@ug.uchile.cl>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AntonioTorga/ClimateGraph
+Project-URL: Documentation, https://climategraph.readthedocs.io
+Project-URL: Repository, https://github.com/AntonioTorga/ClimateGraph
+Project-URL: Issues, https://github.com/AntonioTorga/ClimateGraph/issues
+Project-URL: Changelog, https://github.com/AntonioTorga/ClimateGraph/blob/main/CHANGELOG.md
+Keywords: climate,air quality,xarray,visualization,netcdf,wrf,chimere
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: xarray
+Requires-Dist: pandas
+Requires-Dist: openpyxl
+Requires-Dist: dask
+Requires-Dist: netcdf4
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: pyyaml
+Requires-Dist: pyresample
+Requires-Dist: cartopy
+Requires-Dist: pydantic
+Requires-Dist: pint
+Requires-Dist: pint_xarray
+Requires-Dist: geopandas
+Requires-Dist: regionmask
+Requires-Dist: h5netcdf
+Requires-Dist: h5py
+Requires-Dist: dask
+Provides-Extra: dev
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pillow; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.2; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: sphinx-gallery; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-design; extra == "docs"
+Requires-Dist: pylint; extra == "docs"
+Requires-Dist: pydeps; extra == "docs"
+Provides-Extra: doc
+Requires-Dist: sphinx; extra == "doc"
+Requires-Dist: sphinx-rtd-theme; extra == "doc"
+Requires-Dist: myst-parser; extra == "doc"
+Dynamic: license-file
+
+# 🌍 ClimateGraph
+
+[![CI](https://github.com/AntonioTorga/ClimateGraph/actions/workflows/ci.yml/badge.svg)](https://github.com/AntonioTorga/ClimateGraph/actions/workflows/ci.yml)
+[![Documentation](https://readthedocs.org/projects/climategraph/badge/?version=latest)](https://climategraph.readthedocs.io/en/latest/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**ClimateGraph** reads, transforms and visualizes climate and environmental data
+from sources that have nothing in common — a gridded model output, a network of
+monitoring stations, a folder of CSVs — and lets you compare them without
+writing code for each one.
+
+A single control file says what data exists, how to filter it, and what to draw.
+
+![Hourly PM2.5 from a station network and a model](https://raw.githubusercontent.com/AntonioTorga/ClimateGraph/main/docs/source/_static/examples/timeseries.png)
+
+```yaml
+analysis:
+  output_path: "./results"
+
+data:
+  STATIONS:
+    path: "./data/stations.nc"
+    topology: PointSurface
+    reader: defaultpointsurface
+    vars: {PM25: {name: pm25, unit: "ug/m**3"}}
+  MODEL:
+    path: "./data/model.nc"
+    topology: RegularGrid
+    reader: defaultgrid
+    vars: {PM25: {name: pm25, unit: "ug/m**3"}}
+
+plots:
+  comparison:
+    type: timeseries
+    data: [STATIONS, MODEL]
+    time: "1/6/2021 - 10/6/2021"
+    vars: {PM25: "ug/m**3"}
+```
+
+```console
+$ ClimateGraph run config.yaml
+```
+
+That simple config file creates the picture above comparing PM2.5 between monitoring stations and a model.
+
+## Why
+
+- **Topology agnostic** — grids and station networks are compared directly;
+  resampling between them is a configuration option, not your problem.
+- **Config-driven** — the analysis lives in YAML or JSON, not in a script.
+- **Lazy** — nothing is read until it is actually needed.
+- **Extensible** — a new reader, plot type or domain is one subclass. It
+  registers itself and the configuration schema picks it up automatically.
+
+## Install
+
+Requires Python 3.12+. Some dependencies build against system libraries:
+
+```console
+$ sudo apt-get install -y libgeos-dev libproj-dev libhdf5-dev libnetcdf-dev
+$ git clone https://github.com/AntonioTorga/ClimateGraph.git
+$ cd ClimateGraph
+$ pip install -e .
+```
+
+The sample NetCDFs under `test_data/data/` are Git LFS and excluded from clones
+by default, so this is quick and the fast test suite runs without them.
+
+## Documentation
+
+**[climategraph.readthedocs.io](https://climategraph.readthedocs.io)**
+
+| | |
+|---|---|
+| [Quickstart](https://climategraph.readthedocs.io/en/latest/getting-started/quickstart.html) | From a blank file to a figure |
+| [Examples](https://climategraph.readthedocs.io/en/latest/examples.html) | One per plot type, each with the config that produced it |
+| [Control file reference](https://climategraph.readthedocs.io/en/latest/reference/control-file.html) | Every field of every block |
+| [Architecture](https://climategraph.readthedocs.io/en/latest/about/overview.html) | How it works, module by module, and how to extend it |
+| [API reference](https://climategraph.readthedocs.io/en/latest/api/index.html) | Generated from the source |
+
+Try the examples straight from a clone — the data is in the repository:
+
+```console
+$ python docs/examples/make_data.py
+$ ClimateGraph run docs/examples/configs/timeseries.yaml
+```
+
+## Development
+
+```console
+$ pip install -e ".[dev,test,docs]"
+$ pre-commit install          # once per clone
+$ pytest -m "not slow"
+$ make -C docs html
+```
+
+Every push and every pull request against `main` or `develop` runs lint, the
+fast test suite on Python 3.12 and 3.13, a coverage gate, and a strict
+documentation build. Slow tests touch the LFS sample data and skip automatically
+when it is absent.
+
+## Funding
+
+This project is funded by ANID (Agencia Nacional de Investigación y Desarrollo)
+Chile, through the FONDECYT Regular project N° 1231717, directed by Nicolas
+Huneeus.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

climategraph-0.4.0.dist-info/RECORD

@@ -0,0 +1,44 @@
+ClimateGraph/__init__.py,sha256=UlLtQwiKVRDrEEvdt1S7hIpDWrPxar3Ulgjpt4uY36Y,259
+ClimateGraph/appkernel.py,sha256=izwjJk44POfTw6Rt9Mk41HzX8Z3hIwfzAz0ymsI45So,5378
+ClimateGraph/cli.py,sha256=y51TD9b4SRiOLWd0BFs1efS2sTBuTsElUR1M6iRN4QQ,1928
+ClimateGraph/data/__init__.py,sha256=IsMCXa9m8VwdaBbywtHv3Z_Fyq2_QJ5fIR8HPv8sBQU,273
+ClimateGraph/data/data.py,sha256=gJWya74UzmzRv7mdEkRLtBKOBHPdxbkEGNaYHPoJkOk,18132
+ClimateGraph/data/point_surface.py,sha256=iQXFrGrsfWEtqyYQXR-3D_J0AnYeTpjDmbF5pIefe6I,3095
+ClimateGraph/data/regular_grid.py,sha256=TQ7L80vHE5mPLWVRYPn9Gcc3YPyKXgaH3OYuRyGwkg8,783
+ClimateGraph/data/satellite_swath.py,sha256=80n-pZsxS5217UdUvUrxbvGxHO217YfLdumFQKXFq5U,583
+ClimateGraph/domain/__init__.py,sha256=eMNvkrwpANJPrXu-ssyY3MRSyACmLlnoV9FiJj5u4NY,247
+ClimateGraph/domain/domain.py,sha256=RSXq6REqxEpRrfCnYbj_SOskrj0MYJIF7vRrEFpMwmU,6279
+ClimateGraph/domain/domains.py,sha256=BNa8O-7cciKdd02q-PqsMKl-Tj_ktXVc4hnafjQ7j7I,9428
+ClimateGraph/plot/__init__.py,sha256=R7kXia-IKilZe6wkx4MdXZNorzZrktK_sm-6MzuJDms,235
+ClimateGraph/plot/plot.py,sha256=0WgPaTAP0K3k7BVRrqZ4m2VAkOO7nZt8XOoqCMIvpA0,13772
+ClimateGraph/plot/plots.py,sha256=tw9lhBxsusIOAXBi5-4FDf6S2_lz2TZxEP9hxsrnpN8,43457
+ClimateGraph/plot/primitive.py,sha256=fk1r_JpfjTj4bQ8in9Z9muWsSYASj3kOZcJcYusReiM,3328
+ClimateGraph/plot/primitives.py,sha256=8dcAS_vMUVwz_Qv8RlsYCNhEemJ1hPaIrAV2vf-GY1Y,5158
+ClimateGraph/reader/__init__.py,sha256=lWeUhbU_LilagEF11UqaKL9ydFoJZsXqJXJvPd1_Q7o,268
+ClimateGraph/reader/reader/__init__.py,sha256=yI_SZTp9zzzF5r171iy6uWcTDbC1mPPQMIuonTbqoD4,283
+ClimateGraph/reader/reader/reader.py,sha256=uNhG_dEjmt59k4dQ5TkiV-Nwbvkt9X8NfVYyRkIRXz4,13591
+ClimateGraph/reader/reader/point_surface/__init__.py,sha256=Fk4ctPwe_loxMyLahMu5ZfESUc17mmfJjJx9VyK2fc4,191
+ClimateGraph/reader/reader/point_surface/csv_base.py,sha256=m7Jc2FCEiUagUr4pPeu8JlBlzJsT_qrqakbJBotGa3M,5806
+ClimateGraph/reader/reader/point_surface/default.py,sha256=kKc13WImwzB5nKDCnWE1tzxnAs4iEIeY9bdxz72hVXI,1407
+ClimateGraph/reader/reader/point_surface/dmc.py,sha256=PF0sxeEKskPn4piYYiM8uZhqJXc20m8D2FapWk3Ksgs,341
+ClimateGraph/reader/reader/point_surface/sinca.py,sha256=gzi3hyB_f_1hD8IpBKf_qoLvoE7cUXty3K3yNEqOM3g,357
+ClimateGraph/reader/reader/point_surface/single_file.py,sha256=dE1QkFKAoCDmYfmELOiDUf2TahjIMb-eMTxIWXB6p30,2436
+ClimateGraph/reader/reader/point_surface/station_per_file.py,sha256=MtTlZ7ofDHM0RNI3auzaWsgeJqRqZ8ATWV3ntq_e3sU,2137
+ClimateGraph/reader/reader/point_surface/variable_per_file.py,sha256=5gV7Dm9-hSJp3_SV1KNPwis1IEJ6GnDBGxQoo4-NJfM,3790
+ClimateGraph/reader/reader/regular_grid/__init__.py,sha256=5-Ndsw2QHTPvTbn2eDTTESVqEK0fFQ9mOnh0bEsGwVY,169
+ClimateGraph/reader/reader/regular_grid/chimere.py,sha256=QzP3Ccztr0lw2L6cqzDpuWAzoHi3AY78UvwQ437TVm0,547
+ClimateGraph/reader/reader/regular_grid/default.py,sha256=L7QmoTD7lknjShAogTtuoZi4ccTJk60mW6g8AsrS8AY,2109
+ClimateGraph/reader/reader/regular_grid/wrf.py,sha256=9HDWS8Of76Wt3FmJ9tJ67bm7I0XIBFa5oVM0BwyADUU,2069
+ClimateGraph/utils/__init__.py,sha256=AB8zKTXq0qfM0k5Yt4TUpnrVutIrNL7t4IonZjCJyC0,78
+ClimateGraph/utils/control_model.py,sha256=2IsHU8Nlr1LU3zcTqvXmgifL1KSoz0WFn9B24eDayYk,11403
+ClimateGraph/utils/dataset_utils.py,sha256=9bWdemHMoYEmp6N0tS1YinjsA72GX7AdK7SpS1iq9LU,9886
+ClimateGraph/utils/general_utils.py,sha256=CIv2NcKB_0NOyti3kjq-9Egu42fHUn8p_IH7SxPeyr8,7811
+ClimateGraph/utils/parser.py,sha256=o5hf92XIYB7is0RehQ43wf-xMeKA9owK-AVhkZ4IwUU,10525
+ClimateGraph/utils/registry.py,sha256=ISMPLr7K7CwH9HDnWDkWXv-U9zeIXEBdSaxF78dONAo,3035
+ClimateGraph/utils/resample_engine.py,sha256=PaPjC8EZ61BvgjqJMD4lETAPM-U6DX5btU58GN4jRt0,5129
+climategraph-0.4.0.dist-info/licenses/LICENSE,sha256=gG29UruQPO9wQm3Q6SZq83YC6epHzwdNhSRfdUv8eD4,1091
+climategraph-0.4.0.dist-info/METADATA,sha256=uv4m16GKHwDXLZhV5hznHwxGwlNxYdG54adipi6IMWA,6509
+climategraph-0.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+climategraph-0.4.0.dist-info/entry_points.txt,sha256=AwEWGaxK-Eb_37LFjGmrmDnMIWXr7e7Nmgp79LrVeMc,54
+climategraph-0.4.0.dist-info/top_level.txt,sha256=wfJevfLxGeFuV1IwtKWwPZU_odgKjUHhAGCwPyyfJSs,13
+climategraph-0.4.0.dist-info/RECORD,,

climategraph-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

climategraph-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ClimateGraph = ClimateGraph.cli:app

climategraph-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Antonio Torga and Nicolás Huneeus
+
+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.

climategraph-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ClimateGraph