=====================
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
:mod:`metpy.calc` would have only returned :class:`pint.Quantity` even when provided
:class:`xarray.DataArray`. Now, MetPy will properly return a :class:`~xarray.DataArray` when
provided one where able, except where otherwise explicitly stated. See the
:doc:`MetPy xarray tutorial </tutorials/xarray_tutorial>` for more information.

Positional argument name changes
--------------------------------

Many of the functions in :mod:`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,

.. code-block:: python

   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.

.. code-block:: python

   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.

.. container:: api-table

  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.wind_components`                                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(speed, wdir)``                                                                                                |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(speed, wind_direction)``                                                                                      |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.heat_index`                                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(temperature, rh, mask_undefined=True)``                                                                       |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(temperature, relative_humidity, mask_undefined=True)``                                                        |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.apparent_temperature`                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(temperature, rh, speed, face_level_winds=False, mask_undefined=True)``                                        |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(temperature, relative_humidity, speed, face_level_winds=False, mask_undefined=True)``                         |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.geopotential_to_height`                                                                       |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(geopot)``                                                                                                     |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(geopotential)``                                                                                               |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.sigma_to_pressure`                                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(sigma, psfc, ptop)``                                                                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(sigma, pressure_sfc, pressure_top)``                                                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.absolute_momentum`                                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u_wind, v_wind, index='index')``                                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, index='index')``                                                                                        |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.bunkers_storm_motion`                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, u, v, heights)``                                                                                    |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, u, v, height)``                                                                                     |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.bulk_shear`                                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, u, v, heights=None, bottom=None, depth=None)``                                                      |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, u, v, height=None, bottom=None, depth=None)``                                                       |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.critical_angle`                                                                               |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, u, v, heights, stormu, stormv)``                                                                    |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, u, v, height, u_storm, v_storm)``                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.storm_relative_helicity`                                                                      |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, heights, depth, ...)``                                                                                  |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(height, u, v, depth, ...)``                                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.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)``|
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.relative_humidity_from_dewpoint`                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(temperature, dewpt)``                                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(temperature, dewpoint)``                                                                                      |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.temperature_from_potential_temperature`                                                       |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, theta)``                                                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, potential_temperature)``                                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.dry_lapse`                                                                                    |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, ref_pressure=None)``                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, reference_pressure=None, vertical_dim=0)``                                             |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.moist_lapse`                                                                                  |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, ref_pressure=None)``                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, reference_pressure=None)``                                                             |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.lcl`                                                                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpt, max_iters=50, eps=1e-05)``                                                      |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpoint, max_iters=50, eps=1e-05)``                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.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')``         |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.el`                                                                                           |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpt, parcel_temperature_profile=None, which='top')``                                 |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpoint, parcel_temperature_profile=None, which='top')``                              |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.parcel_profile`                                                                               |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpt)``                                                                               |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpoint)``                                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.parcel_profile_with_lcl`                                                                      |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpt)``                                                                               |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpoint)``                                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.vapor_pressure`                                                                               |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, mixing)``                                                                                           |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, mixing_ratio)``                                                                                     |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.dewpoint_from_relative_humidity`                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(temperature, rh)``                                                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(temperature, relative_humidity)``                                                                             |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.dewpoint`                                                                                     |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(e)``                                                                                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(vapor_pressure)``                                                                                             |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.mixing_ratio`                                                                                 |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(part_press, tot_press, ...)``                                                                                 |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(partial_press, total_press, ...)``                                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.saturation_mixing_ratio`                                                                      |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(tot_press, temperature)``                                                                                     |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(total_press, temperature)``                                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.virtual_temperature`                                                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(temperature, mixing, ...)``                                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(temperature, mixing_ratio, ...)``                                                                             |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.virtual_potential_temperature`                                                                |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, mixing, ...)``                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, mixing_ratio, ...)``                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.density`                                                                                      |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, mixing, ...)``                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, mixing_ratio, ...)``                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.cape_cin`                                                                                     |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpt, ...)``                                                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpoint, ...)``                                                                       |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.most_unstable_parcel`                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpoint, heights=None, ...)``                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpoint, height=None, ...)``                                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.mixed_parcel`                                                                                 |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(p, temperature, dewpt, parcel_start_pressure=None, heights=None, ....)``                                      |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, dewpoint, parcel_start_pressure=None, height=None, ...)``                              |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.dry_static_energy`                                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(heights, temperature)``                                                                                       |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(height, temperature)``                                                                                        |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.moist_static_energy`                                                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(heights, temperature, specific_humidity)``                                                                    |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(height, temperature, specific_humidity)``                                                                     |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.thickness_hydrostatic`                                                                        |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, mixing=None, ...)``                                                                    |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, mixing_ratio=None, ...)``                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.brunt_vaisala_frequency_squared`                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(heights, potential_temperature, axis=0)``                                                                     |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(height, potential_temperature, vertical_dim=0)``                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.brunt_vaisala_frequency`                                                                      |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(heights, potential_temperature, axis=0)``                                                                     |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(height, potential_temperature, vertical_dim=0)``                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.brunt_vaisala_period`                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(heights, potential_temperature, axis=0)``                                                                     |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(height, potential_temperature, vertical_dim=0)``                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.static_stability`                                                                             |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, axis=0)``                                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, temperature, vertical_dim=0)``                                                                      |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.vertical_velocity_pressure`                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(w, pressure, temperature, mixing=0)``                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(w, pressure, temperature, mixing_ratio=0)``                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.vertical_velocity`                                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(omega, pressure, temperature, mixing=0)``                                                                     |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(omega, pressure, temperature, mixing_ratio=0)``                                                               |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.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
:mod:`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,

.. parsed-literal::

   mean_pressure_weighted(pressure, temperature, **heights=my_height_values**)

will break as the ``heights`` keyword has changed to ``height``.

.. container:: api-table

  +----------------------------------------------------------------+
  | :func:`~metpy.calc.mean_pressure_weighted`                     |
  +----------------------------------------------------------------+
  | ``(pressure, *args, heights=None, bottom=None, depth=None)``   |
  +----------------------------------------------------------------+
  | ``(pressure, *args, height=None, bottom=None, depth=None)``    |
  +----------------------------------------------------------------+
  | :func:`~metpy.calc.isentropic_interpolation`                   |
  +----------------------------------------------------------------+
  | ``(theta_levels, pressure, temperature, *args, axis=0, ...)``  |
  +----------------------------------------------------------------+
  | ``(levels, pressure, temperature, *args, vertical_dim=0, ...)``|
  +----------------------------------------------------------------+
  | :func:`~metpy.calc.mixed_layer`                                |
  +----------------------------------------------------------------+
  | ``(p, *args, heights=None, ...)``                              |
  +----------------------------------------------------------------+
  | ``(pressure, *args, height=None, ...)``                        |
  +----------------------------------------------------------------+
  | :func:`~metpy.calc.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.

