forecasting

Forecasting regime — alarm-based metrics with explicit AlarmPolicy.

Two entry points: - evaluate(alarms, seizures, policy, …) — accepts pre-computed alarm

times; useful when alarms come from a different pipeline.

  • evaluate_stream(proba, times, seizures, policy, …) — accepts a continuous prediction stream (proba per timepoint); applies the policy’s threshold + refractory + merging to produce alarms, then evaluates. This is the gold-standard entry point — every reported number is reproducible from (proba, times, policy).

Also provides: - sweep_thresholds — sensitivity-vs-FP/hr ROC across a threshold sweep. - sweep_policies — same metrics across multiple AlarmPolicy values

(e.g. cadence ablation).

All metrics use the AlarmPolicy.fp_denominator convention. The Mormann- tradition default (“interictal”) excludes [seizure - sop - sph, seizure + sop] windows from the FP/hr denominator.

scitex_seizure_metrics.forecasting.bootstrap_ci(values, n_boot=1000, ci=0.95, rng_seed=0)[source]

Percentile bootstrap CI of the mean for a 1-D array.

Parameters:
scitex_seizure_metrics.forecasting.evaluate(alarm_times, seizure_times, policy, *, total_recording_time, n_surrogate=1000, surrogate='poisson', rng_seed=0, name='')[source]

Alarm-based forecasting evaluation under an explicit AlarmPolicy.

Parameters:

  • alarm_times – seconds-since-recording-start timestamps of alarms.

  • seizure_times – seconds-since-recording-start timestamps of true seizure onsets.

  • policy (AlarmPolicy) – AlarmPolicy describing SPH/SOP/cadence/refractory/etc.

  • total_recording_time (float) – total recording duration (seconds).

  • n_surrogate (int) – number of random surrogates to estimate the chance baseline for IoC.

  • surrogate (str) – name of registered surrogate (“poisson”, “periodic”, “persistence”, or any user-registered).

  • rng_seed (int) – surrogate RNG seed.

  • name (str) – identifier carried into the report.

Returns:

MetricsReport with the forecasting-regime fields populated.

Return type:

MetricsReport

scitex_seizure_metrics.forecasting.evaluate_stream(proba, times, seizure_times, policy, *, total_recording_time=None, n_surrogate=1000, surrogate='poisson', rng_seed=0, name='')[source]

Continuous-stream evaluation entry point — gold standard.

Threshold + dedupe (per AlarmPolicy) the proba stream, then call evaluate() on the derived alarms. Use this when you have per-window predictions and want fully-reproducible alarm-based metrics.

Parameters:
Return type:

MetricsReport

scitex_seizure_metrics.forecasting.sweep_policies(proba, times, seizure_times, policies, *, total_recording_time=None, n_surrogate=200, surrogate='poisson', rng_seed=0, name='')[source]

Same evaluation across a list of AlarmPolicy values (e.g. cadence or refractory ablation). Returns DataFrame with one row per policy plus the policy.describe() columns.

Parameters:
scitex_seizure_metrics.forecasting.sweep_thresholds(proba, times, seizure_times, policy, *, thresholds=None, total_recording_time=None, n_surrogate=200, surrogate='poisson', rng_seed=0, name='')[source]

Generate the sensitivity-vs-FP/hr operating curve.

Returns a pandas DataFrame with one row per threshold; columns include sensitivity, fp_per_hour, time_in_warning_frac, ioc.

Parameters: