Introduction to `cf_xarray`¶

This notebook is a brief introduction to cf_xarray’s current capabilities.

import numpy as np
import xarray as xr

import cf_xarray as cfxr

# For this notebooks, it's nicer if we don't show the array values by default
xr.set_options(display_expand_data=False)

<xarray.core.options.set_options at 0x7f9f78cd0440>

cf_xarray works best when xarray keeps attributes by default.

xr.set_options(keep_attrs=True)

<xarray.core.options.set_options at 0x7f9f786fdf90>

Lets read two datasets.

This one is inspired by POP model output and illustrates how the coordinates attribute is interpreted. It also illustrates one way of tagging curvilinear grids for convenient use of cf_xarray

This synthetic dataset has multiple X and Y coords. An example would be model output on a staggered grid.

This dataset has ancillary variables

What attributes have been discovered?¶

The criteria for identifying variables using CF attributes are listed here.

ds.lon

<xarray.DataArray 'lon' (lon: 53)> Size: 212B
200.0 202.5 205.0 207.5 210.0 212.5 ... 317.5 320.0 322.5 325.0 327.5 330.0
Coordinates:
  * lon      (lon) float32 212B 200.0 202.5 205.0 207.5 ... 325.0 327.5 330.0
Attributes:
    standard_name:  longitude
    long_name:      Longitude
    units:          degrees_east
    axis:           X

ds.lon has attributes axis: X. This means that cf_xarray can identify the 'X' axis as being represented by the lon variable.

It can also use the standard_name and units attributes to infer that lon is “Longitude”. To see variable names that cf_xarray can infer, use ds.cf

ds.cf

Coordinates:
             CF Axes: * X: ['lon']
                      * Y: ['lat']
                      * T: ['time']
                        Z: n/a

      CF Coordinates: * longitude: ['lon']
                      * latitude: ['lat']
                      * time: ['time']
                        vertical: n/a

       Cell Measures:   area, volume: n/a

      Standard Names: * latitude: ['lat']
                      * longitude: ['lon']
                      * time: ['time']

              Bounds:   n/a

       Grid Mappings:   n/a

Data Variables:
       Cell Measures:   area, volume: n/a

      Standard Names:   air_temperature: ['air']

              Bounds:   n/a

       Grid Mappings:   n/a

For pop, only latitude and longitude are detected, not X or Y. Please comment here: https://github.com/xarray-contrib/cf-xarray/issues/23 if you have opinions about this behaviour.

pop.cf

Coordinates:
             CF Axes: * X: ['nlon']
                      * Y: ['nlat']
                        Z, T: n/a

      CF Coordinates:   longitude: ['TLONG', 'ULONG']
                        latitude: ['TLAT', 'ULAT']
                        vertical, time: n/a

       Cell Measures:   area, volume: n/a

      Standard Names:   n/a

              Bounds:   n/a

       Grid Mappings:   n/a

Data Variables:
       Cell Measures:   area, volume: n/a

      Standard Names:   sea_water_potential_temperature: ['TEMP']
                        sea_water_x_velocity: ['UVEL']

              Bounds:   n/a

       Grid Mappings:   n/a

For multiple, multiple X and Y coordinates are detected

multiple.cf

Coordinates:
             CF Axes: * X: ['x1', 'x2']
                      * Y: ['y1', 'y2']
                        Z, T: n/a

      CF Coordinates:   longitude, latitude, vertical, time: n/a

       Cell Measures:   area, volume: n/a

      Standard Names:   n/a

              Bounds:   n/a

       Grid Mappings:   n/a

Data Variables:
       Cell Measures:   area, volume: n/a

      Standard Names:   n/a

              Bounds:   n/a

       Grid Mappings:   n/a

Feature: Utility functions¶

There are some utility functions to allow use by downstream libraries

pop.cf.keys()

{'X',
 'Y',
 'latitude',
 'longitude',
 'sea_water_potential_temperature',
 'sea_water_x_velocity'}

You can test for presence of these keys

"sea_water_x_velocity" in pop.cf

True

You can also get out the available Axis names

pop.cf.axes

{'X': ['nlon'], 'Y': ['nlat']}

