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 leastmin_periodssoundings. The run is counted in time, on the 12-hourly grid from the first time invhdto the last, not in rows: a sounding missing fromvhdis 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) andend(12 hours after the last sounding, less one second), indexed byevent_idfrom 0.- Raises:
ValueError – If a time in
vhdis not a whole number of 12-hour steps from the first, or a time is repeated.- Return type:
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