v3.0.1 (27 Jan 2021)¶

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

📢 Announcements¶

Congratulations to @bouweandela, @jvegasbsc, and @zklaus who recently became Iris core developers. They bring a wealth of expertise to the team, and are using Iris to underpin ESMValTool - “A community diagnostic and performance metrics tool for routine evaluation of Earth system models in CMIP”. Welcome aboard! 🎉
Congratulations also goes to @jonseddon who recently became an Iris core developer. We look forward to seeing more of your awesome contributions! 🎉

✨ Features¶

@MoseleyS greatly enhanced the nimrod module to provide richer meta-data translation when loading Nimrod data into cubes. This covers most known operational use-cases. (PR #3647)
@stephenworsley improved the handling of iris.coords.CellMeasures in the Cube statistical operations collapsed(), aggregated_by() and rolling_window(). These previously removed every CellMeasure attached to the cube. Now, a CellMeasure will only be removed if it is associated with an axis over which the statistic is being run. (PR #3549)
@stephenworsley, @pp-mo and @abooton added support for CF Ancillary Data variables. These are created as iris.coords.AncillaryVariable, and appear as components of cubes much like AuxCoords, with the new Cube methods add_ancillary_variable(), remove_ancillary_variable(), ancillary_variable(), ancillary_variables() and ancillary_variable_dims(). They are loaded from and saved to NetCDF-CF files. Special support for Quality Flags is also provided, to ensure they load and save with appropriate units. (PR #3800)
@bouweandela implemented lazy regridding for the Linear, Nearest, and AreaWeighted regridding schemes. (PR #3701)
@bjlittle added logging support within iris.analysis.maths, iris.common.metadata, and iris.common.resolve. Each module defines a logging.Logger instance called logger with a default level of INFO. To enable DEBUG logging use logger.setLevel("DEBUG"). (PR #3785)
@bjlittle added the iris.common.resolve module, which provides infrastructure to support the analysis, identification and combination of metadata common between two Cube operands into a single resultant Cube that will be auto-transposed, and with the appropriate broadcast shape. (PR #3785)
@bjlittle added the common metadata API, which provides a unified treatment of metadata across Iris, and allows users to easily manage and manipulate their metadata in a consistent way. (PR #3785)
@bjlittle added lenient metadata support, to allow users to control strict or lenient metadata equivalence, difference and combination. (PR #3785)
@bjlittle added lenient cube maths support and resolved several long standing major issues with cube arithmetic regarding a more robust treatment of cube broadcasting, cube dimension auto-transposition, and preservation of common metadata and coordinates during cube math operations. Resolves Issue #1887, Issue #2765, and Issue #3478. (PR #3785)
@pp-mo and @TomekTrzeciak enhanced collapse() to allow a 1-D weights array when collapsing over a single dimension. Previously, the weights had to be the same shape as the whole cube, which could cost a lot of memory in some cases. The 1-D form is supported by most weighted array statistics (such as np.average()), so this now works with the corresponding Iris schemes (in that case, MEAN). (PR #3943)

🐛 Bugs Fixed¶

@stephenworsley fixed remove_coord() to now also remove derived coordinates by removing aux_factories. (PR #3641)
@jonseddon fixed isinstance(cube, collections.Iterable) to now behave as expected if a Cube is iterated over, while also ensuring that TypeError is still raised. (Fixed by setting the __iter__() method in Cube to None). (PR #3656)
@stephenworsley enabled cube concatenation along an axis shared by cell measures; these cell measures are now concatenated together in the resulting cube. Such a scenario would previously cause concatenation to inappropriately fail. (PR #3566)
@stephenworsley newly included CellMeasures in Cube copy operations. Previously copying a Cube would ignore any attached CellMeasure. (PR #3546)
@bjlittle set a CellMeasure’s measure attribute to have a default value of area. Previously, the measure was provided as a keyword argument to CellMeasure with a default value of None, which caused a TypeError when no measure was provided, since area or volume are the only accepted values. (PR #3533)
@trexfeathers set all plot types in iris.plot to now use matplotlib.dates.date2num to format date/time coordinates for use on a plot axis (previously pcolor() and pcolormesh() did not include this behaviour). (PR #3762)
@trexfeathers changed date/time axis labels in iris.quickplot to now always be based on the epoch used in matplotlib.dates.date2num (previously would take the unit from a time coordinate, if present, even though the coordinate’s value had been changed via date2num). (PR #3762)
@pp-mo newly included attributes of cell measures in NETCDF-CF file loading; they were previously being discarded. They are now available on the CellMeasure in the loaded Cube. (PR #3800)
@pp-mo fixed the netcdf loader to now handle any grid-mapping variables with missing false_easting and false_northing properties, which was previously failing for some coordinate systems. See Issue #3629. (PR #3804)
@stephenworsley changed the way tick labels are assigned from string coords. Previously, the first tick label would occasionally be duplicated. This also removes the use of Matplotlib’s deprecated IndexFormatter. (PR #3857)
@znicholls fixed _title() to only check units.is_time_reference if the units symbol is not used. (PR #3902)
@rcomer fixed a bug whereby numpy array type attributes on a cube’s coordinates could prevent printing it. See Issue #3921. (PR #3922)

💣 Incompatible Changes¶

@pp-mo rationalised CubeList extraction methods:

The former method iris.cube.CubeList.extract_strict, and the strict keyword of the extract() method have been removed, and are replaced by the new routines extract_cube() and extract_cubes(). The new routines perform the same operation, but in a style more like other Iris functions such as load_cube() and load_cubes(). Unlike strict extraction, the type of return value is now completely consistent : extract_cube() always returns a Cube, and extract_cubes() always returns an iris.cube.CubeList of a length equal to the number of constraints. (PR #3715)
@pp-mo removed the former function iris.analysis.coord_comparison. (PR #3562)
@bjlittle moved the iris.experimental.equalise_cubes.equalise_attributes() function from the iris.experimental module into the iris.util module. Please use the iris.util.equalise_attributes() function instead. (PR #3527)
@bjlittle removed the module iris.experimental.concatenate. In v1.6.0 the experimental concatenate functionality was moved to the iris.cube.CubeList.concatenate() method. Since then, calling the iris.experimental.concatenate.concatenate() function raised an exception. (PR #3523)
@stephenworsley changed the default units of DimCoord and AuxCoord from “1” to “unknown”. (PR #3795)
@stephenworsley changed Iris objects loaded from NetCDF-CF files to have units='unknown' where the corresponding NetCDF variable has no units property. Previously these cases defaulted to units='1'. This affects loading of coordinates whose file variable has no “units” attribute (not valid, under CF units rules): These will now have units of “unknown”, rather than “1”, which may prevent the creation of a hybrid vertical coordinate. While these cases used to “work”, this was never really correct behaviour. (PR #3795)
@SimonPeatman added attribute var_name to coordinates created by the iris.analysis.trajectory.interpolate() function. This prevents duplicate coordinate errors in certain circumstances. (PR #3718)
@bjlittle aligned the iris.analysis.maths.apply_ufunc() with the rest of the iris.analysis.maths API by changing its keyword argument from other_cube to other. (PR #3785)
@bjlittle changed the iris.analysis.maths.IFunc.__call__() to ignore any surplus other keyword argument for a data_func that requires only one argument. This aligns the behaviour of iris.analysis.maths.IFunc.__call__() with apply_ufunc(). Previously a ValueError exception was raised. (PR #3785)

🔥 Deprecations¶

@stephenworsley removed the deprecated iris.Future flags cell_date_time_objects, netcdf_promote, netcdf_no_unlimited and clip_latitudes. (PR #3459)
@stephenworsley changed iris.fileformats.pp.PPField.lbproc to be an int. The deprecated attributes flag1, flag2 etc. have been removed from it. (PR #3461)
@bjlittle deprecated as_compatible_shape() in preference for Resolve e.g., Resolve(src, tgt)(tgt.core_data()). The as_compatible_shape() function will be removed in a future release of Iris. (PR #3892)

🔗 Dependencies¶

@stephenworsley, @trexfeathers and @bjlittle removed Python2 support, modernising the codebase by switching to exclusive Python3 support. (PR #3513)
@bjlittle improved the developer set up process. Configuring Iris and Installing From Source (Developers) as a developer with all the required package dependencies is now easier with our curated conda environment YAML files. (PR #3812)
@stephenworsley pinned Iris to require Dask >=2.0. (PR #3460)
@stephenworsley and @trexfeathers pinned Iris to require Cartopy >=0.18, in order to remain compatible with the latest version of Matplotlib. (PR #3762)
@bjlittle unpinned Iris to use the latest version of Matplotlib. Supporting Iris for both Python2 and Python3 had resulted in pinning our dependency on Matplotlib at v2.x. But this is no longer necessary now that Python2 support has been dropped. (PR #3468)
@stephenworsley and @trexfeathers unpinned Iris to use the latest version of Proj. (PR #3762)
@stephenworsley and @trexfeathers removed GDAL from the extensions dependency group. We no longer consider it to be an extension. (PR #3762)

📚 Documentation¶

@tkknight moved the Tri-Polar Grid Projected Plotting from the general part of the gallery to oceanography. (PR #3761)
@tkknight updated documentation to use a modern sphinx theme and be served from https://scitools-iris.readthedocs.io/en/latest/. (PR #3752)
@bjlittle added support for the black code formatter. This is now automatically checked on GitHub PRs, replacing the older, unittest-based iris.tests.test_coding_standards.TestCodeFormat. Black provides automatic code format correction for most IDEs. See the new developer guide section on Code Formatting. (PR #3518)
@tkknight and @trexfeathers refreshed the Contributing a “What’s New” Entry for the What’s New in Iris. This includes always creating the latest what’s new page so it appears on the latest documentation at https://scitools-iris.readthedocs.io/en/latest/whatsnew. This resolves Issue #2104, Issue #3451, Issue #3818, Issue #3837. Also updated the Maintainer Steps to follow when making a release. (PR #3769, PR #3838, PR #3843)
@tkknight enabled the PDF creation of the documentation on the Read the Docs service. The PDF may be accessed by clicking on the version at the bottom of the side bar, then selecting PDF from the Downloads section. (PR #3765)
@stephenworsley added a warning to the iris.analysis.cartography.project() function regarding its behaviour on projections with non-rectangular boundaries. (PR #3762)
@stephenworsley added the Combining Units section to the user guide to clarify how Units are handled during cube arithmetic. (PR #3803)
@tkknight overhauled the Further Topics including information on getting involved in becoming a contributor and general structure of the guide. This resolves Issue #2170, Issue #2331, Issue #3453, Issue #314, Issue #2902. (PR #3852)
@rcomer added argument descriptions to the DimCoord docstring. (PR #3681)
@tkknight added two url’s to be ignored for the make linkcheck. This will ensure the Iris github project is not repeatedly hit during the linkcheck for issues and pull requests as it can result in connection refused and thus travis-ci job failures. For more information on linkcheck, see Testing. (PR #3873)
@tkknight enabled the napolean package that is used by sphinx to cater for the existing google style docstrings and to also allow for numpy docstrings. This resolves Issue #3841. (PR #3871)
@tkknight configured sphinx-build to promote warnings to errors when building the documentation via make html. This will minimise technical debt accruing for the documentation. (PR #3877)
@tkknight updated Installing Iris to include a reference to Windows Subsystem for Linux. (PR #3885)
@tkknight updated the Iris Documentation homepage to include panels so the links are more visible to users. This uses the sphinx-panels extension. (PR #3884)
@bjlittle created the Further topics section and included documentation for Metadata, Lenient Metadata, and Lenient Cube Maths. (PR #3890)
@jonseddon updated the CF version of the netCDF saver in the Saving Iris Cubes section and in the equivalent function docstring. (PR #3925)
@bjlittle applied Title Case Capitalization to the documentation. (PR #3940)

💼 Internal¶

@pp-mo and @lbdreyer removed all Iris test dependencies on iris-grib by transferring all relevant content to the iris-grib repository. (PR #3662, PR #3663, PR #3664, PR #3665, PR #3666, PR #3669, PR #3670, PR #3671, PR #3672, PR #3742, PR #3746)
@lbdreyer and @pp-mo overhauled the handling of dimensional metadata to remove duplication. (PR #3422, PR #3551)
@trexfeathers simplified the standard license header for all files, which removes the need to repeatedly update year numbers in the header. (PR #3489)
@stephenworsley changed the numerical values in tests involving the Robinson projection due to improvements made in Proj. (PR #3762) (see also Proj#1292 and Proj#2151)
@stephenworsley changed tests to account for more detailed descriptions of projections in GDAL. (PR #3762) (see also GDAL#1185)
@stephenworsley changed tests to account for GDAL now saving fill values for data without masked points. (PR #3762)
@trexfeathers changed every graphics test that includes Cartopy’s coastlines to account for new adaptive coastline scaling. (PR #3762) (see also Cartopy#1105)
@trexfeathers changed graphics tests to account for some new default grid-line spacing in Cartopy. (PR #3762) (see also Cartopy#1117)
@trexfeathers added additional acceptable graphics test targets to account for very minor changes in Matplotlib version 3.3 (colormaps, fonts and axes borders). (PR #3762)
@rcomer corrected the Matplotlib backend in Iris tests to ignore matplotlib.rcdefaults, instead the tests will always use agg. (PR #3846)
@bjlittle migrated the black support from 19.10b0 to 20.8b1. (PR #3866)
@lbdreyer updated the CF standard name table to the latest version: v75. (PR #3867)
@bjlittle added PEP 517 and PEP 518 support for building and installing Iris, in particular to handle the PyKE package dependency. (PR #3812)
@bjlittle added metadata support for comparing attributes dictionaries that contain numpy arrays using xxHash, an extremely fast non-cryptographic hash algorithm, running at RAM speed limits.
@bjlittle added the iris.tests.assertDictEqual method to override unittest.TestCase.assertDictEqual() in order to cope with testing metadata attributes dictionary comparison where the value of a key may be a numpy array. (PR #3785)
@bjlittle added the get_logger() function for creating a generic logging.Logger with a logging.StreamHandler and custom logging.Formatter. (PR #3785)
@owena11 identified and optimised a bottleneck in FieldsFile header loading due to the use of numpy.fromfile(). (PR #3791)
@znicholls added a test for plotting with the label being taken from the unit’s symbol, see test_pcolormesh_str_symbol() (PR #3902).
@znicholls made step_over_diffs() robust to hyphens (-) in the input path (i.e. the result_dir argument) (PR #3902).
@bjlittle migrated the CIaaS from travis-ci to cirrus-ci, and removed stickler-ci support. (PR #3928)
@bjlittle introduced nox as a common and easy entry-point for test automation. It can be used both from cirrus-ci in the cloud, and locally by the developer to run the Iris tests, the doc-tests, the gallery doc-tests, and lint Iris with flake8 and black. (PR #3928)