v1.8 (14 Apr 2015)
******************

This document explains the changes made to Iris for this release
(:doc:`View all changes <index>`.)


Features
========

.. _showcase:

.. admonition:: Showcase: Rotate winds

    Iris can now rotate and unrotate wind vector data by transforming the wind
    vector data to another coordinate system.

    For example::

        >>> from iris.analysis.cartography import rotate_winds
        >>> u_cube = iris.load_cube('my_rotated_u_wind_cube.pp')
        >>> v_cube = iris.load_cube('my_rotated_v_wind_cube.pp')
        >>> target_cs = iris.coord_systems.GeogCS(6371229.0)
        >>> u_prime, v_prime = rotate_winds(u_cube, v_cube, target_cs)

.. admonition:: Showcase: Nearest-neighbour scheme

    A nearest-neighbour scheme for interpolation and regridding has been added
    to Iris. This joins the existing :class:`~iris.analysis.Linear` and
    :class:`~iris.analysis.AreaWeighted` interpolation and regridding schemes.

    For example::

        >>> result = cube.interpolate(sample_points, iris.analysis.Nearest())
        >>> regridded_cube = cube.regrid(target_grid, iris.analysis.Nearest())

.. admonition:: Showcase: Slices over a coordinate

    You can slice over one or more dimensions of a cube using
    :meth:`iris.cube.Cube.slices_over`.
    This provides similar functionality to :meth:`~iris.cube.Cube.slices`
    but with almost the opposite outcome.
    
    Using :meth:`~iris.cube.Cube.slices` to slice a cube on a selected
    dimension returns all possible slices of the cube with the selected
    dimension retaining its dimensionality.  Using
    :meth:`~iris.cube.Cube.slices_over` to slice a cube on a selected
    dimension returns all possible slices of the cube over the selected
    dimension. 
    
    To demonstrate this::

        >>> cube = iris.load(iris.sample_data_path('colpex.pp'))[0]
        >>> print(cube.summary(shorten=True))
        air_potential_temperature / (K)     (time: 6; model_level_number: 10; grid_latitude: 83; grid_longitude: 83)
        >>> my_slice = next(cube.slices('time'))
        >>> my_slice_over = next(cube.slices_over('time'))
        >>> print(my_slice.summary(shorten=True))
        air_potential_temperature / (K)     (time: 6)
        >>> print(my_slice_over.summary(shorten=True))
        air_potential_temperature / (K)     (model_level_number: 10; grid_latitude: 83; grid_longitude: 83)
    

* :func:`iris.cube.CubeList.concatenate` now works with
  `biggus <https://biggus.readthedocs.io/>`_ arrays and so
  now supports concatenation of cubes with deferred data.

* Improvements to NetCDF saving through using biggus:

 * A cube's lazy data payload will still be lazy after saving; the data will not
   be loaded into memory by the save operation.

 * Cubes with data payloads larger than system memory can now be saved to NetCDF
   through biggus streaming the data to disk.

* :func:`iris.util.demote_dim_coord_to_aux_coord` and
  :func:`iris.util.promote_aux_coord_to_dim_coord`
  allow a coordinate to be easily demoted or promoted within a cube.

* :func:`iris.util.squeeze` removes all length 1 dimensions from a cube, and
  demotes any associated squeeze dimension :class:`~iris.coords.DimCoord` to be
  a scalar coordinate.

* :meth:`iris.cube.Cube.slices_over`, which returns an iterator of all
  sub-cubes along a given coordinate or dimension index.

* :meth:`iris.cube.Cube.interpolate` now accepts datetime.datetime and 
  netcdftime.datetime instances for date or time coordinates.

* Many new and updated translations between CF spec and STASH codes or GRIB2
  parameter codes.

* PP/FF loader creates a height coordinate at 1.5m or 10m for certain relevant
  stash codes.

* Lazy aggregator support for the
  :class:`standard deviation <iris.analysis.STD_DEV>` aggregator has been added.

* A speed improvement in calculation of
  :func:`iris.analysis.cartography.area_weights`.

* Experimental support for unstructured grids has been added with
  :func:`iris.experimental.ugrid`. This has been implemented using
  `UGRID <https://github.com/pyugrid/pyugrid>`_.

* :meth:`iris.cube.CubeList.extract_overlapping` supports extraction of cubes
  over regions where common coordinates overlap, over multiple coordinates.

* Warnings raised due to invalid units in loaded data have been suppressed.

