lair.pcaps.determine_pcap_events#

lair.pcaps.determine_pcap_events(vhd, threshold, min_periods=3)[source]#

Determine persistent cold air pool (PCAP) events from the valley heat deficit.

An event is a run of 12-hourly soundings whose valley heat deficit (VHD) is above threshold, lasting at least min_periods soundings. The run is counted in time, on the 12-hourly grid from the first time in vhd to the last, not in rows: a sounding missing from vhd is a gap in the run, as is a VHD that is NaN.

A gap of one sounding between two soundings above the threshold is taken as above, and counts toward min_periods. A longer gap, or one next to a sounding at or below the threshold, ends the event.

Parameters:
  • vhd (pd.Series) – The valley heat deficit [MJ/m^2], indexed by time, one value every 12 hours (the output of valleyheatdeficit()). Soundings may be missing or NaN.

  • threshold (float) – A sounding is in an event when its VHD is above this value [MJ/m^2]. Whiteman et al. (2014) use 4.04.

  • min_periods (int, optional) – The fewest soundings an event lasts, a gap of one included. Default is 3 (36 hours).

Returns:

pd.DataFrame – One row per event, with its start (the first sounding) and end (12 hours after the last sounding, less one second), indexed by event_id from 0.

Raises:

ValueError – If a time in vhd is not a whole number of 12-hour steps from the first, or a time is repeated.

Return type:

DataFrame

Examples

The missing 2024-01-02 12:00 sounding is one gap between two soundings above the threshold, so the event runs through it:

>>> import pandas as pd
>>> times = pd.to_datetime(
...     ["2024-01-01 12:00", "2024-01-02 00:00", "2024-01-03 00:00"]
... )
>>> vhd = pd.Series([5.0, 6.0, 5.5], index=times)
>>> determine_pcap_events(vhd, threshold=4.04)
                       start                 end
event_id
0        2024-01-01 12:00:00 2024-01-03 11:59:59