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 0x7f585fe9bdf0>

cf_xarray works best when xarray keeps attributes by default.

xr.set_options(keep_attrs=True)

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

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

{'Y': 25, 'latitude': 25, 'T': 2920, 'time': 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/stable/cf_xarray/accessor.py:1505, in CFAccessor.__getattr__(self, attr)
   1504 def __getattr__(self, attr):
-> 1505     return _getattr(
   1506         obj=self._obj,
   1507         attr=attr,
   1508         accessor=self,
   1509         key_mappers=_DEFAULT_KEY_MAPPERS,
   1510         wrap_classes=True,
   1511     )

File ~/checkouts/readthedocs.org/user_builds/cf-xarray/checkouts/stable/cf_xarray/accessor.py:675, in _getattr(obj, attr, accessor, key_mappers, wrap_classes, extra_decorator)
    673     for name in inverted[key]:
    674         if name in newmap:
--> 675             raise AttributeError(
    676                 f"cf_xarray can't wrap attribute {attr!r} because there are multiple values for {name!r}. "
    677                 f"There is no unique mapping from {name!r} to a value in {attr!r}."
    678             )
    679     newmap.update(dict.fromkeys(inverted[key], value))
    680 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 0x7f585bb1fa90>]

../_images/0a571cc31c253af9beba809e41a983dd645ec8386706de057c313bb7e9824129.png

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`#