pyhctsa.operations.extreme_events.extreme_event_order

pyhctsa.operations.extreme_events.extreme_event_order(y, extreme_thresh=0.05)

Temporal patterning of positive vs. negative extreme events.

Labels each point in the top/bottom extreme_thresh fraction of the distribution as a positive- or negative-direction ‘extreme event’ (raw threshold exceedances, not declustered peaks), then asks not just how often each type occurs but how the two types are ordered in time relative to each other: does a positive extreme tend to be followed by another positive one (clustering by sign), or does the sequence alternate?

Parameters:
y : array-like

The input time series (assumed z-scored).

extreme_thresh : float, optional

The proportion of points (in each direction) to count as ‘extreme’; must be in (0, 0.5) so that the two tails cannot overlap. Default is 0.05.

Returns:

Dictionary containing:

  • propPosEvents: proportion of extreme events that are positive-direction.

  • meanInterval, cvInterval: mean (in samples) and coefficient of variation of the inter-event intervals of the combined (both-direction) event sequence.

  • meanIntervalPos, cvIntervalPos, meanIntervalNeg, cvIntervalNeg: the same, computed within each direction’s own event sub-sequence.

  • alternationRate: proportion of consecutive event pairs whose direction differs.

  • propPN, propNP: proportion of consecutive event pairs that switch positive-to-negative and negative-to-positive (they sum to alternationRate).

  • meanIntervalPN, cvIntervalPN, meanIntervalNP, cvIntervalNP: mean and coefficient of variation of the gaps between successive PN (NP) switches, timestamped at the later (post-switch) event.

  • lzComplexity: normalized Lempel-Ziv complexity (Michael Small’s MS_complexitybs) of the 0/1 event-direction sequence. NaN with fewer than 10 events, or if all events have the same direction.

Outputs that need at least two events (the intervals and alternation measures) are NaN otherwise.

Return type:

dict