Pint-Xarray

Common errors

• AttributeError: 'DataArray' object has no attribute 'pint'

  cause The `pint_xarray` accessor was not registered with xarray. This happens if `import pint_xarray` is omitted or placed after the `xarray.DataArray` creation in certain environments.
  fix Add `import pint_xarray` at the beginning of your script or before you attempt to use the `.pint` accessor. The import statement itself registers the accessor.

• pint.errors.DimensionalityError: Cannot convert from 'meter' to 'second'

  cause You attempted an operation (e.g., addition, conversion) between two quantities that have fundamentally incompatible dimensions (e.g., length and time). Pint strictly enforces dimensional correctness.
  fix Review the units of the involved DataArrays or Quantities. Ensure they are dimensionally compatible before performing the operation. If a conversion is intended, ensure the target unit is dimensionally consistent (e.g., `da.pint.to('kilometer')` for a meter-quantified array).

Warnings

• breaking Starting from version 0.5.0, `pint-xarray` changed its internal unit storage mechanism. Units are now stored as `pint.Quantity` objects within a custom `pint_units` backend, rather than as strings in `xarray.DataArray.attrs`. This enhances unit propagation and ensures better integration with Pint's features.
  Fix: Migrate code to use the `.pint.quantify()` method to explicitly attach units, and avoid direct manipulation of `attrs['units']` if unit-awareness is desired. Existing data saved before 0.5.0 might need re-quantifying upon loading.
• deprecated The `convert_units` function (e.g., `pint_xarray.convert_units(da, 'meter')`) has been removed in favor of the `.pint.to()` accessor method.
  Fix: Replace calls to `pint_xarray.convert_units(obj, unit)` with `obj.pint.to(unit)`.
• gotcha When performing operations with quantified xarray objects, Pint's strict unit checking will enforce dimensional consistency. Attempting operations on quantities with incompatible dimensions will raise a `DimensionalityError`.
  Fix: Always ensure units are dimensionally compatible before an operation. Use `da.pint.to(target_unit)` or `da.pint.to_base_units()` to explicitly convert units if needed.
• gotcha Using `pint-xarray` for computations will ensure unit propagation for many operations, but it does not magically resolve all unit inconsistencies in every scenario. For example, some non-unit-aware xarray methods might still drop unit metadata if not handled correctly.
  Fix: Always verify the units after complex operations, especially when chaining multiple xarray methods. If units are unexpectedly dropped or behave strangely, consider applying `.pint.quantify()` or `.pint.dequantify()` at critical points, or using `.pint.to()` to harmonize units before operations.

Install

• pip install pint-xarray Install pint-xarray

Imports

• pint_xarray

  import pint_xarray

  Importing `pint_xarray` is necessary to register the `.pint` accessor on xarray objects. It doesn't typically require direct symbol usage, just the import side-effect.
• DataArray.pint
  wrong:

  da.attrs['units'] = 'meter'

  correct:

  da.pint.quantify(...)

  The preferred way to attach units since v0.5.0 is via the `.pint` accessor, not direct attribute manipulation.
• Dataset.pint
  wrong:

  ds['var'].attrs['units'] = 'meter'

  correct:

  ds.pint.quantify(...)

  Units for Dataset variables should be managed via the `.pint` accessor for unit-awareness.

Quickstart

This quickstart demonstrates how to initialize `xarray.DataArray` and `xarray.Dataset` objects with physical units using the `.pint` accessor. It shows how to quantify variables and perform unit conversions, highlighting the core functionality of unit-aware data handling.

import xarray as xr
import pint_xarray # noqa: F401 (registers accessor)
import pint
import numpy as np

# Create a Pint UnitRegistry
ureg = pint.UnitRegistry()

# Create an xarray DataArray with units using the .pint accessor
da = xr.DataArray(
    np.array([10.0, 20.0, 30.0]),
    coords={"x": [0, 1, 2]},
    dims=("x",),
).pint.quantify(unit=ureg.meter)

print("Original DataArray:")
print(da)

# Perform a unit-aware operation: convert units
da_km = da.pint.to("kilometer")
print("\nConverted to kilometers:")
print(da_km)

# Example with a Dataset and multiple variables
ds = xr.Dataset(
    {
        "temperature": ("time", [25.0, 26.0]),
        "pressure": ("time", [1013.25, 1012.00])
    },
    coords={"time": [0, 1]}
).pint.quantify({"temperature": ureg.degC, "pressure": ureg.hPa})

print("\nOriginal Dataset variable 'temperature':")
print(ds["temperature"])

# Convert a Dataset variable's units
temp_kelvin = ds["temperature"].pint.to("kelvin")
print("\nTemperature in Kelvin:")
print(temp_kelvin)