diff --git a/Changelog.rst b/Changelog.rst index 128bb77819..b6aa9dd4ee 100644 --- a/Changelog.rst +++ b/Changelog.rst @@ -1,8 +1,11 @@ Version NEXTVERSION -------------- -**2026-10-??** +**2026-11-??** +* New package-level functions to convert from and to `xarray`: + `cf.from_xarray` and `cf.to_xarray` + (https://github.com/NCAS-CMS/cf-python/issues/978) * Allow a sequence as input to `cf.year`, `cf.month`, `cf.day`, `cf.hour`, `cf.minute`, and `cf.second` (https://github.com/NCAS-CMS/cf-python/issues/974) diff --git a/cf/__init__.py b/cf/__init__.py index 784e77d98a..81260cc1cf 100644 --- a/cf/__init__.py +++ b/cf/__init__.py @@ -188,6 +188,7 @@ from .regrid import RegridOperator +from .xarray_utils import from_xarray, to_xarray # Set up basic logging for the full project with a root logger import logging diff --git a/cf/mixin/fielddomain.py b/cf/mixin/fielddomain.py index eea0314c09..2eb8e3a1ad 100644 --- a/cf/mixin/fielddomain.py +++ b/cf/mixin/fielddomain.py @@ -13,6 +13,7 @@ ) from ..functions import ( _DEPRECATION_ERROR_KWARGS, + _DEPRECATION_ERROR_METHOD, bounds_combination_mode, normalize_slice, ) @@ -3928,42 +3929,20 @@ def set_coordinate_reference( def to_xarray(self, group=True): """Convert the {{class}} to an `xarray` dataset. - {{cf_xarray description}} - - Note that ``ds = f.to_xarray()`` is identical to ``ds = - {{package}}.write(f, fmt='XARRAY')``; and multiple - {{class_lower}}s may be written to the same `xarray` dataset - with `{{package}}.write` (e.g. ``ds = {{package}}.write([f, - g], fmt='XARRAY')``). Also, `{{package}}.write` allows a - mixture of fields and domains to be written to the - same `xarray` dataset. - - An `xarray` dataset can be converted to one or more fields - with ``f = {{package}}.read(ds)``, or domains with ``f = - {{package}}.read(ds, domain=True)``. + Deprecated at version NEXTVERSION and is no longer + available. Use `cf.to_xarray` instead. .. versionadded:: 3.21.0 - .. seealso:: `cf.{{class}}List.to_xarray`, `cf.write` - - :Parameter: - - group: `bool`, optional - If False then create a "flat" dataset, i.e. one with - only the root group, regardless of any group structure - specified by the netCDF interfaces of the - {{class_lower}} and its components. If True (the - default) then any sub-groups will be created and - populated. - - :Returns: - - {{Returns xarray}} """ - from cf.read_write import write - - return write(self, fmt="XARRAY", group=group) + _DEPRECATION_ERROR_METHOD( + self, + "to_xarray", + version="NEXTVERSION", + removed_at="4.0.0", + message="Use the 'cf.to_xarray' function instead.", + ) # pragma: no cover # ---------------------------------------------------------------- # Aliases diff --git a/cf/mixin/fielddomainlist.py b/cf/mixin/fielddomainlist.py index 904286b173..8d94235428 100644 --- a/cf/mixin/fielddomainlist.py +++ b/cf/mixin/fielddomainlist.py @@ -1,4 +1,4 @@ -from ..functions import _DEPRECATION_ERROR_ARG +from ..functions import _DEPRECATION_ERROR_ARG, _DEPRECATION_ERROR_METHOD class FieldDomainList: @@ -335,31 +335,14 @@ def select_by_rank(self, *ranks): def to_xarray(self, group=True): """Convert the list elements to an `xarray` Dataset. - {{cf_xarray description}} - - Note that ``ds = fl.to_xarray()`` is identical to ``ds = - cf.write(fl, fmt='XARRAY')``. Also, `cfdm.write` allows a - mixture of fields and domains to be written to the - same `xarray` dataset. - - .. versionadded:: 3.21.0 - - .. seealso:: `cf.write` - - :Parameter: - - group: `bool`, optional - If False then create a "flat" dataset, i.e. one with - only the root group, regardless of any group structure - specified by the netCDF interfaces of the list - elements and their components. If True (the default) - then any sub-groups will be created and populated. - - :Returns: - - {{Returns xarray}} + Deprecated at version NEXTVERSION and is no longer + available. Use `cf.to_xarray` instead. """ - from cf.read_write import write - - return write(self, fmt="XARRAY", group=group) + _DEPRECATION_ERROR_METHOD( + self, + "to_xarray", + version="NEXTVERSION", + removed_at="4.0.0", + message="Use the 'cf.to_xarray' function instead.", + ) # pragma: no cover diff --git a/cf/test/test_xarray.py b/cf/test/test_xarray.py index 426234d8f1..f9e44dc465 100644 --- a/cf/test/test_xarray.py +++ b/cf/test/test_xarray.py @@ -31,47 +31,18 @@ def test_Field_to_xarray(self): # Write each field to a different xarray dataset for f in fields: - ds = f.to_xarray() + ds = cf.to_xarray(f) self.assertIsInstance(ds, xr.Dataset) - str(ds) self.assertIn("Conventions", ds.attrs) - - # Write all fields to one xarray dataset - ds = cf.write(fields, fmt="XARRAY") - self.assertIsInstance(ds, xr.Dataset) - str(ds) - - def test_Domain_to_xarray(self): - """Test Domain.to_xarray.""" - domains = [f.domain for f in cf.example_fields()] - - # Write each domain to a different xarray dataset - for d in domains: - ds = d.to_xarray() - self.assertIsInstance(ds, xr.Dataset) str(ds) - # Write all domains to one xarray dataset - ds = cf.write(domains, fmt="XARRAY") - self.assertIsInstance(ds, xr.Dataset) - str(ds) - - def test_FieldList_to_xarray(self): - """Test FieldList.to_xarray.""" - fields = cf.example_fields() - ds = fields.to_xarray() - self.assertIsInstance(ds, xr.Dataset) - str(ds) - - def test_DomainList_to_xarray(self): - """Test DomainList.to_xarray.""" - domains = cf.DomainList([f.domain for f in cf.example_fields()]) - ds = domains.to_xarray() + # Write all fields to one xarray dataset + ds = cf.to_xarray(fields) self.assertIsInstance(ds, xr.Dataset) str(ds) - def test_FieldList_to_xarray_from_disk(self): - """Test FieldList.to_xarray from datasets read from disk.""" + def test_Field_to_xarray_from_disk(self): + """Test Field.to_xarray on datasets read from disk.""" for dataset in ( "example_field_0.nc", "example_field_0.zarr2", @@ -96,13 +67,9 @@ def test_FieldList_to_xarray_from_disk(self): "ugrid_2.nc", "ugrid_3.nc", "test_file.nc", - "extra_data.pp", - "file1.pp", - "umfile.pp", - "wgdos_packed.pp", ): f = cf.read(dataset) - ds = f.to_xarray() + ds = cf.to_xarray(f) self.assertIsInstance(ds, xr.Dataset) str(ds) @@ -111,17 +78,17 @@ def test_Field_to_xarray_groups(self): f = cf.example_field(0) g = f.copy() - ds = f.to_xarray() + ds = cf.to_xarray(f) self.assertIsInstance(ds, xr.Dataset) f.nc_set_variable("/forecast/model/q2") - ds = f.to_xarray() + ds = cf.to_xarray(f) self.assertIsInstance(ds, xr.DataTree) self.assertIn("q2", ds["/forecast/model"]) str(ds) # group=True - ds = cf.write([f, g], fmt="XARRAY") + ds = cf.to_xarray([f, g]) self.assertIsInstance(ds, xr.DataTree) str(ds) @@ -129,47 +96,55 @@ def test_Field_to_xarray_groups(self): self.assertIn("q2", ds["/forecast/model"]) # group=False - ds = f.to_xarray(group=False) + ds = cf.to_xarray(f, group=False) self.assertIsInstance(ds, xr.Dataset) self.assertIn("q2", ds) str(ds) - ds = cf.write([f, g], fmt="XARRAY", group=False) + ds = cf.to_xarray([f, g], group=False) self.assertIsInstance(ds, xr.Dataset) str(ds) self.assertIn("q", ds) self.assertIn("q2", ds) - def test_FieldList_to_xarray_groups(self): - """Test FieldList.to_xarray with groups.""" - f = cf.example_fields(0) - - ds = f.to_xarray() - self.assertIsInstance(ds, xr.Dataset) + def test_write_xarray_external(self): + """Test cf.write with xarray and external file.""" + f = cf.example_field(0) + with self.assertRaises(ValueError): + cf.write(f, fmt="XARRAY", external="file.nc") + + def test_from_xarray(self): + """Test cf.from_xarray.""" + # These fields round trip OK! + f = cf.example_fields(0, 2, 5, 7, 12, 13) + ds = cf.to_xarray(f) + g = cf.from_xarray(ds) + self.assertEqual(len(f), len(g)) + self.assertIsInstance(g, cf.FieldList) + + f = sorted(f, key=lambda x: x.get_property("standard_name")) + g = sorted(g, key=lambda x: x.get_property("standard_name")) + self.assertEqual( + [field1.equals(field0) for field0, field1 in zip(f, g)], + [True] * len(f), + ) + + def test_to_xarray_domain(self): + """Test cf.to_xarray with domain.""" + domains = [f.domain for f in cf.example_fields()] - f[0].nc_set_variable("/forecast/model/q2") - ds = f.to_xarray() - self.assertIsInstance(ds, xr.DataTree) - self.assertIn("q2", ds["/forecast/model"]) - str(ds) + # Write each domain to a different xarray dataset + for d in domains: + ds = cf.to_xarray(d) + self.assertIsInstance(ds, xr.Dataset) + str(ds) - ds = f.to_xarray(group=False) + # Write all domains to one xarray dataset + ds = cf.to_xarray(domains) self.assertIsInstance(ds, xr.Dataset) - self.assertIn("q2", ds) str(ds) - def test_Field_to_xarray_aggregation(self): - """Test Field.to_xarray with aggregated data.""" - f = cf.read("example_field_0.nc")[0] - dsf = f.to_xarray() - - self.assertEqual(f.shape[0], 5) - g = cf.aggregate([f[:3], f[3:]])[0] - dsg = g.to_xarray() - - self.assertTrue(dsg.equals(dsf)) - if __name__ == "__main__": print("Run date:", datetime.datetime.now()) diff --git a/cf/xarray_utils.py b/cf/xarray_utils.py new file mode 100644 index 0000000000..b7ceda9801 --- /dev/null +++ b/cf/xarray_utils.py @@ -0,0 +1,35 @@ +"""Utilities for conversion to and from xarray.""" + +import cfdm + + +def from_xarray(ds, domain=False): + """Convert an `xarray` dataset to CF field or domain constructs.""" + try: + import xarray # noqa: F401 + except ImportError as e: + raise ImportError( + f"{e}. Must install xarray " + "to allow the conversion to and from an xarray dataset" + ) + + from . import read + + return read(ds, domain=domain, aggregate=False) + + +# Reset the docstring from cfdm +from_xarray.__doc__ = cfdm.from_xarray.__doc__.replace("cfdm.", "cf.").replace( + "`, the group structure is saved via the :ref:`netCDF interface ` so that it may be re-used,