.. parsed-literal::

   vorticity(u, v, **my_dx_values**, **my_dy_values**)

will break, and you must specify

.. parsed-literal::

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

going forward.

.. container:: api-table

  +--------------------------------------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.precipitable_water`                                                                                                           |
  +--------------------------------------------------------------------------------------------------------------------------------------------------+
  | ``(dewpt, pressure, bottom=None, top=None)``                                                                                                     |
  +--------------------------------------------------------------------------------------------------------------------------------------------------+
  | ``(pressure, dewpoint, *, bottom=None, top=None)``                                                                                               |
  +--------------------------------------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.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')>)``|
  +--------------------------------------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.vorticity`                                                                                                                    |
  +--------------------------------------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, dx, dy)``                                                                                                                               |
  +--------------------------------------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, *, dx=None, dy=None, x_dim=-1, y_dim=-2)``                                                                                              |
  +--------------------------------------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.divergence`                                                                                                                   |
  +--------------------------------------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, dx, dy)``                                                                                                                               |
  +--------------------------------------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, *, dx=None, dy=None, x_dim=-1, y_dim=-2)``                                                                                              |
  +--------------------------------------------------------------------------------------------------------------------------------------------------+

Parameter re-ordering
---------------------

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

.. code-block:: python

   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.

.. code-block:: python

   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.

.. container:: api-table

  +---------------------------------------------------------------------+
  | :func:`~metpy.calc.precipitable_water`                              |
  +---------------------------------------------------------------------+
  | ``(dewpt, pressure, bottom=None, top=None)``                        |
  +---------------------------------------------------------------------+
  | ``(pressure, dewpoint, *, bottom=None, top=None)``                  |
  +---------------------------------------------------------------------+
  | :func:`~metpy.calc.storm_relative_helicity`                         |
  +---------------------------------------------------------------------+
  | ``(u, v, heights, depth, ...)``                                     |
  +---------------------------------------------------------------------+
  | ``(height, u, v, depth, ...)``                                      |
  +---------------------------------------------------------------------+
  | :func:`~metpy.calc.relative_humidity_wet_psychrometric`             |
  +---------------------------------------------------------------------+
  | ``(dry_bulb_temperature, web_bulb_temperature, pressure, **kwargs)``|
  +---------------------------------------------------------------------+
  | ``(pressure, dry_bulb_temperature, wet_bulb_temperature, **kwargs)``|
  +---------------------------------------------------------------------+
  | :func:`~metpy.calc.psychrometric_vapor_pressure_wet`                |
  +---------------------------------------------------------------------+
  | ``(dry_bulb_temperature, wet_bulb_temperature, pressure, ...``      |
  +---------------------------------------------------------------------+
  | ``(pressure, dry_bulb_temperature, wet_bulb_temperature, ...``      |
  +---------------------------------------------------------------------+
  | :func:`~metpy.calc.mixing_ratio_from_relative_humidity`             |
  +---------------------------------------------------------------------+
  | ``(relative_humidity, temperature, pressure)``                      |
  +---------------------------------------------------------------------+
  | ``(pressure, temperature, relative_humidity)``                      |
  +---------------------------------------------------------------------+
  | :func:`~metpy.calc.relative_humidity_from_mixing_ratio`             |
  +---------------------------------------------------------------------+
  | ``(mixing_ratio, temperature, pressure)``                           |
  +---------------------------------------------------------------------+
  | ``(pressure, temperature, mixing_ratio)``                           |
  +---------------------------------------------------------------------+
  | :func:`~metpy.calc.relative_humidity_from_specific_humidity`        |
  +---------------------------------------------------------------------+
  | ``(specific_humidity, temperature, pressure)``                      |
  +---------------------------------------------------------------------+
  | ``(pressure, temperature, specific_humidity)``                      |
  +---------------------------------------------------------------------+
  | :func:`~metpy.calc.dewpoint_from_specific_humidity`                 |
  +---------------------------------------------------------------------+
  | ``(specific_humidity, temperature, pressure)``                      |
  +---------------------------------------------------------------------+
  | ``(pressure, temperature, specific_humidity)``                      |
  +---------------------------------------------------------------------+
  | :func:`~metpy.calc.specific_humidity_from_dewpoint`                 |
  +---------------------------------------------------------------------+
  | ``(dewpoint, pressure)``                                            |
  +---------------------------------------------------------------------+
  | ``(pressure, dewpoint)``                                            |
  +---------------------------------------------------------------------+

Deltas and grid specification
-----------------------------

Many of the functions in :mod:`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
:doc:`xarray functionality </tutorials/xarray_tutorial>` 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.

