unxts.interop.xarray

unxts.interop.xarray#

unxts.interop.xarray is the canonical location for xarray integration. It adds a .unxt accessor to DataArray and Dataset that converts between xarray’s unit metadata — a units string in .attrs — and real unxt.Quantity values, so units become part of the data rather than a label beside it.

Importing the package registers the accessor as an import side effect.

Install#

The recommended install adds unxts.interop.xarray alongside unxt via the interop-xarray extra, so it, unxt and xarray are resolved together as a compatible set:

uv add "unxt[interop-xarray]"

pip install "unxt[interop-xarray]"

Or install the package directly:

uv add unxts.interop.xarray

pip install unxts.interop.xarray

At a glance#

import numpy as np
import xarray as xr

import unxts.interop.xarray  # registers the .unxt accessor

da = xr.DataArray(np.array([1.0, 2.0, 3.0]), dims="x", attrs={"units": "m"})

q = da.unxt.quantify()
q.data
# Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

plain = q.unxt.dequantify()
plain.attrs["units"]
# 'm'

quantify() reads the units attribute and turns the values into a Quantity; dequantify() reverses it, putting the unit back in .attrs.

Pages#

Tutorial

How-to

  • How to use unxt with xarray — quantifying and dequantifying DataArrays and Datasets, coordinates, unit conversion, JAX transforms, and round-tripping through NetCDF.

Reference

  • API — the functions underneath the accessor: extract_unit_attributes, attach_units, extract_units, strip_units.

Discussion

  • The xarray sharp bits — why dimension coordinates cannot hold quantities, and which operations drop units.

See also#