diff --git a/docs/src/further_topics/netcdf_io.rst b/docs/src/further_topics/netcdf_io.rst index e151b2b7c1..bae32ebcae 100644 --- a/docs/src/further_topics/netcdf_io.rst +++ b/docs/src/further_topics/netcdf_io.rst @@ -134,7 +134,49 @@ Deferred Saving TBC -Guess Axis ------------ - -TBC +Guessing Coordinate Axes +------------------------ + +Iris will attempt to add an ``axis`` attribute when saving any coordinate +variable in a NetCDF file. E.g: + +:: + + float longitude(longitude) ; + longitude:axis = "X" ; + +This is achieved by calling :func:`iris.util.guess_coord_axis` on each +coordinate being saved. + +Disabling Axis-Guessing +^^^^^^^^^^^^^^^^^^^^^^^ + +For some coordinates, :func:`~iris.util.guess_coord_axis` will derive an +axis that is not appropriate. If you have such a coordinate, you can disable +axis-guessing by setting the coordinate's +:attr:`~iris.coords.Coord.ignore_axis` property to ``True``. + +One example (from https://github.com/SciTools/iris/issues/5003) is a +coordinate describing pressure thresholds, measured in hecto-pascals. +Iris interprets pressure units as indicating a Z-dimension coordinate, since +pressure is most commonly used to describe altitude/depth. But a +**pressure threshold** coordinate is instead describing alternate +**scenarios** - not a spatial dimension at all - and it is therefore +inappropriate to assign an axis to it. + +Worked example: + +.. doctest:: + + >>> from iris.coords import DimCoord + >>> from iris.util import guess_coord_axis + >>> my_coord = DimCoord( + ... points=[1000, 1010, 1020], + ... long_name="pressure_threshold", + ... units="hPa", + ... ) + >>> print(guess_coord_axis(my_coord)) + Z + >>> my_coord.ignore_axis = True + >>> print(guess_coord_axis(my_coord)) + None diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index d2a3d27236..ce534d9461 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -61,7 +61,7 @@ This document explains the changes made to Iris for this release #. `@HGWright`_ added :attr:`~iris.coords.Coord.ignore_axis` to allow manual intervention preventing :func:`~iris.util.guess_coord_axis` from acting on a - coordinate. (:pull:`5551`) + coordinate. `@trexfeathers`_ documented this. (:pull:`5551`, :pull:`5744`) #. `@pp-mo`_, `@trexfeathers`_ and `@ESadek-MO`_ added more control over NetCDF chunking with the use of the :data:`iris.fileformats.netcdf.loader.CHUNK_CONTROL` @@ -234,7 +234,7 @@ This document explains the changes made to Iris for this release #. `@bjlittle`_ replaced `black`_ with `ruff`_. (:pull:`5634`) #. `@tkknight`_ and `@bjlittle`_ (reviewer) updated codebase to be compliant with - almost all of the rules for `ruff pydocstyle`_. + almost all of the rules for `ruff pydocstyle`_. (https://github.com/SciTools/iris/issues/5625#issuecomment-1859159734) #. `@tkknight`_ and `@bjlittle`_ (reviewer) updated codebase to ensure docstrings diff --git a/lib/iris/coords.py b/lib/iris/coords.py index 8cbe0984cd..8ba5e32397 100644 --- a/lib/iris/coords.py +++ b/lib/iris/coords.py @@ -1662,10 +1662,10 @@ def climatological(self, value): @property def ignore_axis(self): - """A boolean that controls whether guess_coord_axis acts on this coordinate. + """A boolean controlling if iris.util.guess_coord_axis acts on this coordinate. - Defaults to False, and when set to True it will be skipped by - guess_coord_axis. + Defaults to ``False``, and when set to ``True`` it will be skipped by + :func:`iris.util.guess_coord_axis`. """ return self._ignore_axis diff --git a/lib/iris/util.py b/lib/iris/util.py index 6f42229aa9..020b67783a 100644 --- a/lib/iris/util.py +++ b/lib/iris/util.py @@ -249,8 +249,8 @@ def guess_coord_axis(coord): This function maintains laziness when called; it does not realise data. See more at :doc:`/userguide/real_and_lazy_data`. - The ``guess_coord_axis`` behaviour can be skipped by setting the coordinate - property ``ignore_axis`` to ``False``. + The ``guess_coord_axis`` behaviour can be skipped by setting the + :attr:`~iris.coords.Coord.ignore_axis` property on `coord` to ``False``. """ axis = None