.. container:: api-table

  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.shearing_deformation`                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, dx, dy)``                                                                                               |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, dx=None, dy=None, x_dim=-1, y_dim=-2)``                                                                 |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.stretching_deformation`                                                                       |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, dx, dy)``                                                                                               |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, dx=None, dy=None, x_dim=-1, y_dim=-2)``                                                                 |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.total_deformation`                                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, dx, dy)``                                                                                               |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, dx=None, dy=None, x_dim=-1, y_dim=-2)``                                                                 |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.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)``          |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.frontogenesis`                                                                                |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(thta, u, v, dx, dy, dim_order='yx')``                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(potential_temperature, u, v, dx=None, dy=None, x_dim=-1, y_dim=-2)``                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.geostrophic_wind`                                                                             |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(heights, f, dx, dy)``                                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(height, dx=None, dy=None, latitude=None, x_dim=-1, y_dim=-2)``                                                |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.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)``                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.absolute_vorticity`                                                                           |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, dx, dy, lats, dim_order='yx')``                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, dx=None, dy=None, latitude=None, x_dim=-1, y_dim=-2)``                                                  |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.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)``|
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.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)``                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.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)``                    |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.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)``                      |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.vorticity`                                                                                    |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, dx, dy)``                                                                                               |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, *, dx=None, dy=None, x_dim=-1, y_dim=-2)``                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.divergence`                                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, dx, dy)``                                                                                               |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(u, v, *, dx=None, dy=None, x_dim=-1, y_dim=-2)``                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | :func:`~metpy.calc.lat_lon_grid_deltas`                                                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(longitude, latitude, **kwargs)``                                                                              |
  +------------------------------------------------------------------------------------------------------------------+
  | ``(longitude, latitude, x_dim=-1, y_dim=-2, geod=None)``                                                         |
  +------------------------------------------------------------------------------------------------------------------+

