Merge branch 'main' into improve_rename_like

Author: dcherian

.binder/environment.yml

@@ -7,5 +7,6 @@ dependencies:
   - netcdf4
   - pip
   - xarray
+  - pooch
   - pip:
     - git+https://github.com/xarray-contrib/cf-xarray

.github/workflows/ci.yaml

@@ -48,6 +48,29 @@ jobs:
           name: codecov-umbrella
           fail_ci_if_error: false
 
+  no-optional-deps:
+    name: no-optional-deps
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: conda-incubator/setup-miniconda@v2
+        with:
+          channels: conda-forge
+          mamba-version: "*"
+          activate-environment: cf_xarray_test
+          auto-update-conda: false
+          python-version: ${{ matrix.python-version }}
+      - name: Set up conda environment
+        shell: bash -l {0}
+        run: |
+          mamba env update -f ci/environment-no-optional-deps.yml
+          python -m pip install -e .
+          conda list
+      - name: Run Tests
+        shell: bash -l {0}
+        run: |
+          pytest -n 2
+
   upstream-dev:
     name: upstream-dev
     runs-on: ubuntu-latest

README.rst

@@ -34,4 +34,6 @@ A lightweight convenience wrapper for using CF attributes on xarray objects.
 
 For example you can use ``.cf.mean("latitude")`` instead of ``.mean("lat")`` if appropriate attributes are set! This allows you to write code that does not require knowledge of specific dimension or coordinate names particular to a dataset.
 
-See more in the introductory notebook `here <https://cf-xarray.readthedocs.io/en/latest/examples/introduction.html>`_.
+See more in the `introductory notebook <https://cf-xarray.readthedocs.io/en/latest/examples/introduction.html>`_.
+
+Try out our Earthcube 2021 Annual Meeting notebook `submission <https://binder.pangeo.io/v2/gh/malmans2/cf-xarray-earthcube/main?filepath=DC_01_cf-xarray.ipynb>`_.

cf_xarray/accessor.py

@@ -1615,15 +1615,15 @@ def get_bounds_dim_name(self, key: str) -> str:
         assert self._obj.sizes[bounds_dim] in [2, 4]
         return bounds_dim
 
-    def add_bounds(self, dims: Union[Hashable, Iterable[Hashable]]):
+    def add_bounds(self, keys: Union[str, Iterable[str]]):
         """
         Returns a new object with bounds variables. The bounds values are guessed assuming
         equal spacing on either side of a coordinate label.
 
         Parameters
         ----------
-        dims : Hashable or Iterable[Hashable]
-            Either a single dimension name or a list of dimension names.
+        keys : str or Iterable[str]
+            Either a single key or a list of keys corresponding to dimensions.
 
         Returns
         -------
@@ -1638,12 +1638,16 @@ def add_bounds(self, dims: Union[Hashable, Iterable[Hashable]]):
         The bounds variables are automatically named f"{dim}_bounds" where ``dim``
         is a dimension name.
         """
-        if isinstance(dims, Hashable):
-            dimensions = (dims,)
-        else:
-            dimensions = dims
+        if isinstance(keys, str):
+            keys = [keys]
+
+        dimensions = set()
+        for key in keys:
+            dimensions.update(
+                apply_mapper(_get_dims, self._obj, key, error=False, default=[key])
+            )
 
