DOCS: Add numerous calculation examples (Unidata#2588)

* DOCS: Add numerous calculation examples

src/metpy/calc/basic.py

@@ -625,6 +625,13 @@ def add_height_to_pressure(pressure, height):
     height : `pint.Quantity`
         Height above a pressure level
 
+    Examples
+    --------
+    >>> from metpy.calc import add_height_to_pressure
+    >>> from metpy.units import units
+    >>> add_height_to_pressure(1000 * units.hPa, 500 * units.meters)
+    <Quantity(941.953016, 'hectopascal')>
+
     Returns
     -------
     `pint.Quantity`
@@ -659,6 +666,13 @@ def add_pressure_to_height(height, pressure):
     `pint.Quantity`
         The corresponding height value for the pressure above the height level
 
+    Examples
+    --------
+    >>> from metpy.calc import add_pressure_to_height
+    >>> from metpy.units import units
+    >>> add_pressure_to_height(1000 * units.meters, 100 * units.hPa)
+    <Quantity(1.96117548, 'kilometer')>
+
     See Also
     --------
     pressure_to_height_std, height_to_pressure_std, add_height_to_pressure
@@ -690,6 +704,15 @@ def sigma_to_pressure(sigma, pressure_sfc, pressure_top):
     `pint.Quantity`
         Pressure values at the given sigma levels
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from metpy.calc import sigma_to_pressure
+    >>> from metpy.units import units
+    >>> sigma_levs = np.linspace(0, 1, 10)
+    >>> sigma_to_pressure(sigma_levs, 1000 * units.hPa, 10 * units.hPa)
+    <Quantity([  10.  120.  230.  340.  450.  560.  670.  780.  890. 1000.], 'hectopascal')>
+
     Notes
     -----
     Sigma definition adapted from [Philips1957]_:
@@ -1156,7 +1179,7 @@ def altimeter_to_station_pressure(altimeter_value, height):
     gamma = lapse rate in [NOAA1976]_ standard atmosphere below the isothermal layer
     :math:`6.5^{\circ}C. km.^{-1}`
 
-    :math:`t_{0}` = standard sea-level temperature 288 K
+    :math:`T_{0}` = standard sea-level temperature 288 K
 
     :math:`H_{b} =` station elevation in meters (elevation for which station pressure is given)
 

src/metpy/calc/indices.py

@@ -127,6 +127,15 @@ def mean_pressure_weighted(pressure, *args, height=None, bottom=None, depth=None
     list of `pint.Quantity`
         list of layer mean value for each profile in args
 
+    Examples
+    --------
+    >>> from metpy.calc import mean_pressure_weighted
+    >>> from metpy.units import units
+    >>> p = [1000, 850, 700, 500] * units.hPa
+    >>> T = [30, 15, 5, -5] * units.degC
+    >>> mean_pressure_weighted(p, T)
+    [<Quantity(298.54368, 'kelvin')>]
+
     Notes
     -----
     Only functions on 1D profiles (not higher-dimension vertical cross sections or grids).
@@ -191,6 +200,20 @@ def bunkers_storm_motion(pressure, u, v, height):
     wind_mean: (`pint.Quantity`, `pint.Quantity`)
         Scalar U- and V- components of surface to 6 km mean flow
 
+    Examples
+    --------
+    >>> from metpy.calc import bunkers_storm_motion, wind_components
+    >>> from metpy.units import units
+    >>> p = [1000, 925, 850, 700, 500, 400] * units.hPa
+    >>> h = [250, 700, 1500, 3100, 5720, 7120] * units.meters
+    >>> wdir = [165, 180, 190, 210, 220, 250] * units.degree
+    >>> sped = [5, 15, 20, 30, 50, 60] * units.knots
+    >>> u, v = wind_components(sped, wdir)
+    >>> bunkers_storm_motion(p, u, v, h)
+    (<Quantity([22.73539654 10.27331352], 'knot')>,
+    <Quantity([ 7.27954821 34.99751866], 'knot')>,
+    <Quantity([15.00747237 22.63541609], 'knot')>)
+
     Notes
     -----
     Only functions on 1D profiles (not higher-dimension vertical cross sections or grids).
@@ -273,6 +296,17 @@ def bulk_shear(pressure, u, v, height=None, bottom=None, depth=None):
     v_shr: `pint.Quantity`
         V-component of layer bulk shear
 
+    Examples
+    --------
+    >>> from metpy.calc import bulk_shear, wind_components
+    >>> from metpy.units import units
+    >>> p = [1000, 925, 850, 700, 500] * units.hPa
+    >>> wdir = [165, 180, 190, 210, 220] * units.degree
+    >>> sped = [5, 15, 20, 30, 50] * units.knots
+    >>> u, v = wind_components(sped, wdir)
+    >>> bulk_shear(p, u, v)
+    (<Quantity(2.41943319, 'knot')>, <Quantity(11.6920573, 'knot')>)
+
     Notes
     -----
     Only functions on 1D profiles (not higher-dimension vertical cross sections or grids).
@@ -326,6 +360,14 @@ def supercell_composite(mucape, effective_storm_helicity, effective_shear):
     `pint.Quantity`
         Supercell composite
 
+    Examples
+    --------
+    >>> from metpy.calc import supercell_composite
+    >>> from metpy.units import units
+    >>> supercell_composite(2500 * units('J/kg'), 125 * units('m^2/s^2'),
+    ...                     50 * units.knot).to_base_units()
+    <Quantity([6.25], 'dimensionless')>
+
     """
     effective_shear = np.clip(np.atleast_1d(effective_shear), None, units.Quantity(20, 'm/s'))
     effective_shear[effective_shear < units.Quantity(10, 'm/s')] = units.Quantity(0, 'm/s')
@@ -377,6 +419,14 @@ def significant_tornado(sbcape, surface_based_lcl_height, storm_helicity_1km, sh
     `pint.Quantity`
         Significant tornado parameter
 
+    Examples
+    --------
+    >>> from metpy.calc import significant_tornado
+    >>> from metpy.units import units
+    >>> significant_tornado(3000 * units('J/kg'), 750 * units.meters,
+    ...                     150 * units('m^2/s^2'), 25 * units.knot).to_base_units()
+    <Quantity([1.28611111], 'dimensionless')>
+
     """
     surface_based_lcl_height = np.clip(np.atleast_1d(surface_based_lcl_height),
                                        units.Quantity(1000., 'm'), units.Quantity(2000., 'm'))
@@ -430,6 +480,18 @@ def critical_angle(pressure, u, v, height, u_storm, v_storm):
     `pint.Quantity`
         Critical angle in degrees
 
+    Examples
+    --------
+    >>> from metpy.calc import critical_angle, wind_components
+    >>> from metpy.units import units
+    >>> p = [1000, 925, 850, 700, 500, 400] * units.hPa
+    >>> h = [250, 700, 1500, 3100, 5720, 7120] * units.meters
+    >>> wdir = [165, 180, 190, 210, 220, 250] * units.degree
+    >>> sped = [5, 15, 20, 30, 50, 60] * units.knots
+    >>> u, v = wind_components(sped, wdir)
+    >>> critical_angle(p, u, v, h, 7 * units.knots, 7 * units.knots)
+    <Quantity(67.0942521, 'degree')>
+
     Notes
     -----
     Only functions on 1D profiles (not higher-dimension vertical cross sections or grids).

src/metpy/calc/kinematics.py

@@ -622,6 +622,24 @@ def storm_relative_helicity(height, u, v, depth, *, bottom=None, storm_u=None, s
     `pint.Quantity`
         Total storm-relative helicity
 
+    Examples
+    --------
+    >>> from metpy.calc import storm_relative_helicity, wind_components
+    >>> from metpy.units import units
+    >>> # set needed values of pressure, height, wind direction/speed
+    >>> p = [1000, 925, 850, 700, 500, 400] * units.hPa
+    >>> h = [250, 700, 1500, 3100, 5720, 7120] * units.meters
+    >>> wdir = [165, 180, 190, 210, 220, 250] * units.degree
+    >>> sped = [5, 15, 20, 30, 50, 60] * units.knots
+    >>> # compute wind components
+    >>> u, v = wind_components(sped, wdir)
+    >>> # compute SRH with a storm vector
+    >>> storm_relative_helicity(h, u, v, depth=1 * units.km,
+    ...                         storm_u=7 * units('m/s'), storm_v=7 * units('m/s'))
+    (<Quantity(49.6086162, 'meter ** 2 / second ** 2')>,
+    <Quantity(0.0, 'meter ** 2 / second ** 2')>,
+    <Quantity(49.6086162, 'meter ** 2 / second ** 2')>)
+
     Notes
     -----
     Only functions on 1D profiles (not higher-dimension vertical cross sections or grids).