MetPy 1.0 API Changes¶

This is the overview of the changes to MetPy’s programming interface that are coming with the 1.0 release of MetPy. These include changes made to unify and clarify MetPy’s API to be more consistent throughout. Changes are categorized to help you find breakages and see how your code might need to change in upgrading to MetPy 1.0. You might find some functions in multiple categories. You can search this page for some of your commonly used functions to find any relevant breakages you might encounter.

Xarray support for function input/output¶

One of the most important changes you may run into is that many of the functions in metpy.calc would have only returned pint.Quantity even when provided xarray.DataArray. Now, MetPy will properly return a DataArray when provided one where able, except where otherwise explicitly stated. See the MetPy xarray tutorial for more information.

Positional argument name changes¶

Many of the functions in metpy.calc have had changes to the names of their positional arguments to make parameter names consistent among functions and make the documentation of parameters clearer for users. Functions in your code with only this change will be unaffected by the upgrade to MetPy 1.0 if the values are only specified positionally. For example,

wind_components(10. * units('m/s'), 225. * units.deg)

will work the same on MetPy before and after the upgrade to 1.0. However, if you specify these arguments by name, e.g.

wind_components(speed=10. * units('m/s'), wdir=225. * units.deg)

then you will see breakage upgrading to MetPy 1.0, where the wdir argument has been expanded as wind_direction. Common arguments changed here include rh to relative_humidity, heights to height, and dewpt to dewpoint, among others.

wind_components()

(speed, wdir)

(speed, wind_direction)

heat_index()

(temperature, rh, mask_undefined=True)

(temperature, relative_humidity, mask_undefined=True)

apparent_temperature()

(temperature, rh, speed, face_level_winds=False, mask_undefined=True)

(temperature, relative_humidity, speed, face_level_winds=False, mask_undefined=True)

geopotential_to_height()

(geopot)

(geopotential)

sigma_to_pressure()

(sigma, psfc, ptop)

(sigma, pressure_sfc, pressure_top)

absolute_momentum()

(u_wind, v_wind, index='index')

(u, v, index='index')

bunkers_storm_motion()

(pressure, u, v, heights)

(pressure, u, v, height)

bulk_shear()

(pressure, u, v, heights=None, bottom=None, depth=None)

(pressure, u, v, height=None, bottom=None, depth=None)

critical_angle()

(pressure, u, v, heights, stormu, stormv)

(pressure, u, v, height, u_storm, v_storm)

storm_relative_helicity()

(u, v, heights, depth, ...)

(height, u, v, depth, ...)

potential_vorticity_baroclinic()

(potential_temperature, pressure, u, v, dx, dy, lats)

(potential_temperature, pressure, u, v, dx=None, dy=None, latitude=None, x_dim=-1, y_dim=-2, vertical_dim=-3)

relative_humidity_from_dewpoint()

(temperature, dewpt)

(temperature, dewpoint)

temperature_from_potential_temperature()

(pressure, theta)

(pressure, potential_temperature)

dry_lapse()

(pressure, temperature, ref_pressure=None)

(pressure, temperature, reference_pressure=None, vertical_dim=0)

moist_lapse()

(pressure, temperature, ref_pressure=None)

(pressure, temperature, reference_pressure=None)

lcl()

(pressure, temperature, dewpt, max_iters=50, eps=1e-05)

(pressure, temperature, dewpoint, max_iters=50, eps=1e-05)

lfc()

(pressure, temperature, dewpt, parcel_temperature_profile=None, dewpt_start=None, which='top')

(pressure, temperature, dewpoint, parcel_temperature_profile=None, dewpoint_start=None, which='top')

el()

(pressure, temperature, dewpt, parcel_temperature_profile=None, which='top')

(pressure, temperature, dewpoint, parcel_temperature_profile=None, which='top')

parcel_profile()

(pressure, temperature, dewpt)

(pressure, temperature, dewpoint)

parcel_profile_with_lcl()

(pressure, temperature, dewpt)

(pressure, temperature, dewpoint)

vapor_pressure()

(pressure, mixing)

(pressure, mixing_ratio)

dewpoint_from_relative_humidity()

(temperature, rh)

(temperature, relative_humidity)

dewpoint()

(e)

(vapor_pressure)

mixing_ratio()

(part_press, tot_press, ...)

(partial_press, total_press, ...)

saturation_mixing_ratio()

(tot_press, temperature)

(total_press, temperature)

virtual_temperature()

(temperature, mixing, ...)

(temperature, mixing_ratio, ...)

virtual_potential_temperature()

(pressure, temperature, mixing, ...)

(pressure, temperature, mixing_ratio, ...)

