{"id":10038,"library":"pint-xarray","title":"Pint-Xarray","description":"pint-xarray provides an interface between Pint (physical units library) and xarray (labeled multi-dimensional arrays). It enables attaching units to `xarray.DataArray` and `xarray.Dataset` objects, performing unit-aware computations, and ensuring dimensional consistency, making scientific data processing more robust. It is currently at version 0.6.1 and sees active development with releases typically tied to feature additions and bug fixes.","status":"active","version":"0.6.1","language":"en","source_language":"en","source_url":"https://github.com/pint-xarray/pint-xarray","tags":["xarray","pint","units","physical-quantities","scientific-computing","data-analysis"],"install":[{"cmd":"pip install pint-xarray","lang":"bash","label":"Install pint-xarray"}],"dependencies":[{"reason":"Core dependency for labeled multi-dimensional arrays.","package":"xarray"},{"reason":"Core dependency for physical units management.","package":"pint"}],"imports":[{"note":"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.","symbol":"pint_xarray","correct":"import pint_xarray"},{"note":"The preferred way to attach units since v0.5.0 is via the `.pint` accessor, not direct attribute manipulation.","wrong":"da.attrs['units'] = 'meter'","symbol":"DataArray.pint","correct":"da.pint.quantify(...)"},{"note":"Units for Dataset variables should be managed via the `.pint` accessor for unit-awareness.","wrong":"ds['var'].attrs['units'] = 'meter'","symbol":"Dataset.pint","correct":"ds.pint.quantify(...)"}],"quickstart":{"code":"import xarray as xr\nimport pint_xarray # noqa: F401 (registers accessor)\nimport pint\nimport numpy as np\n\n# Create a Pint UnitRegistry\nureg = pint.UnitRegistry()\n\n# Create an xarray DataArray with units using the .pint accessor\nda = xr.DataArray(\n    np.array([10.0, 20.0, 30.0]),\n    coords={\"x\": [0, 1, 2]},\n    dims=(\"x\",),\n).pint.quantify(unit=ureg.meter)\n\nprint(\"Original DataArray:\")\nprint(da)\n\n# Perform a unit-aware operation: convert units\nda_km = da.pint.to(\"kilometer\")\nprint(\"\\nConverted to kilometers:\")\nprint(da_km)\n\n# Example with a Dataset and multiple variables\nds = xr.Dataset(\n    {\n        \"temperature\": (\"time\", [25.0, 26.0]),\n        \"pressure\": (\"time\", [1013.25, 1012.00])\n    },\n    coords={\"time\": [0, 1]}\n).pint.quantify({\"temperature\": ureg.degC, \"pressure\": ureg.hPa})\n\nprint(\"\\nOriginal Dataset variable 'temperature':\")\nprint(ds[\"temperature\"])\n\n# Convert a Dataset variable's units\ntemp_kelvin = ds[\"temperature\"].pint.to(\"kelvin\")\nprint(\"\\nTemperature in Kelvin:\")\nprint(temp_kelvin)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Replace calls to `pint_xarray.convert_units(obj, unit)` with `obj.pint.to(unit)`.","message":"The `convert_units` function (e.g., `pint_xarray.convert_units(da, 'meter')`) has been removed in favor of the `.pint.to()` accessor method.","severity":"deprecated","affected_versions":">=0.5.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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.","error":"AttributeError: 'DataArray' object has no attribute 'pint'"},{"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).","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.","error":"pint.errors.DimensionalityError: Cannot convert from 'meter' to 'second'"}]}