Usage of decorator check_units

[winash12]

I have this toy example

`
from metpy.units import check_units
import os
import xarray as xr
import boto3
from botocore import UNSIGNED
from botocore.config import Config

@check_units(umask='[speed]')
def test_decorator(umask,b):
u = umask

def main():
if (not os.path.isfile('gfs.t12z.pgrb2.0p25.f000')):

    client = boto3.client('s3', config=Config(signature_version=UNSIGNED))
    client.download_file('noaa-gfs-bdp-pds', 'gfs.20230809/12/atmos/gfs.t12z.pgrb2.0p25.f000', 'gfs.t12z.pgrb2.0p25.f000')

u850 = xr.open_dataset('gfs.t12z.pgrb2.0p25.f000', engine='cfgrib',backend_kwargs={'filter_by_keys':{'typeOfLevel': 'isobaricInhPa', 'shortName': 'u', 'level': 850}})
umask = u850.u
b = 4
test_decorator(umask,b)

main()`

When I run this I get this error -

Traceback (most recent call last): File "/home/winash12/testpython/testmetpydec.py", line 24, in <module> main() File "/home/winash12/testpython/testmetpydec.py", line 23, in main test_decorator(umask,b) File "/usr/local/lib/python3.9/dist-packages/metpy/units.py", line 332, in wrapper _check_units_inner_helper(func, sig, defaults, dims, *args, **kwargs) File "/usr/local/lib/python3.9/dist-packages/metpy/units.py", line 319, in _check_units_inner_helper raise ValueError(msg) ValueError: test_decoratorgiven arguments with incorrect units:umaskrequires "[speed]" but given "none" A xarray DataArray or numpy arrayx` can be assigned a unit as follows:
from metpy.units import units
x = x * units("m/s")
For more information see the Units Tutorial: https://unidata.github.io/MetPy/latest/tutorials/unit_tutorial.html

But the "umask` does have the units "m/s" as shown here .

`<xarray.DataArray 'u' (latitude: 721, longitude: 1440)> Size: 4MB
[1038240 values with dtype=float32]
Coordinates:
time datetime64[ns] 8B ...
step timedelta64[ns] 8B ...
isobaricInhPa float64 8B ...

• latitude (latitude) float64 6kB 90.0 89.75 89.5 ... -89.5 -89.75 -90.0
• longitude (longitude) float64 12kB 0.0 0.25 0.5 ... 359.2 359.5 359.8
  valid_time datetime64[ns] 8B ...
  Attributes: (12/29)
  GRIB_paramId: 131
  GRIB_dataType: fc
  GRIB_numberOfPoints: 1038240
  GRIB_typeOfLevel: isobaricInhPa
  GRIB_stepUnits: 1
  GRIB_stepType: instant
  ... ...
  GRIB_name: U component of wind
  GRIB_shortName: u
  GRIB_units: m s**-1
  long_name: U component of wind
  units: m s**-1
  standard_name: eastward_wind
  Traceback (most recent call last):
  File "/home/winash12/testpython/testmetpydec.py", line 26, in
  main()
  File "/home/winash12/testpython/testmetpydec.py", line 23, in main`

[DanielAdriaansen]

You may want to review this section about units and Xarray with MetPy:
https://unidata.github.io/MetPy/latest/tutorials/xarray_tutorial.html#units

Essentially your Xarray object has an attribute defining the units, but the data array inside the Xarray object is not itself unit-aware. The link details how to accomplish this using MetPy's quantify(): https://unidata.github.io/MetPy/latest/api/generated/metpy.xarray.html#metpy.xarray.MetPyDataArrayAccessor.quantify.

See if that helps!

[dopplershift]

That should work. MetPy's own calculations rely on our preprocess_and_wrap() decorator to automatically call .quantify() on all data that is passed in as an xarray DataArray.

[winash12]

Yes thanks for the explanation and how to use it. So we are in essence chaining decorators. Might I ask then if it's possible to mention in the function comments of check_units in units.py that the decorator preprocess_and_wrap from xarray.py must be "chained" to this decorator in order to use it in the proper way ?

One could argue that it's not always necessary to chain preprocess_and_wrap and check_units together and they need to be chained if and only if the arguments being passed to check_units are not an instance of Pint Quantity.

[dopplershift]

They are chained/separate because they perform different functions:

• check_units exists purely to provide better diagnostics by explicitly checking units on entry to a function, rather than failing in mysterious ways when calculations fail. This relies on having Pint Quantity instances for access to proper unit information.
• preprocess_and_wrap is our (scarily complex) Swiss army knife handling conversion of xarray inputs to appropriate inputs, including broadcasting and figuring out what dimensions are being used for e.g. x, y etc.

I'm always happy to merge PRs that improve our documentation. We could definitely improve the developer documentation for this to ease the pathways for contributors to MetPy. It won't be a high priority on our end because these decorators are not considered part of our public API, so we aren't intending to support use of these outside of MetPy.