density()

(pressure, temperature, mixing, ...)

(pressure, temperature, mixing_ratio, ...)

cape_cin()

(pressure, temperature, dewpt, ...)

(pressure, temperature, dewpoint, ...)

most_unstable_parcel()

(pressure, temperature, dewpoint, heights=None, ...)

(pressure, temperature, dewpoint, height=None, ...)

mixed_parcel()

(p, temperature, dewpt, parcel_start_pressure=None, heights=None, ....)

(pressure, temperature, dewpoint, parcel_start_pressure=None, height=None, ...)

dry_static_energy()

(heights, temperature)

(height, temperature)

moist_static_energy()

(heights, temperature, specific_humidity)

(height, temperature, specific_humidity)

thickness_hydrostatic()

(pressure, temperature, mixing=None, ...)

(pressure, temperature, mixing_ratio=None, ...)

brunt_vaisala_frequency_squared()

(heights, potential_temperature, axis=0)

(height, potential_temperature, vertical_dim=0)

brunt_vaisala_frequency()

(heights, potential_temperature, axis=0)

(height, potential_temperature, vertical_dim=0)

brunt_vaisala_period()

(heights, potential_temperature, axis=0)

(height, potential_temperature, vertical_dim=0)

static_stability()

(pressure, temperature, axis=0)

(pressure, temperature, vertical_dim=0)

vertical_velocity_pressure()

(w, pressure, temperature, mixing=0)

(w, pressure, temperature, mixing_ratio=0)

vertical_velocity()

(omega, pressure, temperature, mixing=0)

(omega, pressure, temperature, mixing_ratio=0)

get_layer_heights()

(heights, depth, *args, bottom=None, interpolate=True, with_agl=False)

(height, depth, *args, bottom=None, interpolate=True, with_agl=False)

Keyword-only argument name changes¶

Similar to the positional argument name changes above, some of the functions in metpy.calc have had names changed for keyword-only arguments. If you have specified any of the affected parameters in your code, these functions will break with the upgrade to MetPy 1.0. For example,

mean_pressure_weighted(pressure, temperature, heights=my_height_values)

will break as the heights keyword has changed to height.

mean_pressure_weighted()

(pressure, *args, heights=None, bottom=None, depth=None)

(pressure, *args, height=None, bottom=None, depth=None)

isentropic_interpolation()

(theta_levels, pressure, temperature, *args, axis=0, ...)

(levels, pressure, temperature, *args, vertical_dim=0, ...)

mixed_layer()

(p, *args, heights=None, ...)

(pressure, *args, height=None, ...)

get_layer()

(pressure, *args, heights=None, ...)

(pressure, *args, height=None, ...)

New keyword-only arguments¶

The following functions have had some of their positional or optional arguments changed to keyword-only arguments. As such, any use of these positionally, e.g.

vorticity(u, v, my_dx_values, my_dy_values)

will break, and you must specify

vorticity(u, v, dx=my_dx_values, dy=my_dy_values)

going forward.

precipitable_water()

(dewpt, pressure, bottom=None, top=None)

(pressure, dewpoint, *, bottom=None, top=None)

storm_relative_helicity()

(u, v, heights, depth, bottom=<Quantity(0, 'meter')>, storm_u=<Quantity(0.0, 'meter / second')>, storm_v=<Quantity(0.0, 'meter / second')>)

(height, u, v, depth, *, bottom=<Quantity(0, 'meter')>, storm_u=<Quantity(0.0, 'meter / second')>, storm_v=<Quantity(0.0, 'meter / second')>)

vorticity()

(u, v, dx, dy)

(u, v, *, dx=None, dy=None, x_dim=-1, y_dim=-2)

divergence()

(u, v, dx, dy)

(u, v, *, dx=None, dy=None, x_dim=-1, y_dim=-2)

Parameter re-ordering¶

Some functions in metpy.calc have had the ordering of their arguments rearranged. If you are specifying values positionally, e.g.

mixing_ratio_from_relative_humidity(75 * units.percent, 1013.25 * units.hPa,
                                    25 * units.degC)

these will break, as the signature ordering has changed from (relative_humidity, temperature, pressure) to (pressure, temperature, relative_humidity). If you have specified these arguments by name, however, e.g.

mixing_ratio_from_relative_humidity(relative_humidity=75 * units.percent,
                                    pressure=1015 * units.hPa, temperature=25 * units.degC)

then your code will function as before even with the updated signature ordering in MetPy 1.0.

precipitable_water()

(dewpt, pressure, bottom=None, top=None)

(pressure, dewpoint, *, bottom=None, top=None)

storm_relative_helicity()

