.. _example:

examples
--------------

For use in a script:

.. code-block:: python

    from pathlib import Path

    from metpy.units import units
    import numpy as np

    from ecape.calc import calc_ecape

    sounding_loc = Path("./sounding.txt")
    data = np.genfromtxt(sounding_loc, delimiter=",")

    height = data[:, 0] * units("m")
    pressure = data[:, 1] * units("Pa")
    temperature = data[:, 2] * units("K")
    specific_humidity = data[:, 3] * units("kg/kg")
    u_wind = data[:, 4] * units("m/s")
    v_wind = data[:, 5] * units("m/s")

    cape_type = 'most_unstable'

    ecape = calc_ecape(height, pressure, temperature, specific_humidity, u_wind, v_wind, cape_type)
    print(f"{cape_type} ECAPE: {ecape}")


University of Wyoming soundings (trim below ground rows):

.. code-block:: python

    from pathlib import Path

    import metpy.calc as mpcalc
    import pandas as pd
    from metpy.units import pandas_dataframe_to_unit_arrays, units

    from ecape.calc import calc_ecape

    unit_dictionary = {
        "pressure": units("hPa"),
        "height": units("m"),
        "temperature": None,  # degC throws an error
        "dew_point": None,  # degC throws an error
        "relative_humidity": units("dimensionless"),
        "mixing_ratio": units("g/kg"),
        "direction": units("degree"),
        "speed": units("knot"),
        "theta": units("K"),
        "theta_e": units("K"),
        "theta_v": units("K"),
    }

    sounding_loc = Path("/path/to/UWyo_Sounding.csv")

    df = pd.read_csv(
        sounding_loc,
        header=None,
        names=[unit_dictionary.keys()],
    )

    # MetPy provides a useful solution to incorporating pint units and pd.DataFrames
    unit_array = pandas_dataframe_to_unit_arrays(df.dropna(), unit_dictionary)

    # fix a degC issue
    unit_array["temperature"] *= units("degC")
    unit_array["dew_point"] *= units("degC")

    # perform conversions.. fix provided in a future release
    unit_array["u"], unit_array["v"] = mpcalc.wind_components(unit_array["speed"], unit_array["direction"])
    unit_array["specific_humidity"] = mpcalc.specific_humidity_from_dewpoint(
        unit_array["pressure"], unit_array["dew_point"]
    )

    # let's say, in this case, the SPC MUCAPE calculation is 10% higher than MetPy's..
    # and we happen to be hopeful chasers
    metpy_mucape = mpcalc.most_unstable_cape_cin(
        unit_array["pressure"],
        unit_array["temperature"],
        unit_array["dew_point"]
    )[0]
    spc_cape = metpy_mucape * 1.10

    ecape = calc_ecape(
        unit_array["height"],
        unit_array["pressure"],
        unit_array["temperature"],
        unit_array["specific_humidity"],
        unit_array["u"],
        unit_array["v"],
        cape_type="most_unstable",
        undiluted_cape=spc_cape,
    )

    print(f"mucape: {spc_cape} \necape:  {ecape}")