v3.0 (25 Jan 2021)#
This document explains the changes made to Iris for this release (View all changes.)
v3.0.0 Release Highlights
The highlights for this major release of Iris include:
We’ve finally dropped support for
Python 2
, so welcome toIris 3
andPython 3
!We’ve extended our coverage of the CF Conventions and Metadata by introducing support for CF Ancillary Data and Quality Flags,
Lazy regridding is now available for several regridding schemes,
Managing and manipulating metadata within Iris is now easier and more consistent thanks to the introduction of a new common metadata API,
Cube arithmetic has been significantly improved with regards to extended broadcasting, auto-transposition and a more lenient behaviour towards handling metadata and coordinates,
Our documentation has been refreshed, restructured, revitalised and rehosted on readthedocs,
It’s now easier than ever to install Iris as a user or a developer, and the newly revamped developers guide walks you though how you can get involved and contribute to Iris,
Also, this is a major release of Iris, so please be aware of the incompatible changes and deprecations.
And finally, get in touch with us on GitHub if you have any issues or feature requests for improving Iris. Enjoy!
v3.0.1 (27 Jan 2021)#
v3.0.1 Patches
The patches included in this release include:
💼 Internal
@bjlittle gracefully promote formula terms within
aux_factory
that haveunits
ofunknown
tounits
of1
(dimensionless), where the formula term must have dimensionlessunits
. Without this graceful treatment ofunits
the resultingCube
will not contain the expected auxiliary factory, and the associated derived coordinate will be missing. (PR #3965)
v3.0.2 (27 May 2021)#
v3.0.2 Patches
The patches included in this release include:
🐛 Bugs Fixed
@jonseddon handled a malformed
um_stash_source
CF variable attribute in a netCDF file rather than raising aValueError
. (PR #4035)@rcomer fixed
intersection()
for special cases where one cell’s bounds align with the requested maximum and minimum, as reported in Issue #3391. (PR #4059)@bjlittle resolved a regression in arithmetic behaviour between a coordinate and a cube which resulted in a
NotYetImplementedError
being raised, as reported in Issue #4000. This fix supports+
,-
,*
, and/
operations between a coordinate and a cube, and for convenience additionally includesiris.cube.Cube.__neg__()
support. (PR #4159)
📚 Documentation
@bjlittle updated the
intersphinx_mapping
and fixed documentation to usestable
URLs for matplotlib. (PR #4003) [pre-v3.1.0
]
💼 Internal
@jamesp updated a test to the latest numpy version (PR #3977) [
pre-v3.1.0
]@bjlittle enabled cirrus-ci compute credits for non-draft pull-requests from collaborators targeting the Iris
master
branch. (PR #4007) [pre-v3.1.0
]@bjlittle added conditional task execution to
.cirrus.yml
to allow developers to easily disable cirrus-ci tasks. (PR #4019) [pre-v3.1.0
]@pp-mo adjusted the use of
dask.array.from_array()
iniris._lazy_data.as_lazy_data()
, to avoid the dask ‘test access’. This makes loading of netcdf files with a large number of variables significantly faster. (PR #4135)@pp-mo reverted a change made previously in (PR #3659) to
iris.fileformats.pp.PPDataProxy.__getitem__()
. The check for empty slicings is no longer needed since (PR #4135) was added. (PR #4141)
Note that, the above contributions labelled with pre-v3.1.0
are part of the forthcoming
Iris v3.1.0 release, but require to be included in this patch release.
v3.0.3 (07 July 2021)#
v3.0.3 Patches
The patches included in this release include:
🐛 Bugs Fixed
@lbdreyer modified
intersection()
to use a tolerant equality check, when looking for cells that straddle the wrapping point. (PR #4220)
v3.0.4 (22 July 2021)#
v3.0.4 Patches
The patches included in this release include:
🐛 Bugs Fixed
@pp-mo fixed 2 bugs in cube printout: Firstly, ancillary-variables or cell-measures with long names can now widen the cube “dimensions map” to fit, whereas previously printing these cases caused an Exception. Secondly, cube units are now always printed, whereas previously they were missed out any time that the “dimensions map” was widened to accommodate long coordinate names. (PR #4233)(PR #4238)
💼 Internal
@bjlittle Unpinned the cftime package dependency within Iris in order to allow use of the latest versions of cftime, cf-units and nc-time-axis. (PR #4222)
@rcomer modified test modules so they run consistently under
pytest
andnose
, and also fixed some minor issues withPartialDateTime
. (PR #4249)
Note that, we are forced to drop support for Python 3.6
in this patch due to
the third-party package dependencies required by (PR #4222).
📢 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 loadingNimrod
data into cubes. This covers most known operational use-cases. (PR #3647)@stephenworsley improved the handling of
iris.coords.CellMeasure
s in theCube
statistical operationscollapsed()
,aggregated_by()
androlling_window()
. These previously removed everyCellMeasure
attached to the cube. Now, aCellMeasure
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 likeAuxCoord
s, with the newCube
methodsadd_ancillary_variable()
,remove_ancillary_variable()
,ancillary_variable()
,ancillary_variables()
andancillary_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
, andAreaWeighted
regridding schemes. (PR #3701)@bjlittle added logging support within
iris.analysis.maths
,iris.common.metadata
, andiris.common.resolve
. Each module defines alogging.Logger
instance calledlogger
with a defaultlevel
ofINFO
. To enableDEBUG
logging uselogger.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 twoCube
operands into a single resultantCube
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 asnp.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 aCube
is iterated over, while also ensuring thatTypeError
is still raised. (Fixed by setting the__iter__()
method inCube
toNone
). (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
CellMeasure
s inCube
copy operations. Previously copying aCube
would ignore any attachedCellMeasure
. (PR #3546)@bjlittle set a
CellMeasure
’smeasure
attribute to have a default value ofarea
. Previously, themeasure
was provided as a keyword argument toCellMeasure
with a default value ofNone
, which caused aTypeError
when nomeasure
was provided, sincearea
orvolume
are the only accepted values. (PR #3533)@trexfeathers set all plot types in
iris.plot
to now usematplotlib.dates.date2num
to format date/time coordinates for use on a plot axis (previouslypcolor()
andpcolormesh()
did not include this behaviour). (PR #3762)@trexfeathers changed date/time axis labels in
iris.quickplot
to now always be based on theepoch
used inmatplotlib.dates.date2num
(previously would take the unit from a time coordinate, if present, even though the coordinate’s value had been changed viadate2num
). (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 loadedCube
. (PR #3800)@pp-mo fixed the netcdf loader to now handle any grid-mapping variables with missing
false_easting
andfalse_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 the deprecated matplotlib
IndexFormatter
. (PR #3857)@znicholls fixed
_title()
to only checkunits.is_time_reference
if theunits
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 thestrict
keyword of theextract()
method have been removed, and are replaced by the new routinesextract_cube()
andextract_cubes()
. The new routines perform the same operation, but in a style more like otherIris
functions such asload_cube()
andload_cubes()
. Unlikestrict
extraction, the type of return value is now completely consistent :extract_cube()
always returns aCube
, andextract_cubes()
always returns aniris.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 theiris.experimental
module into theiris.util
module. Please use theiris.util.equalise_attributes()
function instead. (PR #3527)@bjlittle removed the module
iris.experimental.concatenate
. Inv1.6.0
the experimentalconcatenate
functionality was moved to theiris.cube.CubeList.concatenate()
method. Since then, calling theiris.experimental.concatenate.concatenate()
function raised an exception. (PR #3523)@stephenworsley changed the default units of
DimCoord
andAuxCoord
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 nounits
property. Previously these cases defaulted tounits='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 theiris.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 theiris.analysis.maths
API by changing its keyword argument fromother_cube
toother
. (PR #3785)@bjlittle changed the
iris.analysis.maths.IFunc.__call__()
to ignore any surplusother
keyword argument for adata_func
that requires only one argument. This aligns the behaviour ofiris.analysis.maths.IFunc.__call__()
withapply_ufunc()
. Previously aValueError
exception was raised. (PR #3785)
🔥 Deprecations#
@stephenworsley removed the deprecated
iris.Future
flagscell_date_time_objects
,netcdf_promote
,netcdf_no_unlimited
andclip_latitudes
. (PR #3459)@stephenworsley changed
iris.fileformats.pp.PPField.lbproc
to be anint
. The deprecated attributesflag1
,flag2
etc. have been removed from it. (PR #3461)@bjlittle deprecated
as_compatible_shape()
in preference forResolve
e.g.,Resolve(src, tgt)(tgt.core_data())
. Theas_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 exclusivePython3
support. (PR #3513)@bjlittle improved the developer set up process. Configuring Iris and Installing from Source with Conda (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 bothPython2
andPython3
had resulted in pinning our dependency on matplotlib atv2.x
. But this is no longer necessary now thatPython2
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 How to Create an Iris Release 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 theDownloads
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 Developers Guide 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 viamake html
. This will minimise technical debt accruing for the documentation. (PR #3877)@tkknight updated Installing to include a reference to Windows Subsystem for Linux. (PR #3885)
@tkknight updated the Iris 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 useagg
. (PR #3846)@bjlittle migrated the black support from
19.10b0
to20.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 overrideunittest.TestCase.assertDictEqual()
in order to cope with testing metadataattributes
dictionary comparison where the value of a key may be a numpy array. (PR #3785)@bjlittle added the
get_logger()
function for creating a genericlogging.Logger
with alogging.StreamHandler
and customlogging.Formatter
. (PR #3785)@owena11 identified and optimised a bottleneck in
FieldsFile
header loading due to the use ofnumpy.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. theresult_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)