grid-process 1.0.0__py3-none-any.whl

grid_process/units_conv.py

@@ -0,0 +1,209 @@
+# Copyright (c) 2026 MeteoSwiss, contributors listed in AUTHORS
+#
+# Distributed under the terms of the BSD 3-Clause License.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+Module to control, parse and convert units
+"""
+
+import logging
+import re
+from functools import partial
+from collections.abc import Sequence, Hashable
+
+import numpy as np
+import xarray as xr
+from pint import UnitRegistry
+
+from grid_process.helpers import make_accessor
+
+logger = logging.getLogger(__name__)
+
+
+class UnitsError(Exception):
+    """
+    Class to raise units errors
+    """
+
+
+# Register xarray accessor so module functions can also be called as methods
+# on xr.DataArray objects
+@xr.register_dataarray_accessor("units_conv")
+class DaUnits:
+    """
+    Xarray accessors class for units utility functions on DataArray
+    """
+
+    def __init__(self, da: xr.DataArray):
+        self._data = da
+
+
+@xr.register_dataset_accessor("units_conv")
+class DsUnits:
+    """
+    Xarray accessors class for units utility functions on Dataset
+    """
+
+    def __init__(self, ds: xr.Dataset):
+        self._data = ds
+
+
+dataarray_accessor = partial(make_accessor, accessor_class=DaUnits)
+dataset_accessor = partial(make_accessor, accessor_class=DsUnits)
+
+ureg: UnitRegistry = UnitRegistry(
+    autoconvert_offset_to_baseunit=True,
+    preprocessors=[
+        partial(
+            re.sub,
+            r"(?<=[A-Za-z])(?![A-Za-z])(?<![0-9\-][eE])(?<![0-9\-])(?=[0-9\-])",
+            "**",
+        ),
+        partial(re.sub, r"\b[h]\b", "hour"),  # avoid parsing of Plank constant for h
+    ],
+)
+
+
+@dataarray_accessor
+def da_to(da: xr.DataArray, dst_units: str) -> xr.DataArray:
+    """
+    Convert units in a xarray.DataArray.
+
+    Parameters
+    ----------
+    da : xarray.DataArray
+        with attribute "units"
+    dst_units : str
+        destination units
+
+    Returns
+    -------
+    da_out : xarray.DataArray
+        contains the data array with converted units
+
+    Raises
+    ------
+    pint.errors.DimensionalityError
+        if the conversion is not possible
+    """
+
+    da = da.copy()
+    src_units_parsed = ureg.parse_units(da.units)
+    dst_units_parsed = ureg.parse_units(dst_units)
+
+    if src_units_parsed == dst_units_parsed:
+        pass
+    else:
+        da_quantity = da.values * src_units_parsed
+        da.values = da_quantity.to(dst_units_parsed).magnitude
+
+    da.attrs["units"] = dst_units
+    return da
+
+
+@dataset_accessor
+def ds_to(ds: xr.Dataset, dst_units: str | dict[Hashable, str]) -> xr.Dataset:
+    """
+    Convert units in a xarray.Dataset.
+
+    Parameters
+    ----------
+    ds : xarray.Dataset
+        with variable attributes "units"
+    dst_units : str or dict
+        destination units for each data variable to be converted.
+        Variable names not specified in ``dst_units`` are kept in the same units.
+        If passed as a single string, all variables in the dataset are converted to the
+        same units
+
+    Returns
+    -------
+    ds_out : xarray.Dataset
+        contains the dataset with converted units
+
+    Raises
+    ------
+    pint.errors.DimensionalityError
+        if the conversion is not possible
+    """
+
+    if isinstance(dst_units, str):
+        dst_units = {var: dst_units for var in ds}
+    ds_out = ds.copy()
+    for var, dst_unit in dst_units.items():
+        ds_out[var] = da_to(ds[var], dst_unit)
+    return ds_out
+
+
+def consistency_check(datasets: Sequence[xr.Dataset], check_vars: bool = True) -> dict[str, dict[str, str]]:
+    """
+    Checks that the input datasets have same data variables and units. If it is
+    the case, returns the 'units' attributes of each data variable otherwise
+    raises an error.
+
+    Parameters
+    ----------
+    datasets : sequence of xarray.Dataset
+        each data variable in the datasets must have a 'units' attributes
+    check_vars : bool, optional
+        if False, allows datasets to have different variables, but common ones
+        must have same units. Default is True
+
+    Returns
+    -------
+    out : dict
+        contains the 'units' attribute of the data variables in the input
+        datasets. In case same units are specified in various format, the
+        dominant format is kept if there is one otherwise the format from the
+        first dataset in the input sequence
+
+    Raises
+    ------
+    UnitsError
+        if same variables across the input datasets have different units
+    ValueError
+        when ``check_vars=True`` and the input datasets do not have exact same
+        set of variables
+    """
+
+    vars_attrs = np.array([{varname: da.units for varname, da in ds.data_vars.items()} for ds in datasets])
+
+    if check_vars:
+        if not np.all([dic.keys() == vars_attrs[0].keys() for dic in vars_attrs]):
+            raise ValueError("The datasets to combine must have matching variables, which was not the case")
+
+    unique = {key: {"units": value} for elem in vars_attrs[::-1] for key, value in elem.items()}
+    if np.all(
+        [
+            ureg.parse_units(value) == ureg.parse_units(unique[key]["units"])
+            for dic in vars_attrs
+            for key, value in dic.items()
+        ]
+    ):
+        return unique
+
+    raise UnitsError("Same variables among the datasets to combine have different units. Please convert units first")
+
+
+def units_check(datasets: Sequence[xr.Dataset]) -> None:
+    """
+    Check that the data variables in the datasets all have same single units.
+    If not, it raises an error.
+
+    Parameters
+    ----------
+    datasets : sequence of xarray.Dataset
+        each data variable in the datasets must have a 'units' attributes
+
+    Raises
+    ------
+    UnitsError
+        if any variable in any of the input datasets have different units
+    """
+
+    units = [ureg.parse_units(da.units) for ds in datasets for _, da in ds.data_vars.items()]
+
+    if len(set(units)) != 1:
+        raise UnitsError("Variables in the datasets do not all have same single units")

grid_process-1.0.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: grid-process
+Version: 1.0.0
+Summary: Weather forecast oriented Python library to process xarray Datasets
+License-Expression: BSD-3-Clause
+License-File: AUTHORS
+License-File: LICENSE
+Author: Mathieu Schaer
+Author-email: mathieu.schaer@meteoswiss.ch
+Requires-Python: >=3.11,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: bottleneck (>=1.4.0)
+Requires-Dist: dask (>=2023.6.1)
+Requires-Dist: geopandas (>=1.0.0)
+Requires-Dist: numpy (>=1.26.0)
+Requires-Dist: pandas (>=2.1.2)
+Requires-Dist: pint (>=0.24.4)
+Requires-Dist: pydantic (>=2.7.0)
+Requires-Dist: pydantic-settings (>=2.2.0)
+Requires-Dist: pyproj (>=3.6.0)
+Requires-Dist: pyyaml (>=6.0)
+Requires-Dist: scipy (>=1.10.1)
+Requires-Dist: xarray (>=2024.6.0)
+Project-URL: Changelog, https://github.com/MeteoSwiss/grid-process/blob/main/CHANGELOG.rst
+Project-URL: Documentation, https://meteoswiss.github.io/grid-process/
+Project-URL: Homepage, https://github.com/MeteoSwiss/grid-process
+Project-URL: Repository, https://github.com/MeteoSwiss/grid-process
+Description-Content-Type: text/x-rst
+
+.. image:: https://img.shields.io/pypi/v/grid-process.svg
+    :target: https://pypi.org/project/grid-process/
+
+.. image:: https://img.shields.io/pypi/pyversions/grid-process.svg
+    :target: https://pypi.org/project/grid-process/
+
+.. image:: https://img.shields.io/pypi/l/grid-process.svg
+    :target: https://pypi.org/project/grid-process/
+
+.. image:: https://github.com/MeteoSwiss/grid-process/actions/workflows/CI_test.yaml/badge.svg
+    :target: https://github.com/MeteoSwiss/grid-process/actions/workflows/CI_test.yaml
+
+.. image:: https://github.com/MeteoSwiss/grid-process/actions/workflows/CI_publish_dev_documentation.yaml/badge.svg
+    :target: https://github.com/MeteoSwiss/grid-process/actions/workflows/CI_publish_dev_documentation.yaml
+
+===============
+Getting Started
+===============
+
+Weather forecast oriented Python library to process xarray Datasets.
+
+.. warning::
+
+    **Project status and deprecation outlook.** ``grid-process`` mainly serves the needs of MeteoSwiss operational
+    processing. As equivalent functionality becomes available in the
+    `ECMWF earthkit ecosystem <https://earthkit.ecmwf.int/>`_, parts of this library, potentially all of it, will be
+    gradually deprecated in favour of earthkit. Any deprecation will be announced in the changelog. If you start a new
+    project, please consider earthkit first.
+
+Features
+--------
+
+* Grid to points interpolations routines
+* Temporal interpolation routines
+* Spatial and temporal aggregation routines
+* Ensemble and spatial statistics
+* Configurable data model (dimension, coordinate and variable names) to support many data conventions
+* And much more
+
+.. note::
+
+    ``grid-process`` was originally developed internally at MeteoSwiss as ``gridefix-process`` (versions 1 to 6),
+    to process grids from an internal grid database. The first open-source release is ``1.0.0``.
+    See `Migrating from gridefix-process`_ if you are upgrading from the internal package.
+
+Development Setup with Poetry
+-----------------------------
+
+Building the Project
+''''''''''''''''''''
+.. code-block:: console
+
+    $ cd grid-process
+    $ poetry install
+
+Run Tests
+'''''''''
+
+.. code-block:: console
+
+    $ poetry run pytest
+
+Run Quality Tools
+'''''''''''''''''
+
+.. code-block:: console
+
+    $ poetry run pylint grid_process
+    $ poetry run mypy grid_process
+    $ poetry run ruff format
+
+Generate Documentation
+''''''''''''''''''''''
+
+.. code-block:: console
+
+    $ poetry run sphinx-build doc doc/_build
+
+Then open the index.html file generated in *grid-process/doc/_build/*.
+
+Build wheels
+''''''''''''
+
+.. code-block:: console
+
+    $ poetry build
+
+Using the Library
+-----------------
+
+To install grid-process in your project, run this command in your terminal:
+
+.. code-block:: console
+
+    $ poetry add grid-process
+
+You can then use the library in your project through
+
+.. code-block:: python
+
+    import grid_process
+
+Migrating from gridefix-process
+-------------------------------
+
+* Package and import name: ``gridefix-process`` / ``gridefix_process`` became ``grid-process`` / ``grid_process``.
+* Environment variable prefix: ``GRIDEFIX_PROCESS__`` became ``GRID_PROCESS__``
+  (e.g. ``GRID_PROCESS__data_model__validtime``).
+* Versioning restarts at ``1.0.0``; the last internal release was ``gridefix-process`` 6.0.1.
+
+Release the Project
+-------------------
+
+The project follows the **GitOps concept**: releases are triggered whenever a Git TAG is created.
+
+The TAG must follow the `semantic version <https://semver.org/>`__ format and `PEP 440 <https://peps.python.org/pep-0440/>`__ , otherwise the release task will fail.
+
+Follow these steps to create a new release:
+
+* Adapt CHANGELOG.rst with release information
+* Adapt ``doc/_static/switcher_config.json`` adding the new documentation URL for the release
+* Create a new Release in the Github project
+

grid_process-1.0.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+grid_process/__init__.py,sha256=Jcp9bagxKMYWbJvnH6av9nez7Rz3eNn4eH8xw7nmrJs,416
+grid_process/aggreg.py,sha256=if_Rw_vWn3cou-1gggNWp_ONA1_DmmLIavoNvN-OWEA,15858
+grid_process/blending.py,sha256=DA-OcnnxVn_RVlezpIIiRyeqeuk7Dtomyn6f4fWqdCQ,7903
+grid_process/config/__init__.py,sha256=Z9eycy3pcWnAMQEEvzU58proP8-QjFuV4C9iIhMvpLk,167
+grid_process/config/grid_process.yaml,sha256=d0MViWtaNcD9Yzf8OwlKFIUghttCaNZLCGTkB-F46DQ,768
+grid_process/config/library_settings.py,sha256=2v_Ac4Lb24JtP9f4hX4LulSJSo81xGLpuNk37hDbUO8,1778
+grid_process/da_utils.py,sha256=Ovv6YOvrqMdJGOhsAiMQRexhIKbPMbf2s1LUr-yuABE,2870
+grid_process/data_model.py,sha256=7bLSz1XqjeEC-muTlvCEvf2XJGEBQcrazts-CRblf5k,18095
+grid_process/ds_utils.py,sha256=AoTk30gelptpmmIluHGiZppeZo53EeEz1AcfP8r3_3I,1690
+grid_process/ens_stats.py,sha256=4K8bGY7nxb3wIZKRFciPTYbkDeKgrb1BLqaEo_nnudE,14305
+grid_process/grid_interp.py,sha256=2JobEgwhkNCTBSkB1-ZJBef_slWzPScNlwN_nH9uamY,75073
+grid_process/grid_interp_utils.py,sha256=taVJu83dIfQ5qmYsYrm0ddSSHdd2kKz62IqeFDKWqqs,8425
+grid_process/helpers.py,sha256=Xh1c9L593n3C4Ix-l4grfXhBCvf3Z502YD8ssWc729E,5399
+grid_process/optimization.py,sha256=Wx_i4OtG4DJ5DPpqBJoHeZtwbrtZIFb2mAppfOlAZfk,1471
+grid_process/sun.py,sha256=ZYfop-NBtzj0_P69gYMGRQzvYF9-JbfLAdgq3-BB62M,17730
+grid_process/time_utils.py,sha256=7izknDQ6jsIemSaW7l6_-BeK1ujIgko51yjPIaLN1Z4,3444
+grid_process/timeseries.py,sha256=HZzVagTq4PAtRd24SlD6gNbhfiTrRLqFMqBr7TZ8ZVs,20636
+grid_process/units_conv.py,sha256=LNlu3Re4ch6k9Ld2fdmepwYMwoxJ8XSTVYQ5GiRoey4,5911
+grid_process-1.0.0.dist-info/METADATA,sha256=JWBygUJSGYllfdL_qECh5Zhbjw5g70LcrgxKl4fUgYA,5086
+grid_process-1.0.0.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
+grid_process-1.0.0.dist-info/licenses/AUTHORS,sha256=fwJyCiS9pTKM48kEGJ0jwgkBa5T6PXpdCeXz-JSpc5g,135
+grid_process-1.0.0.dist-info/licenses/LICENSE,sha256=qfrMXNx_JZjckTrhyQAnw38WA0ZpMendVO7tY8XUsfQ,1544
+grid_process-1.0.0.dist-info/RECORD,,

grid_process-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.5.0
+Root-Is-Purelib: true
+Tag: py3-none-any

grid_process-1.0.0.dist-info/licenses/AUTHORS

@@ -0,0 +1,11 @@
+Development Lead
+----------------
+
+* Mathieu Schaer
+
+Contributors
+------------
+
+* Daniele Nerini
+* Adel Imamovic
+* Verena Bessenbacher

grid_process-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, MeteoSwiss
+Authors: Mathieu Schaer <mathieu.schaer@meteoswiss.ch>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.