FalseAlarmRate

FalseAlarmRate(min_offset=0, max_offset=0, time_unit='hour')[source]

False alarm rate, number of alarms that hit no event, per unit of time.

A true event at time T counts as hit by an alarm that falls in the window [T + min_offset, T + max_offset]. An alarm that falls in no event window is a false alarm. Further alarms inside a window that is already hit are not false alarms.

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.

The score is the number of false alarms, divided by the scored duration. The scored duration is the span of X.index, last value minus first value, so X should hold only the part of the stream that is scored.

This metric counts unmatched alarms only. With min_offset=0 and max_offset=0, the window is the event time itself, so an alarm is unmatched unless it lands exactly on an event. The default is therefore close to the number of alarms divided by the length of X, but an alarm that lands exactly on an event is not a false alarm.

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 duration is counted in time_unit, by default hours. Otherwise all values are in the units of X.index, and time_unit is ignored.

With no true events the score is still defined, as every alarm is a false alarm. With no alarms the score is 0, as long as X has a span. If X has no span, that is fewer than two time points, the rate is not defined, and nan is returned, even if there are no alarms.

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

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, with the default of 0, alarms after the event are false alarms. Same unit as min_offset. NaN raises a ValueError.
time_unitstr, default=”hour”: Unit in which the duration is counted, if X has a time index, so the score is false alarms per time_unit. Any unit accepted by pd.Timedelta, for instance "hour", "min", or "s". Ignored if X does not have a time index.

Examples

>>> import pandas as pd
>>> from sktime.performance_metrics.detection import FalseAlarmRate
>>> index = pd.date_range("2020-01-01", periods=7, freq="20min")
>>> X = pd.DataFrame({"foo": range(7)}, index=index)
>>> y_true = pd.DataFrame({"ilocs": [5]})
>>> y_pred = pd.DataFrame({"ilocs": [1, 4]})
>>> metric = FalseAlarmRate(min_offset=pd.Timedelta("-20min"))
>>> metric(y_true, y_pred, X)
0.5