Latitude and f
--------------

In MetPy 1.0, :func:`~metpy.calc.geostrophic_wind` and :func:`~metpy.calc.ageostrophic_wind`
have been changed to expect ``latitude`` instead of the coriolis parameter ``f``, where we
will calculate ``f`` using :func:`~metpy.calc.coriolis_parameter`. These have also been
updated with the same new `deltas and grid specification`_ as above. If you are using MetPy's
new :doc:`xarray functionality </tutorials/xarray_tutorial>` in 1.0, this can be automatically
taken from your latitude coordinate information, if possible.

.. container:: api-table

  +------------------------------------------------------------------------+
  | :func:`~metpy.calc.geostrophic_wind`                                   |
  +------------------------------------------------------------------------+
  | ``(heights, f, dx, dy)``                                               |
  +------------------------------------------------------------------------+
  | ``(height, dx=None, dy=None, latitude=None, x_dim=-1, y_dim=-2)``      |
  +------------------------------------------------------------------------+
  | :func:`~metpy.calc.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)``|
  +------------------------------------------------------------------------+

Moved, renamed, miscellaneous
-----------------------------

Functions that have been moved, replaced, or had their function signatures drastically altered.

.. container:: api-table

  +-----------------------------------------------------------------+
  | ``dewpoint_rh()``                                               |
  +-----------------------------------------------------------------+
  +-----------------------------------------------------------------+
  | :func:`~metpy.calc.dewpoint_from_relative_humidity`             |
  +-----------------------------------------------------------------+
  | ``grid_deltas_from_dataarray``                                  |
  +-----------------------------------------------------------------+
  +-----------------------------------------------------------------+
  | ``metpy.xarray``                                                |
  +-----------------------------------------------------------------+
  | :func:`~metpy.calc.first_derivative`                            |
  +-----------------------------------------------------------------+
  | ``(f, **kwargs)``                                               |
  +-----------------------------------------------------------------+
  | ``(f, axis=None, x=None, delta=None)``                          |
  +-----------------------------------------------------------------+
  | :func:`~metpy.calc.second_derivative`                           |
  +-----------------------------------------------------------------+
  | ``(f, **kwargs)``                                               |
  +-----------------------------------------------------------------+
  | ``(f, axis=None, x=None, delta=None)``                          |
  +-----------------------------------------------------------------+
  | :func:`~metpy.calc.gradient`                                    |
  +-----------------------------------------------------------------+
  | ``(f, **kwargs)``                                               |
  +-----------------------------------------------------------------+
  | ``(f, axes=None, coordinates=None, deltas=None)``               |
  +-----------------------------------------------------------------+
  | :func:`~metpy.calc.laplacian`                                   |
  +-----------------------------------------------------------------+
  | ``(f, **kwargs)``                                               |
  +-----------------------------------------------------------------+
  | ``(f, axes=None, coordinates=None, deltas=None)``               |
  +-----------------------------------------------------------------+