tephpy.plotting.shading
=======================

.. py:module:: tephpy.plotting.shading

.. autoapi-nested-parse::

   CAPE/CIN shading geometry for the tephigram (spec §3.2).

   Free builders in the ``isopleths`` pattern: pure functions over bare numpy
   arrays in diagram-native units (hPa, °C — the spec §5 exemption) that
   return closed polygons in (temperature, theta) space, headlessly testable.
   ``TephigramAxes.shade_cape``/``shade_cin`` draw them through the tephigram
   transform as one compound-path ``PathPatch`` per call.

   Both curves are sampled onto their merged pressure grid along the drawn
   polylines — the straight segments in tephigram (x, y) space that
   matplotlib draws between profile levels — with a vertex inserted at each
   exact segment intersection, so the fill closes on the plotted lines at
   every scale (any other interpolation bows away from the drawn chords
   between levels). The regions are bounded as :func:`metpy.calc.cape_cin`
   integrates (its ``which_lfc="bottom"``/``which_el="top"`` defaults): CAPE is the
   positive-buoyancy region between the LFC — the bottom of the lowest
   positive run at or above the LCL — and the EL — the top of the highest
   such run, which is the profile top while the parcel is still buoyant
   there; CIN is the negative-buoyancy region between the parcel start and
   the LFC. With no LFC there is neither region (``cape_cin`` returns
   ``0 J/kg`` for both). Two documented divergences from the *numbers*:
   ``cape_cin`` finds its bounds on virtual-temperature profiles and
   integrates the net virtual-temperature difference (Doswell & Rasmussen
   1994), neither of which the plotted temperature curves can show — the
   shading is the drawn-curve region between the same rules' bounds, and the
   annotated J/kg number remains the quantitative truth.

   ..
       !! processed by numpydoc !!


Functions
---------

.. autoapisummary::

   tephpy.plotting.shading.cape_polygons
   tephpy.plotting.shading.cin_polygons


Module Contents
---------------

.. py:function:: cape_polygons(pressure: numpy.typing.ArrayLike, temperature: numpy.typing.ArrayLike, parcel_pressure: numpy.typing.ArrayLike, parcel_temperature: numpy.typing.ArrayLike, *, lcl_pressure: float) -> list[numpy.typing.NDArray[numpy.float64]]

   
   Build the CAPE region's closed polygons (spec §3.2).


   :Parameters:

       **pressure** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Environment pressures in hPa, strictly decreasing.

       **temperature** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Environment temperatures in degrees Celsius; NaN gaps break the
           region.

       **parcel_pressure** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Parcel-path pressures in hPa, strictly decreasing.

       **parcel_temperature** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Parcel-path temperatures in degrees Celsius.

       **lcl_pressure** : :class:`python:float`
           Pressure of the LCL the parcel uses, in hPa; buoyancy below it
           never counts towards CAPE.



   :Returns:

       :class:`python:list` of :obj:`numpy.ndarray`
           One ``(N, 2)`` closed polygon in (temperature, theta) space per
           uninterrupted positive-buoyancy run — plural when the region is
           interrupted, empty when there is no CAPE (0 is an answer, not an
           error; spec §6).











   ..
       !! processed by numpydoc !!

.. py:function:: cin_polygons(pressure: numpy.typing.ArrayLike, temperature: numpy.typing.ArrayLike, parcel_pressure: numpy.typing.ArrayLike, parcel_temperature: numpy.typing.ArrayLike, *, lcl_pressure: float) -> list[numpy.typing.NDArray[numpy.float64]]

   
   Build the CIN region's closed polygons (spec §3.2).


   :Parameters:

       **pressure** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Environment pressures in hPa, strictly decreasing.

       **temperature** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Environment temperatures in degrees Celsius; NaN gaps break the
           region.

       **parcel_pressure** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Parcel-path pressures in hPa, strictly decreasing.

       **parcel_temperature** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Parcel-path temperatures in degrees Celsius.

       **lcl_pressure** : :class:`python:float`
           Pressure of the LCL the parcel uses, in hPa; it locates the LFC
           that bounds the region.



   :Returns:

       :class:`python:list` of :obj:`numpy.ndarray`
           One ``(N, 2)`` closed polygon in (temperature, theta) space per
           uninterrupted negative-buoyancy run between the parcel start and
           the LFC — empty when there is no LFC (``cape_cin`` reports both
           CAPE and CIN as zero then) or no inhibition below it.











   ..
       !! processed by numpydoc !!