or available Coordinate names. Same for cell measures (.cf.cell_measures) and standard names (.cf.standard_names).

pop.cf.coordinates

{'longitude': ['TLONG', 'ULONG'], 'latitude': ['TLAT', 'ULAT']}

Note: Although it is possible to assign additional coordinates, .cf.coordinates only returns a subset of ("longitude", "latitude", "vertical", "time").

Feature: Rewriting property dictionaries¶

cf_xarray will rewrite the .sizes and .chunks dictionaries so that one can index by a special CF axis or coordinate name

ds.cf.sizes

{'latitude': 25, 'Y': 25, 'time': 2920, 'T': 2920, 'longitude': 53, 'X': 53}

Note the duplicate entries above:

One for X, Y, T
and one for longitude, latitude and time.

An error is raised if there are multiple 'X' variables (for example)

multiple.cf.sizes

---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
Cell In[26], line 1
----> 1 multiple.cf.sizes

File ~/checkouts/readthedocs.org/user_builds/cf-xarray/checkouts/latest/cf_xarray/accessor.py:1550, in CFAccessor.__getattr__(self, attr)
   1549 def __getattr__(self, attr):
-> 1550     return _getattr(
   1551         obj=self._obj,
   1552         attr=attr,
   1553         accessor=self,
   1554         key_mappers=_DEFAULT_KEY_MAPPERS,
   1555         wrap_classes=True,
   1556     )

File ~/checkouts/readthedocs.org/user_builds/cf-xarray/checkouts/latest/cf_xarray/accessor.py:704, in _getattr(obj, attr, accessor, key_mappers, wrap_classes, extra_decorator)
    702     for name in inverted[key]:
    703         if name in newmap:
--> 704             raise AttributeError(
    705                 f"cf_xarray can't wrap attribute {attr!r} because there are multiple values for {name!r}. "
    706                 f"There is no unique mapping from {name!r} to a value in {attr!r}."
    707             )
    708     newmap.update(dict.fromkeys(inverted[key], value))
    709 newmap.update({key: attribute[key] for key in unused_keys})

AttributeError: cf_xarray can't wrap attribute 'sizes' because there are multiple values for 'X'. There is no unique mapping from 'X' to a value in 'sizes'.

multiple.v1.cf.sizes

{'X': 30, 'Y': 20}

Feature: Weight by Cell Measures¶

cf_xarray can weight by cell measure variables if the appropriate attribute is set

# Lets make some weights (not sure if this is right)
ds.coords["cell_area"] = (
    np.cos(ds.air.cf["latitude"] * np.pi / 180)
    * xr.ones_like(ds.air.cf["longitude"])
    * 105e3
    * 110e3
)
# and set proper attributes
ds["cell_area"].attrs = dict(standard_name="cell_area", units="m2")
ds.air.attrs["cell_measures"] = "area: cell_area"

ds.air.cf.weighted("area").mean(["latitude", "time"]).cf.plot(x="longitude")
ds.air.mean(["lat", "time"]).cf.plot(x="longitude")

[<matplotlib.lines.Line2D at 0x7f9f69baca50>]

../_images/31fbf29041736d3b86d1c4d080202859b38e64a6f46997358bfe0277cff479a9.png

Feature: Add canonical CF attributes¶

cf_xarray can add missing canonical CF attributes consistent with the official CF standard name table.

ds_canonical = ds.cf.add_canonical_attributes(verbose=True)
ds_canonical

---------------------------------------------------------------------------
HTTPError                                 Traceback (most recent call last)
Cell In[46], line 1
----> 1 ds_canonical = ds.cf.add_canonical_attributes(verbose=True)
      2 ds_canonical

File ~/checkouts/readthedocs.org/user_builds/cf-xarray/checkouts/latest/cf_xarray/accessor.py:2252, in CFAccessor.add_canonical_attributes(self, override, skip, verbose, source)
   2249 skip_ = [skip] if isinstance(skip, Hashable) else (skip or [])
   2251 # Parse table
-> 2252 info, table, aliases = parse_cf_standard_name_table(source)
   2254 # Loop over standard names
   2255 ds = self._maybe_to_dataset().copy(deep=False)

