eegproc.deep_learning.cross_validation.dataframe module

Run cross-validation directly from a tidy DataFrame.

The array-level entry points (loso_cv() and friends) stay the low-level API for callers who already hold tensors. This is the documented default: it takes the table featurization produces, derives the subject and trial arrays from columns, and maps the integer codes in the results back to the original identifiers so per-subject rows read "P07" rather than 0.

eegproc.deep_learning.cross_validation.dataframe.cross_validate_dataframe(frame, model_builder_function, *, strategy='loso', fs=None, kind='features', label_column='label', subject_columns=('subject',), trial_columns=('trial',), time_column=None, feature_columns=None, window_sec=None, window_samples=None, window_rows=1, overlap=0.0, normalize=None, label_transform=None, on_short_trial='error', return_arrays=False, **strategy_kwargs)[source]

Cross-validate a model over a tidy EEG table.

Parameters:

  • frame (EEGFrame | DataFrame) – A plain DataFrame is wrapped using the column-role keywords below.

  • model_builder_function (Callable[..., Any]) – Passed through unchanged; see loso_cv().

  • strategy (Literal['loso', 'fixed_loso', 'subject_calibration', 'nested_lnso'], default: 'loso') – Which cross-validation scheme to run.

  • kind (Literal['signal', 'features'], default: 'features') – "features" treats each row as one already-computed window, which is what feature_grouped_by_metadata() emits. "signal" windows raw samples and needs time_column and a window length.

  • **strategy_kwargs – Forwarded to the chosen entry point, validated against its signature so a typo raises instead of being silently ignored.

Return type:

dict

Returns:

dict – The chosen strategy’s results, with subject codes mapped back to the original identifiers and a subject_lookup entry added.

Examples

>>> feats = feature_grouped_by_metadata(
...     eeg_df, target_function=psd_bandpowers, fs=128,
...     group_by_metadata_columns=["subject", "trial"],
... )
>>> feats["label"] = ...
>>> results = cross_validate_dataframe(
...     feats, build_model, strategy="loso", fs=128,
... )
Parameters:

  • fs (float | None, default: None)

  • label_column (str, default: 'label')

  • subject_columns (tuple[str, ...], default: ('subject',))

  • trial_columns (tuple[str, ...], default: ('trial',))

  • time_column (str | None, default: None)

  • feature_columns (tuple[str, ...] | None, default: None)

  • window_sec (float | None, default: None)

  • window_samples (int | None, default: None)

  • window_rows (int, default: 1)

  • overlap (float, default: 0.0)

  • normalize (str | None, default: None)

  • label_transform (Optional[Callable], default: None)

  • on_short_trial (str, default: 'error')

  • return_arrays (bool, default: False)