What's New in Iris 2.2
************************

:Release: 2.2.0
:Date:


This document explains the new/changed features of Iris in the release
of version 2.2
(:doc:`View all changes <index>`).


Iris 2.2 Features
===================
.. _showcase:

.. admonition:: 2-Dimensional Coordinate Plotting

  The Iris plot functions :func:`~iris.plot.pcolor` and
  :func:`~iris.plot.pcolormesh` now accommodate the plotting of 2-dimensional
  coordinates as well as 1-dimensional coordinates.

  To enable this feature, each coordinate passed in for plotting will be
  automatically checked for contiguity.  Coordinate bounds must either be
  contiguous, or the cube's data must be masked at the discontiguities in
  order to avoid plotting errors.

  The Iris plot function :func:`iris.plot.quiver` has been added, and this
  also works with 2-dimensional plot coordinates.

.. admonition:: 2-Dimensional Grid Vectors

  The Iris functions :func:`iris.analysis.cartography.gridcell_angles` and
  :func:`iris.analysis.cartography.rotate_grid_vectors` have been added,
  allowing you to convert gridcell-oriented vectors to true-North/East ones.

.. admonition:: NetCDF Data Variable Chunk Sizes

  NetCDF data variable chunk sizes are now utilised at load time for
  significant performance improvements.

* The :class:`iris.fileformats.um.FieldCollation` objects, which are passed
  into load callbacks when using
  :func:`iris.fileformats.um.structured_um_loading`, now
  have the additional properties:
  :data:`iris.fileformats.um.FieldCollation.data_filepath` and
  :data:`iris.fileformats.um.FieldCollation.data_field_indices`.
  These provide the file locations of the original data fields, which are
  otherwise lost in the structured loading process.

* :func:`iris.util.reverse` can now be used to reverse a cube by specifying
  one or more coordinates.

* Time mean fields can now be saved to PP files as a cell method.

* Cube aggregators :func:`iris.analysis.MIN`, :func:`iris.analysis.MAX`,
  :func:`iris.analysis.SUM` and :func:`iris.analysis.COUNT` now perform lazy
  aggregation by utilizing dask.

* Error messages thrown upon failed addition of an
  :class:`~iris.aux_factory.AuxCoordFactory` now include the name of the
  required (but absent) coordinate as well as the name of the cube.

* The function :func:`iris.util.find_discontiguities` can be used to check for
  discontiguities in the bounds arrays of cube coordinates.  Additionally,
  discontiguous points in coordinates can be explicitly masked
  using another new feature :func:`iris.util.mask_cube`.


Iris 2.2 Dependency updates
=============================

* Iris is now using the latest version release of dask (currently 0.19.3)

* Proj4 has been temporarily pinned to version < 5 while problems with the
  Mollweide projection are addressed.

* Matplotlib has been pinned to version < 3 temporarily while we account for
  its changes in all SciTools libraries.


Bugs Fixed
==========

* The bug has been fixed that prevented printing time coordinates with bounds
  when the time coordinate was measured on a long interval (that is, ``months``
  or ``years``).

* "Gracefully filling..." warnings are now only issued when the coordinate or
  bound data is actually masked.

* Iris can now correctly unpack a column of header objects when saving a
  pandas DataFrame to a cube.


Documentation Changes
=====================

* Iris' `INSTALL` document has been updated to include guidance for running
  tests.

* A link has been added to the Developers' Guide to make it easier to find the
  Pull Request Check List.