(u, v, heights, depth, ...)

(height, u, v, depth, ...)

relative_humidity_wet_psychrometric()

(dry_bulb_temperature, web_bulb_temperature, pressure, **kwargs)

(pressure, dry_bulb_temperature, wet_bulb_temperature, **kwargs)

psychrometric_vapor_pressure_wet()

(dry_bulb_temperature, wet_bulb_temperature, pressure, ...

(pressure, dry_bulb_temperature, wet_bulb_temperature, ...

mixing_ratio_from_relative_humidity()

(relative_humidity, temperature, pressure)

(pressure, temperature, relative_humidity)

relative_humidity_from_mixing_ratio()

(mixing_ratio, temperature, pressure)

(pressure, temperature, mixing_ratio)

relative_humidity_from_specific_humidity()

(specific_humidity, temperature, pressure)

(pressure, temperature, specific_humidity)

dewpoint_from_specific_humidity()

(specific_humidity, temperature, pressure)

(pressure, temperature, specific_humidity)

specific_humidity_from_dewpoint()

(dewpoint, pressure)

(pressure, dewpoint)

Deltas and grid specification¶

Many of the functions in metpy.calc relating to vorticity and advection require information about the space between your data points. MetPy has generally standardized the interface for these functions to more explicitly receive dimension information and ordering with consistent parameter names across the board. Particularly, anywhere you may have been specifying dim_order before, you will now need to specify the particular axis number for the requisite dimensions explicitly. Importantly, MetPy’s new xarray functionality in 1.0 can handle these grid specifications for you if you are using it, and these signature updates were made to coincide with that functionality. Please see the the documentation for the following functions for more information.

shearing_deformation()

(u, v, dx, dy)

(u, v, dx=None, dy=None, x_dim=-1, y_dim=-2)

stretching_deformation()

(u, v, dx, dy)

(u, v, dx=None, dy=None, x_dim=-1, y_dim=-2)

total_deformation()

(u, v, dx, dy)

(u, v, dx=None, dy=None, x_dim=-1, y_dim=-2)

advection()

(scalar, wind, deltas)

(scalar, u=None, v=None, w=None, *, dx=None, dy=None, dz=None, x_dim=-1, y_dim=-2, vertical_dim=-3)

frontogenesis()

(thta, u, v, dx, dy, dim_order='yx')

(potential_temperature, u, v, dx=None, dy=None, x_dim=-1, y_dim=-2)

geostrophic_wind()

(heights, f, dx, dy)

(height, dx=None, dy=None, latitude=None, x_dim=-1, y_dim=-2)

ageostrophic_wind()

(heights, f, dx, dy, u, v, dim_order='yx')

(height, u, v, dx=None, dy=None, latitude=None, x_dim=-1, y_dim=-2)

absolute_vorticity()

(u, v, dx, dy, lats, dim_order='yx')

(u, v, dx=None, dy=None, latitude=None, x_dim=-1, y_dim=-2)

potential_vorticity_baroclinic()

(potential_temperature, pressure, u, v, dx, dy, lats)

(potential_temperature, pressure, u, v, dx=None, dy=None, latitude=None, x_dim=-1, y_dim=-2, vertical_dim=-3)

potential_vorticity_barotropic()

(heights, u, v, dx, dy, lats, dim_order='yx')

(height, u, v, dx=None, dy=None, latitude=None, x_dim=-1, y_dim=-2)

inertial_advective_wind()

(u, v, u_geostrophic, v_geostrophic, dx, dy, lats)

(u, v, u_geostrophic, v_geostrophic, dx=None, dy=None, latitude=None, x_dim=-1, y_dim=-2)

q_vector()

(u, v, temperature, pressure, dx, dy, static_stability=1)

(u, v, temperature, pressure, dx=None, dy=None, static_stability=1, x_dim=-1, y_dim=-2)

vorticity()

(u, v, dx, dy)

(u, v, *, dx=None, dy=None, x_dim=-1, y_dim=-2)

divergence()

(u, v, dx, dy)

(u, v, *, dx=None, dy=None, x_dim=-1, y_dim=-2)

lat_lon_grid_deltas()

(longitude, latitude, **kwargs)

(longitude, latitude, x_dim=-1, y_dim=-2, geod=None)

Latitude and f¶

In MetPy 1.0, geostrophic_wind() and ageostrophic_wind() have been changed to expect latitude instead of the coriolis parameter f, where we will calculate f using coriolis_parameter(). These have also been updated with the same new deltas and grid specification as above. If you are using MetPy’s new xarray functionality in 1.0, this can be automatically taken from your latitude coordinate information, if possible.