v2.0 (14 Feb 2018)

This document explains the changes made to Iris for this release (View all changes.)

Features

Dask Integration

The use of Biggus to provide support for virtual arrays and lazy evaluation within Iris has been replaced with Dask.

In addition the concept of lazy data, already used for the Cube data component, has now been extended to the data arrays of a Coord and an AuxCoordFactory.

This is a major feature enhancement, allowing Iris to leverage dask’s rich functionality and community knowledge.

In particular, Dask’s threaded, multiprocessing or distributed schedulers can be used in order to best utilise available compute and memory resource. For further details, see Real and Lazy Data.

  • Changes to the iris.cube.Cube:

    • The new core_data() method returns the real or lazy Cube data.

    • The new in-place arithmetic operators __iadd__, __idiv__, __imul__, __isub__, and __itruediv__ have been added to support Cube operations +=, /=, *=, and -=. Note that, for divison __future__.division is always in effect.

  • Changes to the iris.coords.Coord:

The iris.FUTURE has Arrived!

Throughout version 1 of Iris a set of toggles in iris.FUTURE were maintained. These toggles allowed certain “future” behaviour to be enabled. Since the future has now arrived in Iris 2, all existing toggles in iris.FUTURE now default to True.

  • iris.Future.cell_datetime_objects

    • Use of this FUTURE toggle is now deprecated.

    • iris.coords.Cell objects in time coordinates now contain datetime objects by default and not numbers. For example:

        >>> cube = iris.load_cube(iris.sample_data_path('air_temp.pp'))
  >>> print(cube.coord('time').cell(0).point)
      1998-12-01 00:00:00

This change particularly impacts constraining datasets on time. All time constraints
must now be constructed with datetime objects or :class:`~iris.time.PartialDateTime` objects.
See userguide section 2.2.1 for more details on producing time constraints.

  • iris.Future.netcdf_promote

    • Use of this FUTURE toggle is now deprecated.

    • Removed deprecated behaviour that does not automatically promote NetCDF variables to cubes. This change means that NetCDF variables that define reference surfaces for dimensionless vertical coordinates will always be promoted and loaded as independent cubes.

  • iris.Future.netcdf_no_unlimited

    • Use of this FUTURE toggle is now deprecated.

    • Removed deprecated behaviour that automatically set the length of the outer netCDF variable to ‘UNLIMITED’ on save. This change means that no cube dimension coordinates will be automatically saved as netCDF variables with ‘UNLIMITED’ length.

    • You can manually specify cube dimension coordinates to save with ‘UNLIMITED’ length. For example:

      >>> iris.save(my_cube, 'my_result_file.nc', unlimited_dimensions=['latitude'])

  • iris.Future.clip_latitudes

    • Use of this FUTURE toggle is now deprecated.

    • The iris.coords.Coord.guess_bounds() now limits the guessed bounds to [-90, 90] for latitudes by default. The ability to turn this behaviour off is now deprecated.

