Skip to content
sktime

EventTPR

EventTPR

EventTPR(min_offset=0, max_offset=0)[source]

Event true positive rate, share of true events hit by an alarm.

A true event at time T counts as hit if at least one alarm falls in the window [T + min_offset, T + max_offset]. The score is the number of hit events, divided by the number of true events.

The offsets are signed, negative is before the event and positive is after it. With offsets in the units of X.index, for an event at T:

  • min_offset=0, max_offset=0: only an alarm exactly at T.

  • min_offset=-3, max_offset=0: advance only, an alarm from 3 before T up to T. Late alarms do not count.

  • min_offset=0, max_offset=2: late only, an alarm from T up to 2 after T. Early alarms do not count.

  • min_offset=-3, max_offset=2: before and after, an alarm from 3 before T up to 2 after T.

  • min_offset=-10, max_offset=-2: at least 2 before T, and not earlier than 10 before T. An alarm at T does not count.

Positions in y_true and y_pred are iloc references into X, and are mapped through X.index before matching, so X is required. If X has a time index, the offsets are time offsets, for instance pd.Timedelta("-3s"). Otherwise they are in the units of X.index.

One alarm may hit more than one true event, if the event windows overlap.

Only point events are scored, so interval ilocs (segments) in y_true or y_pred raise a ValueError.

If there are no true events, the score is not defined, and nan is returned. If there are true events but no alarms, the score is 0.

Parameters:
min_offsetint, float, or time offset, default=0

Start of the hit window, relative to the event time T. Negative values let alarms before the event count. A time offset, for instance pd.Timedelta("-3s"), if X has a time index, otherwise a number in the units of X.index. A ValueError is raised if it is NaN, or after max_offset.

max_offsetint, float, or time offset, default=0

End of the hit window, relative to the event time T. Positive values let alarms after the event count, the default of 0 means that alarms after the event do not count. Same unit as min_offset. NaN raises a ValueError.

Examples

>>> import pandas as pd
>>> from sktime.performance_metrics.detection import EventTPR
>>> X = pd.DataFrame({"foo": range(10)})
>>> y_true = pd.DataFrame({"ilocs": [4, 8]})
>>> y_pred = pd.DataFrame({"ilocs": [3]})
>>> metric = EventTPR(min_offset=-2)
>>> metric(y_true, y_pred, X)
0.5