pyepilepsy.metrics.compute_tiw

pyepilepsy.metrics.compute_tiw(y_pred_01: Series, tau: float, epoch_size: float, overlap: float, bad_mask: Series | None = None) → float

Extract the time in warning of the current predictions given a tau

The computation has been optimized using the following approach:

sort predictions and mask

remove bad_mask firings

extract time-continuous predictions. On each block:

get the firing indexes

apply the tiw from last firing index

apply the tiw on all tau seconds after all firings indexes

return the warning block + the last firing index

apply bad_mask firings again

Parameters:

y_pred_01pd.Series: The prediction series filled with 0 and 1. Index must be of type datetime64.
taufloat: The warning time to fire when a positive/preictal class is detected (in minutes). We must have be tau >= epoch_size
epoch_sizefloat: The epoch size in seconds
overlapfloat: The overlap between 2 successive epochs in seconds.
bad_maskpd.Series, optional: A mask to remove some warning windows (such as bad annotations). Must contains 1 and 0. 1 is to remove, 0 is to keep. If None, nothing is removed. The default is None.

Returns:

float: the duration of time in warning in seconds

Notes

In a cross-val context, the TiW is probably reduced because a group ends with the ictal segment, so if a warning is fired at the end, the time in warning that should be generated after the current time segment is not added. BUT, for global results, the time in warning is computed again based on all y_pred_01 tested groups and these missing time in warning segments are accounted for.

Examples

>>> import pandas as pd
>>> import numpy as np
>>> from pyepilepsy.metrics import compute_tiw
>>> y_pred_arr = [0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 1, 0, 0, 0, 0, 1, 1, 1, 1]
>>> datetime_index = np.hstack([
...     pd.date_range("09:00", "12:30", freq="30min").to_numpy(),
...     pd.date_range("14:00", "19:00", freq="30min").to_numpy()
... ])
>>> y_pred_01 = pd.Series(
...     data=y_pred_arr,
...     index=datetime_index
... )
>>> compute_tiw(
...     y_pred_01=y_pred_01,
...     tau=30,
...     epoch_size=60*40,
...     overlap=60*10,
...     bad_mask=None
... )
18000

>>> bad_mask = pd.Series(
...     data=[0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
...     index=datetime_index
... )
>>> compute_tiw(
...     y_pred_01=y_pred_01,
...     tau=30,
...     epoch_size=60*40,
...     overlap=60*10,
...     bad_mask=bad_mask
... )
16200