MeanDetectionOffset

MeanDetectionOffset(min_offset=0, max_offset=0, time_unit='s')[source]

Mean detection offset, how far the earliest alarm is from each event.

A true event at time T counts as hit if at least one alarm falls in the window [T + min_offset, T + max_offset]. For each hit event, the detection offset is the time of the earliest alarm in its window, minus T. The score is the mean detection offset over hit events only.

The offset is signed in the same way as the window: it is negative for an alarm before the event, and positive for a late hit, which can only happen if max_offset is above 0. An earlier alarm gives a smaller score, so lower is better.

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.

Missed events do not enter the mean. Read this score together with EventTPR, which reports how many events were hit at all.

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"), and the score is returned as a number of time_unit. Otherwise all values are in the units of X.index.

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

If there are no true events, or no event is hit, the score is not defined, and nan is returned.

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.
time_unitstr, default=”s”: Unit of the returned score, if X has a time index. Any unit accepted by pd.Timedelta, for instance "s", "ms", "min", or "h". Ignored if X does not have a time index.

Examples

>>> import pandas as pd
>>> from sktime.performance_metrics.detection import MeanDetectionOffset
>>> index = pd.date_range("2020-01-01", periods=20, freq="s")
>>> X = pd.DataFrame({"foo": range(20)}, index=index)
>>> y_true = pd.DataFrame({"ilocs": [5, 15]})
>>> y_pred = pd.DataFrame({"ilocs": [2, 14]})
>>> metric = MeanDetectionOffset(min_offset=pd.Timedelta("-3s"))
>>> metric(y_true, y_pred, X)
-2.0