Deprecate dewpoint_rh in favor of dewpoint_from_relative_humidity

docs/_templates/overrides/metpy.calc.rst

@@ -32,8 +32,8 @@ Moist Thermodynamics
       :toctree: ./
 
       dewpoint
+      dewpoint_from_relative_humidity
       dewpoint_from_specific_humidity
-      dewpoint_rh
       equivalent_potential_temperature
       mixing_ratio
       mixing_ratio_from_relative_humidity
@@ -196,6 +196,7 @@ Do not use these functions in new code, please see their documentation for their
    .. autosummary::
       :toctree: ./
 
+      dewpoint_rh
       get_wind_components
       get_wind_dir
       get_wind_speed

src/metpy/calc/thermo.py

@@ -15,7 +15,7 @@
                     find_intersections, first_derivative, get_layer)
 from .. import constants as mpconsts
 from ..cbook import broadcast_indices
-from ..deprecation import metpyDeprecation
+from ..deprecation import deprecated, metpyDeprecation
 from ..interpolate.one_dimension import interpolate_1d
 from ..package_tools import Exporter
 from ..units import atleast_1d, check_units, concatenate, units
@@ -741,7 +741,7 @@ def saturation_vapor_pressure(temperature):
 @exporter.export
 @preprocess_xarray
 @check_units('[temperature]', '[dimensionless]')
-def dewpoint_rh(temperature, rh):
+def dewpoint_from_relative_humidity(temperature, rh):
     r"""Calculate the ambient dewpoint given air temperature and relative humidity.
 
     Parameters
@@ -766,6 +766,22 @@ def dewpoint_rh(temperature, rh):
     return dewpoint(rh * saturation_vapor_pressure(temperature))
 
 
+@exporter.export
+@preprocess_xarray
+@deprecated('0.12', addendum=(' This function has been renamed '
+                              'dewpoint_from_relative_humidity.'),
+            pending=False)
+def dewpoint_rh(temperature, rh):
+    """Wrap dewpoint_from_relative_humidity for deprecated dewpoint_rh function."""
+    return dewpoint_from_relative_humidity(temperature, rh)
+
+
+dewpoint_rh.__doc__ = (dewpoint_from_relative_humidity.__doc__
+                       + '\n    .. deprecated:: 0.12.0\n        Function has been renamed to'
+                         ' `dewpoint_from_relative_humidity` and will be removed from MetPy '
+                         'in 1.0.0.')
+
+
 @exporter.export
 @preprocess_xarray
 @check_units('[pressure]')
@@ -784,7 +800,7 @@ def dewpoint(e):
 
     See Also
     --------
-    dewpoint_rh, saturation_vapor_pressure, vapor_pressure
+    dewpoint_from_relative_humidity, saturation_vapor_pressure, vapor_pressure
 
     Notes
     -----
@@ -2353,12 +2369,12 @@ def dewpoint_from_specific_humidity(specific_humidity, temperature, pressure):
 
     See Also
     --------
-    relative_humidity_from_mixing_ratio, dewpoint_rh
+    relative_humidity_from_mixing_ratio, dewpoint_from_relative_humidity
 
     """
-    return dewpoint_rh(temperature, relative_humidity_from_specific_humidity(specific_humidity,
-                                                                             temperature,
-                                                                             pressure))
+    return dewpoint_from_relative_humidity(temperature,
+                                           relative_humidity_from_specific_humidity(
+                                               specific_humidity, temperature, pressure))
 
 
 @exporter.export

tests/calc/test_thermo.py

@@ -9,8 +9,8 @@
 
 from metpy.calc import (brunt_vaisala_frequency, brunt_vaisala_frequency_squared,
                         brunt_vaisala_period, cape_cin, density, dewpoint,
-                        dewpoint_from_specific_humidity, dewpoint_rh,
-                        dry_lapse, dry_static_energy, el,
+                        dewpoint_from_relative_humidity, dewpoint_from_specific_humidity,
+                        dewpoint_rh, dry_lapse, dry_static_energy, el,
                         equivalent_potential_temperature,
                         exner_function, isentropic_interpolation, lcl, lfc, mixed_layer,
                         mixed_parcel, mixing_ratio, mixing_ratio_from_relative_humidity,
@@ -198,31 +198,41 @@ def test_sat_vapor_pressure_fahrenheit():
     assert_array_almost_equal(saturation_vapor_pressure(temp), real_es, 4)
 
 
-def test_basic_dewpoint_rh():
-    """Test dewpoint_rh function."""
+@check_and_silence_deprecation
+def test_deprecated_dewpoint_rh():
+    """Test deprecated dewpoint_rh function."""
     temp = np.array([30., 25., 10., 20., 25.]) * units.degC
     rh = np.array([30., 45., 55., 80., 85.]) / 100.
 
     real_td = np.array([11, 12, 1, 16, 22]) * units.degC
     assert_array_almost_equal(real_td, dewpoint_rh(temp, rh), 0)
 
 
-def test_scalar_dewpoint_rh():
-    """Test dewpoint_rh with scalar values."""
-    td = dewpoint_rh(10.6 * units.degC, 0.37)
+def test_basic_dewpoint_from_relative_humidity():
+    """Test dewpoint_from_relative_humidity function."""
+    temp = np.array([30., 25., 10., 20., 25.]) * units.degC
+    rh = np.array([30., 45., 55., 80., 85.]) / 100.
+
+    real_td = np.array([11, 12, 1, 16, 22]) * units.degC
+    assert_array_almost_equal(real_td, dewpoint_from_relative_humidity(temp, rh), 0)
+
+
+def test_scalar_dewpoint_from_relative_humidity():
+    """Test dewpoint_from_relative_humidity with scalar values."""
+    td = dewpoint_from_relative_humidity(10.6 * units.degC, 0.37)
     assert_almost_equal(td, 26. * units.degF, 0)
 
 
-def test_percent_dewpoint_rh():
-    """Test dewpoint_rh with rh in percent."""
-    td = dewpoint_rh(10.6 * units.degC, 37 * units.percent)
+def test_percent_dewpoint_from_relative_humidity():
+    """Test dewpoint_from_relative_humidity with rh in percent."""
+    td = dewpoint_from_relative_humidity(10.6 * units.degC, 37 * units.percent)
     assert_almost_equal(td, 26. * units.degF, 0)
 
 
-def test_warning_dewpoint_rh():
+def test_warning_dewpoint_from_relative_humidity():
     """Test that warning is raised for >120% RH."""
     with pytest.warns(UserWarning):
-        dewpoint_rh(10.6 * units.degC, 50)
+        dewpoint_from_relative_humidity(10.6 * units.degC, 50)
 
 
 def test_dewpoint():