physioex.train.stats

Per-subject metric aggregation (mean / std / confidence interval).

The pooled metrics computed by Trainer.evaluate / Trainer.voting_evaluate answer “how good is the model overall”, but sleep-staging results are reported per subject: each recording yields one score and we summarise the distribution across subjects (mean +/- std, confidence interval). This module turns a list of per-subject (preds, targets) tensors into those aggregates and renders a confusion-matrix figure for logging.

Standard sleep stage labels: W=0, N1=1, N2=2, N3=3, REM=4.

Functions

aggregate(per_subject[, ci_method, ...])	Aggregate per-subject values into mean / std / confidence interval.
aggregated_scalars(aggregated)	Flatten an aggregate() result into a scalar mapping for logging.
confusion_matrix_figure(preds, targets[, ...])	Render a confusion matrix as a matplotlib figure for logging.
figure_from_cm(cm[, class_names])	Render an already-computed confusion matrix tensor/array as a figure.
per_subject_metrics(preds_list, ...[, ...])	Compute scalar and per-class metrics for each subject.

physioex.train.stats.aggregate(per_subject, ci_method='bootstrap', n_bootstrap=1000, ci=0.95, seed=42)

Aggregate per-subject values into mean / std / confidence interval.

Parameters

per_subject:

Output of per_subject_metrics() (metric key -> list of values).

ci_method:

"bootstrap" (percentile bootstrap over subjects, robust) or "normal" (mean +/- z * std / sqrt(n)). Falls back to just the mean when fewer than two subjects are available.

n_bootstrap:

Number of bootstrap resamples (only for ci_method="bootstrap").

ci:

Confidence level (default 0.95).

Returns

dict mapping each metric key to {"mean", "std", "ci_low", "ci_high", "n"}.

Parameters:

• per_subject (Dict[str, List[float]])

• ci_method (str)

• n_bootstrap (int)

• ci (float)

• seed (int)

Return type:

Dict[str, Dict[str, float]]

physioex.train.stats.aggregated_scalars(aggregated)

Flatten an aggregate() result into a scalar mapping for logging.

Produces keys like "eval/f1/N2/mean" and "eval/f1/N2/std" so a logger backend can record them via log_scalars.

Parameters:

aggregated (Dict[str, Dict[str, float]])

Return type:

Dict[str, float]

physioex.train.stats.confusion_matrix_figure(preds, targets, n_classes=None, ignore_index=-1, normalize='targets', class_names=None)

Render a confusion matrix as a matplotlib figure for logging.

normalize="targets" gives per-true-class recall rows (the usual sleep hypnogram view). Returns a matplotlib.figure.Figure.

Parameters:

• preds (Tensor)

• targets (Tensor)

• n_classes (int | None)

• ignore_index (int)

• normalize (str | bool)

• class_names (Sequence[str] | None)

physioex.train.stats.figure_from_cm(cm, class_names=None)

Render an already-computed confusion matrix tensor/array as a figure.

Parameters:

class_names (Sequence[str] | None)

physioex.train.stats.per_subject_metrics(preds_list, targets_list, n_classes, ignore_index=-1)

Compute scalar and per-class metrics for each subject.

Parameters

preds_list, targets_list:

One entry per subject. preds has shape (n_epochs, n_classes) (logits or averaged votes); targets has shape (n_epochs,).

Returns

dict mapping a metric key to a list of per-subject values. Scalar metrics use their bare name ("accuracy"); per-class metrics use "{metric}/{class_name}" (e.g. "f1/N2").

Parameters:

• preds_list (Sequence[Tensor])

• targets_list (Sequence[Tensor])

• n_classes (int)

• ignore_index (int)

Return type:

Dict[str, List[float]]