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.
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.
metpy.calc
pint.Quantity
xarray.DataArray
DataArray
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.
wdir
wind_direction
rh
relative_humidity
heights
height
dewpt
dewpoint
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, 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()
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()
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()
brunt_vaisala_period()
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)
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, ...)
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)
(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()
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.
(relative_humidity, temperature, pressure)
(pressure, temperature, relative_humidity)
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.
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_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_from_dewpoint()
(dewpoint, pressure)
(pressure, dewpoint)
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.
dim_order
shearing_deformation()
(u, v, dx=None, dy=None, x_dim=-1, y_dim=-2)
stretching_deformation()
total_deformation()
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_barotropic()
(heights, u, v, dx, dy, lats, dim_order='yx')
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)
lat_lon_grid_deltas()
(longitude, latitude, **kwargs)
(longitude, latitude, x_dim=-1, y_dim=-2, geod=None)
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.
latitude
f
coriolis_parameter()
Functions that have been moved, replaced, or had their function signatures drastically altered.
dewpoint_rh()
grid_deltas_from_dataarray
metpy.xarray
first_derivative()
(f, **kwargs)
(f, axis=None, x=None, delta=None)
second_derivative()
gradient()
(f, axes=None, coordinates=None, deltas=None)
laplacian()