What's New in Iris 2.1
**********************

:Release: 2.1
:Date: 2018-06-06

This document explains the new/changed features of Iris in version 2.1
(:doc:`older "What's New" release notes can be found here<index>`.)


Iris 2.1 Dependency updates
===========================

* The `cf_units <https://github.com/SciTools/cf_units>`_ dependency
  was updated to cf_units ``v2.0``.
  cf_units v2 is almost entirely backwards compatible with v1.
  However the ability to preserve some aliased calendars has been removed.
  For this reason, it is possible that NetCDF load of a variable with a
  "standard" calendar will result in a saved NetCDF of a "gregorian"
  calendar.
* Iris updated its time-handling functionality from the
  `netcdf4-python <http://unidata.github.io/netcdf4-python/>`_
  ``netcdftime`` implementation to the standalone module
  `cftime <https://github.com/Unidata/cftime>`_.
  cftime is entirely compatible with netcdftime, but some issues may
  occur where users are constructing their own datetime objects.
  In this situation, simply replacing ``netcdftime.datetime`` with
  ``cftime.datetime`` should be sufficient.
* Iris now requires version 2 of Matplotlib, and ``>=1.14`` of NumPy.
  Full requirements can be seen in the `requirements <https://github.com/SciTools/iris/>`_
  directory of the Iris' the source.

Iris 2.1 Features
=================

* Added ``repr_html`` functionality to the :class:`~iris.cube.Cube` to provide
  a rich html representation of cubes in Jupyter notebooks. Existing functionality
  of ``print(cube)`` is maintained.

  .. image:: images/notebook_repr.png

* Updated :func:`iris.cube.Cube.name` to return a STASH code if the cube has
  one and no other valid names are present. This is now consistent with the
  summary information from :func:`iris.cube.Cube.summary`.
* The partial collapse of multi-dimensional auxiliary coordinates is now
  supported. Collapsed bounds span the range of the collapsed dimension(s).
* Added new function :func:`iris.cube.CubeList.realise_data` to compute
  multiple lazy values in a single operation, avoiding repeated re-loading of
  data or re-calculation of expressions.
* The methods :meth:`iris.cube.Cube.convert_units` and
  :meth:`iris.coords.Coord.convert_units` no longer forcibly realise the cube
  data or coordinate points/bounds. The converted values are now lazy arrays
  if the originals were.
* Added :meth:`iris.analysis.trajectory.interpolate` that allows you to
  interpolate to find values along a trajectory.
* It is now possible to add an attribute of ``missing_value`` to a cube
  (:issue:`1588`).
* Iris can now represent data on the Albers Equal Area Projection,
  and the NetCDF loader and saver were updated to handle this. (:issue:`2943`)
* The :class:`~iris.coord_systems.Mercator` projection has been updated to accept
  the ``standard_parallel`` keyword argument (:pull:`3041`).

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

* All var names being written to NetCDF are now CF compliant.
  Non alpha-numeric characters are replaced with '_', and var names now always
  have a leading letter (:pull:`2930`).
* A cube resulting from a regrid operation using the `iris.analysis.AreaWeighted`
  regridding scheme will now have the smallest floating point data type
  to which the source cube's data type can be safely converted using NumPy's
  type promotion rules.
* :mod:`iris.quickplot` labels now honour the axes being drawn to when using the
  ``axes`` keyword (:pull:`3010`).

Incompatible Changes
====================
* The deprecated :mod:`iris.experimental.um` was removed.
  Please use consider using `mule <https://github.com/SciTools/mule>`_
  as an alternative.
