Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion Changelog.rst
Original file line number Diff line number Diff line change
@@ -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)
Expand Down
1 change: 1 addition & 0 deletions cf/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
41 changes: 10 additions & 31 deletions cf/mixin/fielddomain.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
)
from ..functions import (
_DEPRECATION_ERROR_KWARGS,
_DEPRECATION_ERROR_METHOD,
bounds_combination_mode,
normalize_slice,
)
Expand Down Expand Up @@ -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
Expand Down
37 changes: 10 additions & 27 deletions cf/mixin/fielddomainlist.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
from ..functions import _DEPRECATION_ERROR_ARG
from ..functions import _DEPRECATION_ERROR_ARG, _DEPRECATION_ERROR_METHOD


class FieldDomainList:
Expand Down Expand Up @@ -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
111 changes: 43 additions & 68 deletions cf/test/test_xarray.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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)

Expand All @@ -111,65 +78,73 @@ 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)

self.assertIn("q", ds)
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())
Expand Down
35 changes: 35 additions & 0 deletions cf/xarray_utils.py
Original file line number Diff line number Diff line change
@@ -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(
"<Field", "<CF Field"
)


def to_xarray(f, group=True):
"""Convert CF field or domain constructs to an `xarray` dataset."""
return cfdm.to_xarray(f, group=group)


# Reset the docstring from cfdm
to_xarray.__doc__ = cfdm.to_xarray.__doc__.replace("cfdm.", "cf.").replace(
"<Field", "<CF Field"
)
11 changes: 11 additions & 0 deletions docs/source/function.rst
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,17 @@ Aggregation
cf.aggregate
cf.climatology_cells

Conversion from and to xarray
-----------------------------

.. autosummary::
:nosignatures:
:toctree: function/
:template: function.rst

cf.from_xarray
cf.to_xarray

.. _functions-mathematical-operations:

Mathematical operations
Expand Down
7 changes: 7 additions & 0 deletions docs/source/function/cf.from_xarray.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
cf.from_xarray
==============

.. currentmodule:: cf
.. default-role:: obj

.. autofunction:: cf.from_xarray
7 changes: 7 additions & 0 deletions docs/source/function/cf.to_xarray.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
cf.to_xarray
============

.. currentmodule:: cf
.. default-role:: obj

.. autofunction:: cf.to_xarray
4 changes: 4 additions & 0 deletions docs/source/tutorial.rst
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,10 @@ The following file types can be read:

..

* In memory `xarray` datasets (see also `cf.from_xarray`).

..

Note that when reading netCDF4 files that contain :ref:`hierachical
groups <Hierarchical-groups>`, the group structure is saved via the
:ref:`netCDF interface <NetCDF-interface>` so that it may be re-used,
Expand Down
Loading