CF-Xarray

0.10.11 · active · verified Thu Apr 16

CF-Xarray is a lightweight Python library that extends Xarray objects with an accessor (`.cf`) to interpret and utilize Climate and Forecast (CF) metadata conventions. It simplifies data analysis workflows by allowing users to refer to geophysical quantities by their standard CF names (e.g., 'latitude' instead of 'lat'), making code more generic across diverse CF-compliant datasets. The library is actively maintained as part of the `xarray-contrib` organization, with frequent releases.

Common errors

```
AttributeError: 'DataArray' object has no attribute 'cf'
```
cause The `cf-xarray` accessor has not been registered with xarray. This typically happens if `import cf_xarray` is omitted or executed after the xarray object is created and accessed.

fix Add `import cf_xarray` at the beginning of your script or before any `.cf` accessor calls.
```
KeyError: 'latitude' (or similar CF standard name) when using ds.cf['latitude']
```
cause The xarray Dataset or DataArray lacks the necessary CF-compliant attributes (e.g., 'standard_name', 'axis', 'units') for cf-xarray to identify a variable as 'latitude'.

fix Inspect `ds.cf.coordinates` or `ds.cf.axes` to see which CF attributes are recognized. You might need to manually add appropriate attributes to your xarray object (e.g., `da.attrs['standard_name'] = 'latitude'`) or use `ds.cf.guess_coord_axis()` to infer them.
```
ModuleNotFoundError: No module named 'xarray'
```
cause xarray is a mandatory dependency for cf-xarray, and it is not installed in the current Python environment.

fix Install xarray: `pip install xarray cf-xarray`.

Warnings

breaking Xarray's default attribute handling changed in versions >= 2025.11.0. Operations now preserve attributes by default and combine attributes from both operands using `drop_conflicts` in binary operations, instead of keeping only the left operand's attributes. This might affect workflows relying on previous attribute-dropping behavior.
Fix: Review xarray's documentation for attribute handling. If explicit attribute dropping or custom merging is needed, use `keep_attrs=False` or implement custom logic.
gotcha cf-xarray's utility is highly dependent on the presence and correctness of CF-compliant metadata (attributes) in your xarray objects. If metadata is incomplete or non-standard, `cf-xarray` might not identify variables as expected.
Fix: Inspect recognized attributes using `ds.cf.coordinates` or `ds.cf.axes`. Use methods like `ds.cf.guess_coord_axis()` or `ds.cf.add_canonical_attributes()` to infer or add missing metadata. Custom criteria can also be provided for identification.
gotcha The `cf.add_bounds()` method estimates coordinate bounds using linear interpolation and extrapolation. While effective for rectilinear grids, this can be a coarse approximation for curvilinear or irregular grids, potentially leading to inaccuracies or unmatching corners in complex geometries.
Fix: Be aware of the limitations for non-rectilinear grids. For critical applications, prefer datasets with pre-calculated, explicitly provided bounds or grid metrics from the data producer.
deprecated Xarray, cf-xarray's core dependency, dropped support for Python 2.7 in `xarray` v0.12.0. cf-xarray itself requires Python >=3.11.
Fix: Ensure your environment uses Python 3.11 or later and the latest compatible version of xarray.

Install

pip install cf-xarray PyPI

Imports

cf_xarray
```
import cf_xarray
```
Importing the top-level package registers the .cf accessor on xarray objects. No direct import of classes is usually needed for basic usage.

Quickstart

Demonstrates loading an xarray dataset, accessing CF-compliant coordinates and axes via the `.cf` accessor, and performing an operation (mean) using CF standard names. It also shows how to use `guess_coord_axis()` for datasets with incomplete metadata.

import xarray as xr
import cf_xarray # This registers the .cf accessor

# Load a sample dataset (e.g., from xarray's tutorial data)
ds = xr.tutorial.load_dataset("air_temperature")

# Access CF-compliant coordinates
print("CF-identified coordinates:", ds.cf.coordinates)
print("Latitude variable name:", ds.cf["latitude"])

# Perform a mean operation using CF standard names
mean_temp = ds.air.cf.mean("latitude")
print("Mean temperature along latitude:\n", mean_temp)

# Add missing CF attributes (if necessary)
ds_incomplete = ds.copy(deep=True)
ds_incomplete.lat.attrs.pop('standard_name')
ds_incomplete.cf.guess_coord_axis(verbose=True)
print("Guessed coordinates for incomplete dataset:", ds_incomplete.cf.coordinates)

view raw JSON →