tephpy.sounding#

The Sounding data model (spec §3.4).

A Sounding is a frozen dataclass holding one ascent’s pressure/temperature/dewpoint/wind arrays as pint quantities on MetPy’s registry, plus optional station/time metadata and a derived legend label. Inputs are coerced and validated at construction — bad data fails at ingest, not mid-plot (spec §6) — and pressure is normalized to decreasing (surface-first) storage with all arrays reversed together, so downstream metpy.calc sees one orientation.

The pandas/xarray constructors consume the objects handed to them — neither library is imported at runtime — so import tephpy stays light (spec §10 item 10).

Notes#

Added in version 0.1.0.

Classes#

Sounding

One sounding: quantified profile arrays plus metadata (spec §3.4).

Module Contents#

class tephpy.sounding.Sounding[source]#

One sounding: quantified profile arrays plus metadata (spec §3.4).

Pressure and temperature are required; dewpoint and wind are optional, and the two wind fields must arrive together. Bare arrays need the units= mapping; a constructed Sounding always holds pint quantities on MetPy’s registry, with pressure stored decreasing (surface-first). NaN gaps are data everywhere except pressure.

Attributes:

pressurepint.Quantity: Level pressures; required, finite, and strictly monotonic (either direction accepted, normalized to decreasing).
temperaturepint.Quantity: Level temperatures; required.
dewpointpint.Quantity or None: Level dewpoints; where dewpoint and temperature are both non-NaN, dewpoint above temperature is rejected (equality — saturation — is physical).
wind_speedpint.Quantity or None: Level wind speeds; requires wind_direction.
wind_directionpint.Quantity or None: Level wind directions (degrees from north); requires wind_speed.
stationstr or None: Station identifier, e.g. "72357".
timedatetime.datetime or None: Launch time; numpy.datetime64 input is accepted, naive datetimes are read as UTC, and aware ones are converted to UTC.
labelstr or None: Legend text. When not given it derives as e.g. "72357 2013-05-20 12Z" if both station and time are present, else None — and None means no legend entry.
unitsmapping of str to str, optional: Construction-only (not stored): unit strings for bare-array fields, keyed by field name, e.g. units={"pressure": "hPa", "temperature": "degC"} (spec §5).

Raises:

DewpointExceedsTemperatureError: If dewpoint exceeds temperature at a level where both are non-NaN (equality — saturation — is physical and accepted).
NonMonotonicPressureError: If pressure is not strictly monotonic.
TephpyUnitsError: For a units= mapping naming an unknown field, unit-less bare arrays, ambiguous or unparsable units, or the wrong dimensionality.
TephpyValidationError: If a field holds non-numeric elements, the fields are not 1-D and equal-length over at least two levels, only one of the wind pair is given, or pressure is not finite at every level.
TypeError: If pressure or temperature is None, or time is neither a datetime nor a real numpy.datetime64 (NaT is rejected).

Notes

Added in version 0.1.0.

pressure: pint.Quantity#

temperature: pint.Quantity#

dewpoint: pint.Quantity | None = None#

wind_speed: pint.Quantity | None = None#

wind_direction: pint.Quantity | None = None#

station: str | None = None#

time: datetime.datetime | None = None#

label: str | None = None#

units: dataclasses.InitVar[collections.abc.Mapping[str, str] | None] = None#

classmethod from_dataframe(df: pandas.DataFrame, *, units: collections.abc.Mapping[str, str] | None = None, station: str | None = None, time: datetime.datetime | None = None, label: str | None = None, **column_map: str) → Sounding[source]#

Build a sounding from a pandas DataFrame (spec §3.4).

Column names default to the field names; column_map overrides per field (e.g. dewpoint="dwpt"). Columns are bare arrays, so the present fields need the units= mapping.

Parameters:

dfpandas.DataFrame: The profile table; must contain pressure and temperature columns.
unitsmapping of str to str, optional: Unit strings keyed by field name (spec §5).
stationstr, optional: Station identifier.
timedatetime.datetime, optional: Launch time; pandas.Timestamp and numpy.datetime64 are accepted.
labelstr, optional: Legend text override.
**column_mapstr: Field names mapped to their column names in df.

Returns:

Sounding: The validated sounding.

Raises:

KeyError: If a required or explicitly mapped column is missing.
TypeError: If column_map names an unknown field.

Notes

Added in version 0.1.0.

classmethod from_dataset(ds: xarray.Dataset, *, units: collections.abc.Mapping[str, str] | None = None, station: str | None = None, time: datetime.datetime | None = None, label: str | None = None, **var_map: str) → Sounding[source]#

Build a sounding from an xarray Dataset (spec §3.4).

Variable names default to the field names; var_map overrides per field. Units are read from each variable’s attrs["units"] (the xarray/CF convention); the units= mapping is the explicit override.

Parameters:

dsxarray.Dataset: The profile dataset; must contain pressure and temperature variables.
unitsmapping of str to str, optional: Unit strings keyed by field name, overriding attrs["units"].
stationstr, optional: Station identifier.
timedatetime.datetime, optional: Launch time; pandas.Timestamp and numpy.datetime64 are accepted.
labelstr, optional: Legend text override.
**var_mapstr: Field names mapped to their variable names in ds.

Returns:

Sounding: The validated sounding.

Raises:

KeyError: If a required or explicitly mapped variable is missing.
TephpyUnitsError: If a field has neither attrs["units"] nor a units= entry.
TypeError: If var_map names an unknown field.

Notes

Added in version 0.1.0.