3.21.0

Version 3.21.0

2026-08-28

• New keywords to cf.read: backend, backend_options, cfa_filesystem, cfa_backend, cfa_backend_options (#961)
• Deprecated keyword to cfdm.read: netcdf_backend (#961)
• Dataset reads are now entirely managed by xnetcdf and its backend libraries (via cfdm.read) (#961)
• Read with cf.read anything that can be read by xarray (#961)
• Convert xarray.Dataset and xarray.DataTree to cf.Field via cf.read (#961)
• Convert pyfive.File, zarr.Group, h5py.File, umfile.File, and xnetcdf.Dataset to cf.Field via cf.read (#961)
• Extend cf.Field.create_latlon_coordinates to allow the creation of 2-d latitudes/longitudes from plane projection and rotated pole coordinates (#962)
• Automatically create consolidated HDF5 metadata with cf.write. New keywords to cf.write: hdf5_consolidated_metadata and hdf5_expansion_factor (NCAS-CMS/cfdm#413)
• In cf.write, set sensible dataset chunksizes by default for 1-d data, controlled by the new one_d_chunks keyword (NCAS-CMS/cfdm#414)
• New methods to convert to xarray: cf.Field.to_xarray, cf.FieldList.to_xarray, cf.Domain.to_xarray, and cf.DomainList.to_xarray (#933)
• New output format for cf.write that creates an xarray dataset in memory: 'XARRAY' (#933)
• Introduce use of cache files stored as ~/.cf/standard_names*.pickle to improve performance of CF compliance checking (NCAS-CMS/cfdm#411)
• New optional dependency: umfive>=0.3.0
• New optional dependency: xarray>=2026.7.0
• Changed dependency: cfdm>=1.13.3.0, <1.13.4.0

What's Changed

• Convert to xarray by @davidhassell in #935
• API reference: detect missing class pages & populate all gaps by @sadielbartholomew in #959
• xnetcdf and 2-d lat/lon coordinates by @davidhassell in #963

Full Changelog: v3.20.1...v3.21.0

3.20.1

2026-07-07

• New keyword parameter to cf.Field.regrids and cf.Field.regridc: mtol (#949)
• Fix bug in cf.read that prevented some OPeNDAP URLS being read (#948)
• Fix bug that caused weighted cf.collapse and cf.weights to fail when a cell measures has a size 1 axis (#952)
• Changed dependency: cfdm>=1.13.2.1, <1.13.3.0

What's Changed

• Fix bug in cf.read that prevented some OPeNDAP URLS being read by @davidhassell in #951
• Test skipping based on module (esp. healpix) availability by @sadielbartholomew in #944
• Fix bug that caused weighted cf.collapse and cf.weights to fail when a cell meausures has a size 1 axis by @davidhassell in #954
• New keyword parameter to cf.Field.regrids and cf.Field.regridc: max_masked by @davidhassell in #950

Full Changelog: v3.20.0...v3.20.1

3.20.0

2026-04-10

• Read Kerchunk datasets with cf.read (#936)
• Read open file handle datasets with cf.read (#937)
• Write UGRID datasets with cf.write (#697)
• Support for HEALPix grids (#909)
• New HEALPix methods: cf.Field.healpix_info, cf.Field.healpix_decrease_refinement_level, cf.Field.healpix_increase_refinement_level, cf.Field.healpix_change_indexing_scheme, cf.Field.healpix_to_ugrid, cf.Domain.create_healpix (#909)
• New method: cf.Field.create_latlon_coordinates (#909)
• New method: cf.Data.coarsen (#909)
• New functions: cf.locate, cf.healpix_max_refinement_level, cf.healpix_indexing_schemes (#909)
• New keyword to cf.read: filesystem (#931)
• New keyword parameter to cf.Data.compute: persist (#929)
• New function to control the persistence of computed data: cf.persist_data (#929)
• New default backend for netCDF-4 in cf.write: h5netcdf-h5py, that allows control of the internal file metadata via the new h5py_options parameter (#924)
• New default backend for netCDF-4 in cf.read that allows parallel reading: h5netcdf-pyfive (#912)
• New optional backend for netCDF-3 in cf.read that allows parallel reading: netcdf_file (#912)
• Fix bug in cf.read that wouldn't read non-Zarr and Zarr datasets from the same directory (NCAS-CMS/cfdm#391)
• Fix for subspacing with cyclic cf.wi and cf.wo arguments (#887)
• New optional dependency: healpix>=2025.1
• New dependency: pyfive>=1.1.1
• Changed dependency: cfdm>=1.13.1.0, <1.13.2.0

What's Changed

• Fix for subspacing with cyclic cf.wi and cf.wo arguments by @davidhassell in #925
• Enable parallel netCDF dataset reads by @davidhassell in #923
• New 'h5netcdf-h5py' netCDF backend in cf.write, and 'h5py_options' parameter by @davidhassell in #927
• Persist data after computation by @davidhassell in #930
• Add filesystem parameter to cf.read as pass-through to cfdm.read (Part 1) by @Copilot in #932
• Add filesystem parameter to cf.read as pass-through to cfdm.read (Part 2) by @davidhassell in #934
• Implement HEALPix grids by @davidhassell in #910
• Add all cf-plot dependencies (i.e. Cartopy) to cf.environment by @sadielbartholomew in #940
• Implementation of UGRID (part 2 of 2): Write by @davidhassell in #922
• Read Kerchunk and file-like object datasets by @davidhassell in #938

Full Changelog: v3.19.0...v3.20.0

3.19.0

2026-01-19

• Write Zarr v3 datasets with cf.write (#895)
• Read Zarr v2 and v3 datasets that contain a group hierarchy with cf.read (#894)
• Reduce the time taken to import cf (#902)
• New function to control the creation of cached elements during data display: cf.display_data (#913)
• New methods: cf.Data.get_cached_elements, cf.Data.cache_elements (#913)
• Set cached elements during cf.Data.__init__ (#913)
• Removed the cf.constants.CONSTANTS dictionary, replacing it with cf.ConstantAccess.constants (#902)
• Reduce the time taken to import cf (#902)
• New optional dependency: zarr>=3.1.3
• Changed dependency: cfdm>=1.13.0.0, <1.13.1.0

What's Changed

• Add three new recipes (21 - 23) by 2025 summer student by @sadielbartholomew in #900
• Docs: update description & preview image of cf-plot gallery by @sadielbartholomew in #901
• Reference training materials (& remove reference to 'the the'!) by @sadielbartholomew in #904
• Reduce the time taken to import cf by @davidhassell in #905
• Control setting and display of cached data elements by @davidhassell in #914
• Zarr write + Zarr groups by @davidhassell in #915
• Update hooks & workflows esp. to skip recipes with isort by @sadielbartholomew in #918
• Decouple recipes gallery from main docs build by @sadielbartholomew in #919
• Prepare release of v3.19.0 by @sadielbartholomew in #920

Full Changelog: v3.18.2...v3.19.0

3.18.2

2025-10-16

• Python 3.9 support removed (#896)
• Allow regridding for very large grids. New keyword parameter tocf.Field.regrids and cf.Field.regridc: dst_grid_partitions (#878)
• Changed dependency: Python>=3.10.0

What's Changed

• cf.Data.arctan2(): Fixes #890 by trying to conform valid units first. by @ThatDesert in #891
• Remove support for Python 3.9 (EOL) by @davidhassell in #897
• Unit test skips based on lack of optional module availability by @sadielbartholomew in #898
• Allow regridding for very large grids by @davidhassell in #893

Full Changelog: v3.18.1...v3.18.2

3.18.1

2025-08-20

• New methods to allow changing units in a chain: cf.Field.to_units, cf.Data.to_units (#874)
• Allow multiple conditions for the same axis in cf.Field.subspace and cf.Field.indices (#881)
• Fix bug in cf.Field.collapse that causes a ValueError to be raised for missing external cell measures data (#885)
• New dependency: distributed>=2025.5.1
• Changed dependency: cfdm>=1.12.3.0, <1.12.4.0

What's Changed

• Docs: fix DOI badge at source & patch in built docs (to avoid rebuild) by @sadielbartholomew in #877
• New to_units methods to allow changing units in a chain by @davidhassell in #875
• Add distributed as required dependency with version pin by @sadielbartholomew in #880
• cf.Field.subspace - allow multiple subspacing conditions for the same axis by @davidhassell in #882
• cf.Field.collapse fails when cell measure has external data by @davidhassell in #886
• Added troubleshooting for installing cf next to Jupyter and conda by @ThatDesert in #884

New Contributors

• @ThatDesert made their first contribution in #884

Full Changelog: v3.18.0...v3.18.1

3.18.0

2025-06-05

• Implement lossy compression via quantization (#870)
• New quantization class: cf.Quantization (#870)
• New quantization methods: cf.Field.get_quantization, cf.Field.get_quantize_on_write, cf.Field.set_quantize_on_write, cf.Field.del_quantize_on_write (#870)
• New keyword parameter to cf.write: chunk_cache (#871)
• Read Zarr datasets with cf.read (#863)
• Update CF aggregation keywords (#868)
• New keyword parameter to cf.DimensionCoordinate.create_bounds: inplace (#855)
• Set new minimum version of dask: 2025.5.1 (#866)
• Changed dependency: cfdm>=1.12.2.0, <1.12.3.0
• Changed dependency: dask>=2025.5.1

3.17.0

2025-04-02

• Set new minimum version of dask: 2025.2.0 (#849)
• Set a new minimum version of numpy: 2.0.0 (#843)
• Replace dataset aggregation functionality (CFA) with that imported from cfdm (#841)
• New keyword parameter to cf.Field.compute_vertical_coordinates: key (#802)
• New keyword parameter to cf.histogram: density (#794)
• Fix bug that caused Data._axes to be incorrect after a call to cf.Field.collapse (#857)
• Fix bug that caused wrong directions from cf.DimensionCoordinate.direction (#859)
• Changed dependency: Python>=3.9.0
• Changed dependency: numpy>=2.0.0
• Changed dependency: cfdm>=1.12.1.0, <1.12.2.0
• Changed dependency: dask>=2025.2.0, <=2025.3.0
• Changed dependency: netCDF4>=1.7.2
• Changed dependency: cftime>=1.6.4
• Changed optional dependency: esmpy>=8.7.0
• Removed dependency (now incorporated into cfdm): h5py
• Removed dependency (now incorporated into cfdm): h5netcdf
• Removed dependency (now incorporated into cfdm): s3fs

3.16.3

2025-01-28

• Allow 'nearest_dtos' 2-d regridding to work with discrete sampling geometry source grids (#832)
• New method: cf.Field.filled (#811)
• New method: cf.Field.is_discrete_axis (#784)
• Include the UM version as a field property when reading UM files (#777)
• Fix bug that caused climatological time collapses within/over days to fail (#809)
• New keyword parameter to cf.Field.derivative: ignore_coordinate_units (#807)
• Allow access to netCDF-4 files in S3 object stores (#712)
• New class cf.H5netcdfArray
• New class cf.NetCDF4Array
• New class cf.CFAH5netcdfArray
• New class cf.CFANetCDF4Array
• Replace core dask functionality with that imported from cfdm (#839)
• Fix bug that sometimes puts an incorrect radian-1 or radian-2 in the returned units of the differential operator methods and functions (#807)
• Fix bug where cf.example_fields returned a list of Fields rather than a Fieldlist (#725)
• Fix bug where combining UGRID fields erroneously creates an extra axis and broadcasts over it (#784)
• Fix bug where cf.normalize_slice doesn't correctly handle certain cyclic slices (#774)
• Fix bug where cf.Field.subspace doesn't always correctly handle global or near-global cyclic subspaces (#828)
• New dependency: h5netcdf>=1.3.0
• New dependency: h5py>=3.10.0
• New dependency: s3fs>=2024.6.0
• Changed dependency: numpy>=1.15,<2.0
• Changed dependency: 1.11.2.0<=cfdm<1.11.3.0
• Changed dependency: cfunits>=3.3.7
• Changed dependency: dask>=2024.6.0,<=2024.7.1

3.16.2

2024-04-26

• Improve the performance of reading and accessing the data of PP and UM fields files (#746)
• Improve cf.Field.collapse performance by lazily computing reduced axis coordinates (#741)
• Improve cf.Field.__getitem__ performance by not re-calculating axis cyclicity (#744)
• Reduce output CFA netCDF file size by setting the HDF5 chunksizes of CFA variables to be no larger than required (#739)
• Allow a halo to be added by cf.Field.indices and cf.Field.subspace (#759)
• Added spherical regridding to discrete sampling geometry destination grids (#716)
• Added 3-d spherical regridding to cf.Field.regrids, and the option to regrid the vertical axis in logarithmic coordinates to cf.Field.regrids and cf.Field.regridc (#715)
• New keyword parameter to cf.Field.regrids and cf.Field.regridc: return_esmpy_regrid_operator (#766)
• New keyword parameters to cf.wi: open_lower and open_upper (#740)
• Fix misleading error message when it is not possible to create area weights requested from cf.Field.collapse (#731)
• Fix bug in cf.read when reading UM files that caused LBPROC value 131072 (Mean over an ensemble of parallel runs) to be ignored (#737)
• Fix bug in cf.aggregate that sometimes put a null transpose operation into the Dask graph when one was not needed (#754)
• Fix bug in cf.aggregate that caused a failure when property values were numpy arrays with two or more elements (#764)
• Fix bug in cf.aggregate that didn't correctly handle the "actual_range" CF attribute (#764)
• Fix bug whereby Field.cyclic is not updated after a Field.del_construct operation (#758)
• Fix bug that meant cyclic() always returned an empty set for domains produced by cf.Field.domain (#762)
• Changed dependency: cfunits>=3.3.7
• Changed dependency: netCDF4>=1.6.5