Package: xarray-units
xarray-unitsxarray extension for handling unitsOverviewxarray-units is an import-only package that provides axarrayDataArray accessor.unitsfor handling units such as converting units and numeric operations considering units.Astropyis used as a backend.
Unlike similar implementations, xarray-units does not use a special data type to handle units, but uses the original data type in a DataArray.
This allows to continue to use powerful features such as parallel and lazy processing withDaskand/or user-defined DataArray subclasses.Installationpipinstallxarray-units==0.5.0Basic usagesSuppose the following imports will be commonly used in the examples:importxarrayasxrimportxarray_unitsSetting and unsetting unitsxarray-units sets units in DataArray attributes (.attrs) with the name"units":da_km=xr.DataArray([1,2,3]).units.set("km")print(da_km)<xarray.DataArray (dim_0: 3)>
array([1, 2, 3])
Dimensions without coordinates: dim_0
Attributes:
    units:    kmAnd the units can also be unset (deleted):da=da_km.units.unset()print(da)<xarray.DataArray (dim_0: 3)>
array([1, 2, 3])
Dimensions without coordinates: dim_0[!NOTE]
These are equivalent to manually un/setting the units in the DataArray attributes, but theunitsaccessor also check that the units are valid when setting.Converting units to othersxarray-units converts a DataArray with units to other units:da_km=xr.DataArray([1,2,3]).units.set("km")da_m=da_km.units.to("m")print(da_m)<xarray.DataArray (dim_0: 3)>
array([1000., 2000., 3000.])
Dimensions without coordinates: dim_0
Attributes:
    units:    mAstropyequivalenciescan also be used for equivalences between different units:fromastropy.unitsimportspectralda_mm=xr.DataArray([1,2,3]).units.set("mm")da_GHz=da_mm.units.to("GHz",spectral())print(da_GHz)<xarray.DataArray (dim_1: 3)>
array([299.792458  , 149.896229  ,  99.93081933])
Dimensions without coordinates: dim_0
Attributes:
    units:    GHz[!TIP]
There exist other accessor methods (e.g.decompose,like) for converting units.
Seethe package guidefor more details.Numeric operations considering unitsxarray-units performs numerical operations considering units when theunitsaccessor is attached to the DataArray on the left side of the operator:da_m=xr.DataArray([1000,2000,3000]).units.set("m")da_km=xr.DataArray([1,2,3]).units.set("km")da_sum_m=da_m.units+da_kmda_sum_km=da_km.units+da_mprint(da_sum_m)print(da_sum_km)<xarray.DataArray (dim_0: 3)>
array([2000., 4000., 6000.])
Dimensions without coordinates: dim_0
Attributes:
    units:    m

<xarray.DataArray (dim_0: 3)>
array([2., 4., 6.])
Dimensions without coordinates: dim_0
Attributes:
    units:    kmThe units of the DataArray after the operation follows those of the DataArray with theunitsaccessor.
The resulting data values will be therefore different depending on the order of the operation.
They are, of course, equal when considering units:da_eq=(da_sum_m.units==da_sum_km)print(da_eq)<xarray.DataArray (dim_0: 3)>
array([ True,  True,  True])
Dimensions without coordinates: dim_0[!IMPORTANT]
Because this feature is accessor-based, units are only considered for the operation right after theunitsaccessor.
Seemethod and operation chainsfor performing multiple operations at once.[!TIP]
There exist accessor methods corresponding to each operator (e.g.add→+,eq→==).
Seethe package guidefor more details.Formatting unitsxarray-units converts units tovarious string formats:da=xr.DataArray([1,2,3]).units.set("m / s^2")da_console=da.units.format("console")da_latex=da.units.format("latex")print(da_console)print(da_latex)<xarray.DataArray (dim_0: 3)>
array([1, 2, 3])
Dimensions without coordinates: dim_0
Attributes:
    units:    m s^-2

<xarray.DataArray (dim_0: 3)>
array([1, 2, 3])
Dimensions without coordinates: dim_0
Attributes:
    units:    $\mathrm{\frac{m}{s^{2}}}$This is useful, for example, when plotting a DataArray:da.units.format("latex").plot()[!NOTE]
By default, the units of the DataArray coordinates will also be formatted.Advanced usagesHandling units of coordinatesTheunitsaccessor has an option for handling units of DataArray coordinates.
For example, the following code will create a DataArray withxandycoordinates in units of meters:da_m=xr.DataArray([[1,2],[3,4]],dims=["x","y"]).units.set("deg_C")da_m=da_m.assign_coords(x=xr.DataArray([1000,2000],dims="x").units.set("m"),y=xr.DataArray([3000,4000],dims="y").units.set("m"),)print(da_m.x)print(da_m.y)<xarray.DataArray 'x' (x: 2)>
array([1000, 2000])
Coordinates:
  * x        (x) int64 1000 2000
Attributes:
    units:    m

<xarray.DataArray 'y' (y: 2)>
array([3000, 4000])
Coordinates:
  * y        (y) int64 3000 4000
Attributes:
    units:    mTo handling the units of the DataArray coordinates, use an optionoffor specifying them:da_km=da_m.units(of=["x","y"]).to("km")print(da_km.x)print(da_km.y)<xarray.DataArray 'x' (x: 2)>
array([1., 2.])
Coordinates:
  * x        (x) float64 1.0 2.0
Attributes:
    units:    km

<xarray.DataArray 'y' (y: 2)>
array([3., 4.])
Coordinates:
  * y        (y) float64 3.0 4.0
Attributes:
    units:    kmwhereofaccepts the name(s) of the coordinate(s).Method and operation chainsTheunitsaccessor has an optionchainfor chaining methods or operations while considering units:da_m=xr.DataArray([1,2,3]).units.set("m")da_s=xr.DataArray([1,2,3]).units.set("s")da_a=da_m.units(chain=2)/da_s/da_sprint(da_a)<xarray.DataArray (dim_0: 3)>
array([1.        , 0.5       , 0.33333333])
Dimensions without coordinates: dim_0
Attributes:
    units:    m / s2wherechainis the number of chained methods or operations.
This is equivalent to nesting theunitsaccessors:(da_m.units/da_s).units/da_sUse with static type checkingxarray-units provides a special type hintxarray_units.DataArraywith which type checkers can statically handle theunitsaccessor and its methods:fromxarray_unitsimportDataArrayda:DataArray=xr.DataArray([1,2,3]).units.set("km")[!TIP]xarray_units.DataArraywill be replaced byxarray.DataArrayat runtime, so it can also be used for creating and subclassingDataArray.Use without the units accessorxarray-units provides a functionxarray_units.unitsthat returns theunitsaccessor of a DataArray.
The following two codes are therefore equivalent:xr.DataArray([1,2,3]).units.set("km")fromxarray_unitsimportunitsunits(xr.DataArray([1,2,3])).set("km")