-        bad_dims: Set[Hashable] = set(dimensions) - set(self._obj.dims)
+        bad_dims: Set[str] = dimensions - set(self._obj.dims)
         if bad_dims:
             raise ValueError(
                 f"{bad_dims!r} are not dimensions in the underlying object."

cf_xarray/criteria.py

@@ -5,6 +5,7 @@
 """
 
 
+import copy
 import re
 from typing import MutableMapping, Tuple
 
@@ -74,19 +75,20 @@
 }
 
 # "long_name" and "standard_name" criteria are the same. For convenience.
-coordinate_criteria["long_name"] = coordinate_criteria["standard_name"]
+coordinate_criteria["long_name"] = copy.deepcopy(coordinate_criteria["standard_name"])
+coordinate_criteria["long_name"]["X"] += ("cell index along first dimension",)
+coordinate_criteria["long_name"]["Y"] += ("cell index along second dimension",)
 
 #: regular expressions for guess_coord_axis
 regex = {
     "time": re.compile("\\bt\\b|(time|min|hour|day|week|month|year)[0-9]*"),
-    "vertical": re.compile(
-        "(z|nav_lev|gdep|lv_|bottom_top|sigma|h(ei)?ght|altitude|depth|"
+    "Z": re.compile(
+        "(z|nav_lev|gdep|lv_|[o]*lev|bottom_top|sigma|h(ei)?ght|altitude|depth|"
         "isobaric|pres|isotherm)[a-z_]*[0-9]*"
     ),
-    "Y": re.compile("y"),
+    "Y": re.compile("y|j|nlat|nj"),
     "latitude": re.compile("y?(nav_lat|lat|gphi)[a-z0-9]*"),
-    "X": re.compile("x"),
+    "X": re.compile("x|i|nlon|ni"),
     "longitude": re.compile("x?(nav_lon|lon|glam)[a-z0-9]*"),
 }
-regex["Z"] = regex["vertical"]
 regex["T"] = regex["time"]

cf_xarray/tests/test_accessor.py

@@ -648,6 +648,10 @@ def test_add_bounds(obj, dims):
         assert added[dim].attrs["bounds"] == name
         assert_allclose(added[name].reset_coords(drop=True), expected[dim])
 
+    # Test multiple dimensions
+    assert not {"x1_bounds", "x2_bounds"} <= set(multiple.variables)
+    assert {"x1_bounds", "x2_bounds"} <= set(multiple.cf.add_bounds("X").variables)
+
 
 def test_bounds():
     ds = airds.copy(deep=True).cf.add_bounds("lat")
@@ -790,9 +794,9 @@ def _make_names(prefixes):
         "nav_lev",
     ]
 )
-_X_NAMES = _make_names(["x"])
-_Y_NAMES = _make_names(["y"])
-_Z_NAMES = _VERTICAL_NAMES
+_X_NAMES = _make_names(["x", "nlon", "i", "ni"])
+_Y_NAMES = _make_names(["y", "nlat", "j", "nj"])
+_Z_NAMES = _VERTICAL_NAMES + ["olevel", "level", "zlevel"]
 _LATITUDE_NAMES = _make_names(["lat", "latitude", "gphi", "nav_lat"])
 _LONGITUDE_NAMES = _make_names(["lon", "longitude", "glam", "nav_lon"])
 
@@ -1203,3 +1207,24 @@ def test_differentiate_positive_upward(obj):
     obj.z.attrs["positive"] = "zzz"
     with pytest.raises(ValueError):
         obj.cf.differentiate("z", positive_upward=True)
+
+
+def test_cmip6_attrs():
+    da = xr.DataArray(
+        np.ones((10, 10)),
+        dims=("nlon", "nlat"),
+        coords={
+            "nlon": (
+                "nlon",
+                np.arange(10),
+                {"long_name": "cell index along first dimension"},
+            ),
+            "nlat": (
+                "nlat",
+                np.arange(10),
+                {"long_name": "cell index along second dimension"},
+            ),
+        },
+    )
+    assert da.cf.axes["X"] == ["nlon"]
+    assert da.cf.axes["Y"] == ["nlat"]

cf_xarray/tests/test_units.py

@@ -0,0 +1,60 @@
+r"""Tests the operation of cf_xarray's ported unit support code.
+
+Reused with modification from MetPy under the terms of the BSD 3-Clause License.
+Copyright (c) 2017 MetPy Developers.
+"""
+
+import pytest
+
+pytest.importorskip("pint")
+
+from ..units import units
+
+
+def test_added_degrees_units():
+    """Test that our added degrees units are present in the registry."""
+    # Test equivalence of abbreviations/aliases to our defined names
+    assert str(units("degrees_N").units) == "degrees_north"
+    assert str(units("degreesN").units) == "degrees_north"
+    assert str(units("degree_north").units) == "degrees_north"
+    assert str(units("degree_N").units) == "degrees_north"
+    assert str(units("degreeN").units) == "degrees_north"
+    assert str(units("degrees_E").units) == "degrees_east"
+    assert str(units("degreesE").units) == "degrees_east"
+    assert str(units("degree_east").units) == "degrees_east"
+    assert str(units("degree_E").units) == "degrees_east"
+    assert str(units("degreeE").units) == "degrees_east"
+
+    # Test equivalence of our defined units to base units
+    assert units("degrees_north") == units("degrees")
+    assert units("degrees_north").to_base_units().units == units.radian
+    assert units("degrees_east") == units("degrees")
+    assert units("degrees_east").to_base_units().units == units.radian
+
+
+def test_gpm_unit():
+    """Test that the gpm unit does alias to meters."""
+    x = 1 * units("gpm")
+    assert str(x.units) == "meter"
+
+
+def test_psu_unit():
+    """Test that the psu unit are present in the registry."""
+    x = 1 * units("psu")
+    assert str(x.units) == "practical_salinity_unit"
+
+
+def test_percent_units():
+    """Test that percent sign units are properly parsed and interpreted."""
+    assert str(units("%").units) == "percent"
+
+
+@pytest.mark.xfail(reason="not supported by pint, yet: hgrecco/pint#1295")
+def test_udunits_power_syntax():
+    """Test that UDUNITS style powers are properly parsed and interpreted."""
+    assert units("m2 s-2").units == units.m ** 2 / units.s ** 2
+
+
+def test_udunits_power_syntax_parse_units():
+    """Test that UDUNITS style powers are properly parsed and interpreted."""
+    assert units.parse_units("m2 s-2") == units.m ** 2 / units.s ** 2

cf_xarray/units.py

@@ -0,0 +1,58 @@
+r"""Module to provide unit support via pint approximating UDUNITS/CF.
+
+Reused with modification from MetPy under the terms of the BSD 3-Clause License.
+Copyright (c) 2015,2017,2019 MetPy Developers.
+"""
+import functools
+import re
+import warnings
+
+import pint
+from pint import (  # noqa: F401
+    DimensionalityError,
+    UndefinedUnitError,
+    UnitStrippedWarning,
+)
+
+# Create registry, with preprocessors for UDUNITS-style powers (m2 s-2) and percent signs
+units = pint.UnitRegistry(
+    autoconvert_offset_to_baseunit=True,
+    preprocessors=[
+        functools.partial(
+            re.compile(
+                r"(?<=[A-Za-z])(?![A-Za-z])(?<![0-9\-][eE])(?<![0-9\-])(?=[0-9\-])"
+            ).sub,
+            "**",
+        ),
+        lambda string: string.replace("%", "percent"),
+    ],
+    force_ndarray_like=True,
+)
+
+units.define(
+    pint.unit.UnitDefinition("percent", "%", (), pint.converters.ScaleConverter(0.01))
+)
+
+# Define commonly encoutered units (both CF and non-CF) not defined by pint
+units.define(
+    "degrees_north = degree = degrees_N = degreesN = degree_north = degree_N = degreeN"
+)
+units.define(
+    "degrees_east = degree = degrees_E = degreesE = degree_east = degree_E = degreeE"
+)
+units.define("@alias meter = gpm")
+units.define("practical_salinity_unit = [] = psu")
+
+# Enable pint's built-in matplotlib support
+try:
+    units.setup_matplotlib()
+except ImportError:
+    warnings.warn(
+        "Import(s) unavailable to set up matplotlib support...skipping this portion "
+        "of the setup."
+    )
+
+# Set as application registry
+pint.set_application_registry(units)
+
+del pint

ci/environment-no-optional-deps.yml

@@ -0,0 +1,13 @@
+name: cf_xarray_test
+channels:
+  - conda-forge
+dependencies:
+  - pytest-cov
+  - pytest
+  - pytest-xdist
+  - dask
+  - matplotlib-base
+  - netcdf4
+  - pandas
+  - pooch
+  - xarray

ci/environment.yml

@@ -9,5 +9,6 @@ dependencies:
   - matplotlib-base
   - netcdf4
   - pandas
+  - pint
   - pooch
   - xarray

ci/upstream-dev-env.yml

@@ -12,3 +12,4 @@ dependencies:
   - pooch
   - pip:
     - git+https://github.com/pydata/xarray
+    - git+https://github.com/hgrecco/pint

doc/whats-new.rst

@@ -3,11 +3,17 @@
 What's New
 ----------
 
-v0.5.2 (unreleased)
+v0.5.3 (unreleased)
 ===================
-
+- Begin adding support for units with a unit registry for pint arrays. :pr:`197`.
+  By `Jon Thielen`_ and `Justus Magin`_.
 - :py:meth:`Dataset.cf.rename_like` also updates the ``bounds`` and ``cell_measures`` attributes. By `Mattia Almansi`_.
-- Added :py:attr:`DataArray.cf.formula_terms` and :py:attr:`Dataset.cf.formula_terms`.
+
+v0.5.2 (May 11, 2021)
+=====================
+
+- Add some explicit support for CMIP6 output. By `Deepak Cherian`_.
+- Replace the ``dims`` argument of :py:meth:`Dataset.cf.add_bounds` with ``keys``, allowing to use CF keys. By `Mattia Almansi`_.
 - Added :py:attr:`DataArray.cf.formula_terms` and :py:attr:`Dataset.cf.formula_terms`.
   By `Deepak Cherian`_.
 - Added :py:attr:`Dataset.cf.bounds` to return a dictionary mapping valid keys to the variable names of their bounds. By `Mattia Almansi`_.
@@ -102,6 +108,8 @@ v0.1.3
 - Support expanding key to multiple dimension names.
 
 .. _`Mattia Almansi`: https://github.com/malmans2
+.. _`Justus Magin`: https://github.com/keewis
+.. _`Jon Thielen`: https://github.com/jthielen
 .. _`Anderson Banihirwe`: https://github.com/andersy005
 .. _`Pascal Bourgault`: https://github.com/aulemahal
 .. _`Deepak Cherian`: https://github.com/dcherian

setup.cfg

@@ -41,7 +41,7 @@ skip_gitignore = true
 force_to_top = true
 default_section = THIRDPARTY
 known_first_party = cf_xarray
-known_third_party = dask,matplotlib,numpy,pandas,pkg_resources,pytest,setuptools,sphinx_autosummary_accessors,xarray
+known_third_party = dask,matplotlib,numpy,pandas,pint,pkg_resources,pytest,setuptools,sphinx_autosummary_accessors,xarray
 
 # Most of the numerical computing stack doesn't have type annotations yet.
 [mypy-affine.*]