Merge branch 'numpydoc-pre-commit' of github.com:tkknight/iris into numpydoc-pre-commit

* 'numpydoc-pre-commit' of github.com:tkknight/iris:
  Update CF standard names to v84. (SciTools#5761)
  Regrid docs fix (SciTools#5758)
  Improve ncdata and CF information on "iris heart xarray" page (SciTools#5752)
  Pin ASV - airspeed-velocity/asv#1385. (SciTools#5756)
  Normalise units of coordinate bounds (SciTools#5746)
  Add "Which Regridder?" Documentation (SciTools#5742)
  Document `Coord.ignore_axis` (SciTools#5744)
  Disable navidation with keys for docs HTML theme options (SciTools#5747)
  Shapefile masking (SciTools#5470)
  [pre-commit.ci] pre-commit autoupdate (SciTools#5739)
  DOCS: Add whatsnew for ruff pydocstyle compliance (SciTools#5700)
  update docstring (SciTools#5737)
  Updated environment lockfiles (SciTools#5738)
  Consider NaNs equal when comparing cubes (SciTools#5713)

Author: tkknight

.github/workflows/benchmarks_run.yml

@@ -42,7 +42,7 @@ jobs:
 
       - name: Install ASV & Nox
         run: |
-          pip install asv nox
+          pip install "asv!=0.6.2" nox
 
       - name: Cache environment directories
         id: cache-env-dir

.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
     -   id: no-commit-to-branch
 
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.1.14"
+    rev: "v0.2.1"
     hooks:
     -   id: ruff
         types: [file, python]

docs/src/community/iris_xarray.rst

@@ -38,9 +38,28 @@ There are multiple ways to convert between Iris and Xarray objects.
   feasible to save a NetCDF file using one package then load that file using
   the other package. This will be lossy in places, as both Iris and Xarray
   are opinionated on how certain NetCDF concepts relate to their data models.
-* The Iris development team are exploring an improved 'bridge' between the two
-  packages. Follow the conversation on GitHub: `iris#4994`_. This project is
-  expressly intended to be as lossless as possible.
+* `ncdata <https://github.com/pp-mo/ncdata/blob/main/README.md>`_ is a package which
+  the Iris development team have developed to manage netcdf data, which can act as an
+  improved 'bridge' between Iris and Xarray :
+
+Ncdata can convert Iris cubes to an Xarray dataset, or vice versa, with minimal
+overhead and as lossless as possible.
+
+For example :
+
+.. code-block:: python
+
+      from ncdata.iris_xarray import cubes_from_xarray, cubes_to_xarray
+      cubes = cubes_from_xarray(dataset)
+      xrds = cubes_to_xarray(cubes)
+
+Ncdata avoids the feature limitations previously mentioned regarding Xarray's
+:meth:`~xarray.DataArray.to_iris` and :meth:`~xarray.DataArray.from_iris`,
+because it doesn't replicate any logic of either Xarray or Iris.
+Instead, it uses the netcdf file interfaces of both to exchange data
+"as if" via a netcdf file.  So, these conversions *behave* just like exchanging data
+via a file, but are far more efficient because they can transfer data without copying
+arrays or fetching lazy data.
 
 Regridding
 ----------
@@ -98,7 +117,7 @@ Iris :class:`~iris.cube.Cube`\ s, although an ambition for the future.
 
 NetCDF File Control
 -------------------
-(More info: :term:`NetCDF Format`)
+(More info: :ref:`netcdf_io`)
 
 Unlike Iris, Xarray generally provides full control of major file structures,
 i.e. dimensions + variables, including their order in the file.  It mostly
@@ -107,15 +126,41 @@ However, attribute handling is not so complete: like Iris, it interprets and
 modifies some recognised aspects, and can add some extra attributes not in the
 input.
 
-.. todo:
-    More detail on dates and fill values (@pp-mo suggestion).
-
-Handling of dates and fill values have some special problems here.
-
-Ultimately, nearly everything wanted in a particular desired result file can
-be achieved in Xarray, via provided override mechanisms (`loading keywords`_
+Whereas Iris is primarily designed to handle netCDF data encoded according to
+`CF Conventions <https://cfconventions.org/>`_ , this is not so important to Xarray,
+which therefore may make it harder to correctly manage this type of data.
+While Xarray CF support is not complete, it may improve, and obviously
+:ref:`cfxarray` may be relevant here.
+There is also relevant documentation
+`at this page <https://docs.xarray.dev/en/stable/user-guide/weather-climate.html#weather-and-climate-data>`_.
+
+In some particular aspects, CF data is not loaded well (or at all), and in many cases
+output is not fully CF compliant (as-per `the cf checker <https://cfchecker.ncas.ac.uk/>`_).
+
+* xarray has it's own interpretation of coordinates, which is different from the CF-based
+  approach in Iris, and means that the use of the "coordinates" attribute in output is
+  often not CF compliant.
+* dates are converted to datetime-like objects internally.  There are special features
+  providing `support for  non-standard calendars <https://docs.xarray.dev/en/stable/user-guide/weather-climate.html#non-standard-calendars-and-dates-outside-the-nanosecond-precision-range>`_,
+  however date units may not always be saved correctly.
+* CF-style coordinate bounds variables are not fully understood.  The CF approach
+  where bounds variables do not usually define their units or standard_names can cause
+  problems.  Certain files containing bounds variables with more than 2 bounds (e.g.
+  unstructured data) may not load at all.
+* missing points are always represented as NaNs, as-per Pandas usage.
+  (See :ref:`xarray_missing_data` ).
+  This means that fill values are not preserved, and that masked integer data is
+  converted to floats.
+  The netCDF default fill-values are not supported, so that variables with no
+  "_FillValue" attribute will have missing points equal to the fill-value
+  in place of NaNs.  By default, output variables generally have ``_FillValue = NaN``.
+
+Ultimately, however, nearly everything wanted in a particular desired result file
+**can** be achieved in Xarray, via provided override mechanisms (`loading keywords`_
 and the '`encoding`_' dictionaries).
 
+.. _xarray_missing_data:
+
 Missing Data
 ------------
 Xarray uses :data:`numpy.nan` to represent missing values and this will support

docs/src/conf.py

@@ -193,7 +193,8 @@ def _dotv(version):
 
 # sphinx.ext.todo configuration -----------------------------------------------
 # See https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
-todo_include_todos = True
+todo_include_todos = False
+todo_emit_warnings = False
 
 # sphinx.ext.autodoc configuration --------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options
@@ -244,6 +245,7 @@ def _dotv(version):
 intersphinx_mapping = {
     "cartopy": ("https://scitools.org.uk/cartopy/docs/latest/", None),
     "dask": ("https://docs.dask.org/en/stable/", None),
+    "iris-esmf-regrid": ("https://iris-esmf-regrid.readthedocs.io/en/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "python": ("https://docs.python.org/3/", None),
@@ -300,6 +302,7 @@ def _dotv(version):
     "footer_start": ["copyright", "sphinx-version"],
     "footer_end": ["custom_footer"],
     "navigation_depth": 3,
+    "navigation_with_keys": False,
     "show_toc_level": 2,
     "show_prev_next": True,
     "navbar_align": "content",
@@ -404,6 +407,7 @@ def _dotv(version):
     "https://biggus.readthedocs.io/",
     "https://stickler-ci.com/",
     "https://twitter.com/scitools_iris",
+    "https://stackoverflow.com/questions/tagged/python-iris",
 ]
 
 # list of sources to exclude from the build.

docs/src/further_topics/index.rst

@@ -17,4 +17,5 @@ Extra information on specific technical issues.
    missing_data_handling
    netcdf_io
    dask_best_practices/index
-   ugrid/index
+   ugrid/index
+   which_regridder_to_use

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