Bugs Fixed

  • Indexing or slicing an AuxCoord coordinate will return a coordinate with points and bounds data that are new copied arrays, rather than views onto those of the original parent coordinate.

  • Indexing or slicing a cell measure will return a new cell measure with data that is a new copied array, rather than a view onto the original parent cell measure.

  • Performing an in-place arithmetic add(), divide(), multiply(), or subtract() operation on a Cube with integer or boolean data with a float result will raise an ArithmeticError exception.

  • Lazy data now refers to absolute paths rather than preserving the form that was passed to iris.load functions. This means that it is possible to use relative paths at load, change working directory, and still expect to be able to load any un-loaded/lazy data. (#2325)

  • The order in which files are passed to iris.load functions is now the order in which they are processed. (#2325)

  • Loading from netCDF files with iris.load() will load a cube for each scalar variable, a variable that does not reference a netCDF dimension, unless that scalar variable is identified as a CF scalar coordinate, referenced from another data variable via the ‘coordinates’ attribute. Previously such data variables were ignored during load.

Incompatible Changes

  • The lazy_data() method no longer accepts any arguments. Setting lazy data should now be done with cube.data.

Significant Changes in Calculated Results

Due to the replacement of Biggus with Dask, as described above, the results of certain types of calculation may have significantly different values from those obtained in earlier versions. This is of a much greater order than the usual small changes in floating point results : it applies especially to any data with masked points, or of long integer types.

  • Due to concerns regarding maintainability and API consistency the iris.cube.Cube.share_data flag introduced in v1.13 has been removed. Intra-cube data sharing is a oft-requested feature that we will be targeting in a future Iris release.

  • Using convert_units() on a cube with unknown units will now result in a UnitConversionError being raised.

  • iris.fileformats.pp_rules has been renamed to iris.fileformats.pp_load_rules for consistency with the new iris.fileformats.pp_save_rules.

  • Fill values are no longer taken from the cube’s data attribute when it is a masked array.

  • When saving a cube or list of cubes in NetCDF format, a fill value or list of fill values can be specified via a new fill_value argument. If a list is supplied, each fill value will be applied to each cube in turn. If a fill_value argument is not specified, the default fill value for the file format and the cube’s data type will be used.

  • When saving to PP, the “standard” BMDI of -1e30 is now always applied in PPField generation. To save PP data with an alternative BMDI, use iris.fileformats.pp.save_pairs_from_cube() to generate PPFields, and modify these before saving them to file.

  • A ‘fill_value’ key can no longer be specified as part of the packing argument to iris.save when saving in netCDF format. Instead, a fill value or list of fill values should be specified as a separate fill_value argument if required.

  • If the packing argument to iris.save is a dictionary, an error is raised if it contains any keys other than ‘dtype’, ‘scale_factor’ and ‘add_offset’.

  • The deprecated iris.fileformats.grib was removed. All Iris GRIB functionality is now delivered through iris-grib.

  • In Iris v1 it was possible to configure Iris to log at import time through iris.config.LOGGING. This capability has been removed in Iris v2.

  • When coordinates have no well defined plot axis, iris.plot and iris.quickplot routines now use the order of the cube’s dimensions to determine the coordinates to plot as the x and y axis of a plot.

  • The cf_units dependency version has been updated to v1.2.0, which prints shorter unit strings. For example, the unit meter-second^-1 is now printed as m.s-1.

Deprecation

All deprecated functionality that was announced for removal in Iris 2.0 has been removed. In particular:

  • The deprecated keyword arguments coord and name have been removed from the iris.cube.Cube constructor.

  • The deprecated methods iris.cube.Cube.add_history, iris.cube.Cube.assert_valid and iris.cube.Cube.regridded have been removed from iris.cube.Cube.

  • The deprecated module iris.fileformats.pp_packing has been removed.

  • The deprecated module iris.proxy has been removed.

  • The deprecated configuration variable SAMPLE_DATA_DIR has been removed from iris.config in favour of user installation of the iris-sample-data package.

  • The deprecated module iris.unit has been removed in favour of cf_units.

  • The BitwiseInt class has been removed from iris.fileformats.pp.

  • Removed deprecated functions reset_load_rules, add_save_rules, reset_save_rules and as_pairs from iris.fileformats.pp.

  • The deprecated module iris.analysis.interpolate has been removed, along with the following deprecated classes and functions:

    • iris.analysis.interpolate.linear

    • iris.analysis.interpolate.nearest_neighbour_data_value

    • iris.analysis.interpolate.regrid

    • iris.analysis.interpolate.regrid_to_max_resolution

    • iris.analysis.interpolate.extract_nearest_neighbour

    • iris.analysis.interpolate.nearest_neighbour_indices

    • iris.analysis.interpolate.Linear1dExtrapolator

  • Removed deprecated module iris.experimental.fieldsfile. Note that there is no direct replacement for :meth:iris.experimental.fieldsfile.load, which specifically performed fast loading from _either_ PP or FF files. Instead, please use the :meth:iris.fileformats.um.structured_um_loading context manager, and within that context call :meth:iris.load, or the format-specific :meth:iris.fileformats.pp.load_cubes or :meth:iris.fileformats.um.load_cubes.

  • Removed deprecated module iris.fileformats.ff. Please use facilities in iris.fileformats.um instead.

  • Removed deprecated and unused kwarg ignore from the following functions:

  • Deprecated functions iris.util.broadcast_weights, iris.util.ensure_array and iris.util.timers have been removed from iris.util.

  • The following classes and functions have been removed from iris.fileformats.rules:

    • iris.fileformat.rules.calculate_forecast_period

    • iris.fileformat.rules.log

    • iris.fileformat.rules.CMAttribute

    • iris.fileformat.rules.CMCustomAttribute

    • iris.fileformat.rules.CoordAndDims

    • iris.fileformat.rules.DebugString

    • iris.fileformat.rules.FunctionRule

    • iris.fileformat.rules.ProcedureRule

    • iris.fileformat.rules.Rule

    • iris.fileformat.rules.RulesContainer

    • iris.fileformat.rules.RuleResult

  • In addition the deprecated keyword argument legacy_custom_rules has been removed from the iris.fileformats.rules.Loader constructor.

Documentation

previous

v2.1 (06 Jun 2018)

next

v1.13 (17 May 2017)