* Experimental low-level read and write access for FieldsFile variants is now
  supported via :class:`iris.experimental.um.FieldsFileVariant`.

* PP loader will return cubes for all fields prior to a field with a problematic
  header before raising an exception.

* NetCDF loader skips invalid global attributes, raising a warning rather than
  raising an exception.

* A warning is now raised rather than an exception when constructing an
  :class:`~iris.aux_factory.AuxCoordFactory` fails.

* Supported :class:`aux coordinate factories <iris.aux_factory.AuxCoordFactory>`
  have been extended to include:

 * ``ocean sigma coordinate``,
 * ``ocean s coordinate``,
 * ``ocean s coordinate, generic form 1``, and
 * ``ocean s coordinate, generic form 2``.

* :meth:`iris.cube.Cube.intersection` now supports taking a points-only
  intersection. Any bounds on intersected coordinates are ignored but retained.

* The FF loader's known handled grids now includes ``Grid 21``.

* A :class:`nearest neighbour <iris.analysis.Nearest>` scheme is now provided
  for :meth:`iris.cube.Cube.interpolate` and :meth:`iris.cube.Cube.regrid`. 

* :func:`iris.analysis.cartography.rotate_winds` supports transformation of
  wind vectors to a different coordinate system.

* NumPy universal functions can now be applied to cubes using
  :func:`iris.analysis.maths.apply_ufunc`.

* Generic functions can be applied to :class:`~iris.cube.Cube` instances using 
  :class:`iris.analysis.maths.IFunc`. 

* The :class:`iris.analysis.Linear` scheme now supports regridding as well as
  interpolation. This enables :meth:`iris.cube.Cube.regrid` to perform bilinear
  regridding, which now replaces the experimental routine
  "iris.experimental.regrid.regrid_bilinear_rectilinear_src_and_grid".


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

* Fix in netCDF loader to correctly determine whether the longitude coordinate
  (including scalar coordinates) is circular.

* :meth:`iris.cube.Cube.intersection` now supports bounds that extend slightly
  beyond 360 degrees.

* Lateral Boundary Condition (LBC) type FieldFiles are now handled correctly by
  the FF loader.

* Making a copy of a scalar cube with no data now correctly copies the data
  array.

* Height coordinates in NAME trajectory output files have been changed to match
  other NAME output file formats.

* Fixed datatype when loading an ``integer_constants`` array from a FieldsFile.

* FF/PP loader adds appropriate cell methods for ``lbtim.ib = 3`` intervals.

* An exception is raised if the units of the latitude and longitude coordinates
  of the cube passed into :func:`iris.analysis.cartography.area_weights` are not
  convertible to radians.

* GRIB1 loader now creates a time coordinate for a time range indicator of 2.

* NetCDF loader now loads units that are empty strings as dimensionless.


v1.8.1 (03 Jun 2015)
--------------------

* The PP loader now carefully handles floating point errors in date time
  conversions to hours.

* The handling fill values for lazy data loaded from NetCDF files is altered,
  such that the _FillValue set in the file is preserved through lazy operations.

* The risk that cube intersections could return incorrect results due to
  floating point tolerances is reduced.

* The new GRIB2 loading code is altered to enable the loading of various data
  representation templates; the data value unpacking is handled by the GRIB API.

* Saving cube collections to NetCDF, where multiple similar aux-factories exist
  within the cubes, is now carefully handled such that extra file variables are
  created where required in some cases.


Deprecations
============

* The original GRIB loader has been deprecated and replaced with a new
  template-based GRIB loader.

* Deprecated default NetCDF save behaviour of assigning the outermost
  dimension to be unlimited.  Switch to the new behaviour with no auto
  assignment by setting :data:`iris.FUTURE.netcdf_no_unlimited` to True.

* The former experimental method
  "iris.experimental.regrid.regrid_bilinear_rectilinear_src_and_grid" has been
  removed, as :class:`iris.analysis.Linear` now includes this functionality.


Documentation
=============

* A chapter on :doc:`merge and concatenate </userguide/merge_and_concat>` has
  been added to the :doc:`user guide </userguide/index>`.

* A section on installing Iris using `conda <http://conda.pydata.org/>`_ has
  been added to the :doc:`install guide </installing>`.

* Updates to the chapter on
  :doc:`regridding and interpolation </userguide/interpolation_and_regridding>`
  have been added to the :doc:`user guide </userguide/index>`.