File ~/checkouts/readthedocs.org/user_builds/cf-xarray/checkouts/latest/cf_xarray/utils.py:111, in parse_cf_standard_name_table(source)
    108 if not source:
    109     import pooch
--> 111     source = pooch.retrieve(
    112         "https://raw.githubusercontent.com/cf-convention/cf-convention.github.io/"
    113         "master/Data/cf-standard-names/current/src/cf-standard-name-table.xml",
    114         known_hash=None,
    115     )
    116 root = ElementTree.parse(source).getroot()
    118 # Build dictionaries

File ~/checkouts/readthedocs.org/user_builds/cf-xarray/conda/latest/lib/python3.13/site-packages/pooch/core.py:239, in retrieve(url, known_hash, fname, path, processor, downloader, progressbar)
    236 if downloader is None:
    237     downloader = choose_downloader(url, progressbar=progressbar)
--> 239 stream_download(url, full_path, known_hash, downloader, pooch=None)
    241 if known_hash is None:
    242     get_logger().info(
    243         "SHA256 hash of downloaded file: %s\n"
    244         "Use this value as the 'known_hash' argument of 'pooch.retrieve'"
   (...)
    247         file_hash(str(full_path)),
    248     )

File ~/checkouts/readthedocs.org/user_builds/cf-xarray/conda/latest/lib/python3.13/site-packages/pooch/core.py:807, in stream_download(url, fname, known_hash, downloader, pooch, retry_if_failed)
    803 try:
    804     # Stream the file to a temporary so that we can safely check its
    805     # hash before overwriting the original.
    806     with temporary_file(path=str(fname.parent)) as tmp:
--> 807         downloader(url, tmp, pooch)
    808         hash_matches(tmp, known_hash, strict=True, source=str(fname.name))
    809         shutil.move(tmp, str(fname))

File ~/checkouts/readthedocs.org/user_builds/cf-xarray/conda/latest/lib/python3.13/site-packages/pooch/downloaders.py:221, in HTTPDownloader.__call__(self, url, output_file, pooch, check_only)
    219 try:
    220     response = requests.get(url, timeout=timeout, **kwargs)
--> 221     response.raise_for_status()
    222     content = response.iter_content(chunk_size=self.chunk_size)
    223     total = int(response.headers.get("content-length", 0))

File ~/checkouts/readthedocs.org/user_builds/cf-xarray/conda/latest/lib/python3.13/site-packages/requests/models.py:1024, in Response.raise_for_status(self)
   1019     http_error_msg = (
   1020         f"{self.status_code} Server Error: {reason} for url: {self.url}"
   1021     )
   1023 if http_error_msg:
-> 1024     raise HTTPError(http_error_msg, response=self)

HTTPError: 403 Client Error: Forbidden for url: https://raw.githubusercontent.com/cf-convention/cf-convention.github.io/master/Data/cf-standard-names/current/src/cf-standard-name-table.xml

Introduction to `cf_xarray`¶

What attributes have been discovered?¶

Feature: Accessing coordinate variables¶

Feature: Accessing variables by standard names¶

Feature: Utility functions¶

Feature: Rewriting property dictionaries¶

Feature: Renaming variables¶

Feature: Rewriting arguments¶

Slicing¶

Reductions¶

Plotting¶

Resample & groupby¶

Rolling & coarsen¶

Feature: mix “special names” and variable names¶

Feature: Weight by Cell Measures¶

Feature: Cell boundaries and vertices¶

Feature: Add canonical CF attributes¶

Introduction to cf_xarray¶

What attributes have been discovered?¶

Feature: Accessing coordinate variables¶

Feature: Accessing variables by standard names¶

Feature: Utility functions¶

Feature: Rewriting property dictionaries¶

Feature: Renaming variables¶

Feature: Rewriting arguments¶

Slicing¶

Reductions¶

Plotting¶

Resample & groupby¶

Rolling & coarsen¶

Feature: mix “special names” and variable names¶

Feature: Weight by Cell Measures¶

Feature: Cell boundaries and vertices¶

Feature: Add canonical CF attributes¶

Introduction to `cf_xarray`¶