ffrprep.group.compute_subject_metrics

ffrprep.group.compute_subject_metrics(evoked_paths, epochs_paths=None, response_window=(0.1, 0.2), by_type_paths=None, harmonics=None, stimulus=None, n_trials_presented=None)[source]

Compute per-subject scalar FFR metrics from saved derivatives.

Recomputes the same scalar metrics ffrprep.reports shows in the participant-level report (RMS SNR, band power) directly from each subject’s saved combined Evoked, plus trial-to-trial response consistency from the saved preprocessing Epochs when available. Nothing here is computed from raw data; this only aggregates already-computed participant-level derivatives.

Optionally (harmonics / stimulus) it also derives spectral and stimulus-following measures from the sum of the two per-trial-type (polarity) averages, the response commonly analyzed in FFR studies.

Parameters:

  • evoked_paths (dict[str, pathlib.Path]) – Mapping of subject label to combined Evoked .fif path.

  • epochs_paths (dict[str, list of pathlib.Path], optional) – Mapping of subject label to that subject’s preprocessing Epochs .fif path(s) for the same (task, session, run). When a subject has multiple (per-trial-type) epochs files, response consistency is averaged across them.

  • response_window (tuple of (float, float)) – Response window for RMS SNR / band power, matching the participant-level --response-window default.

  • by_type_paths (dict[str, dict[str, pathlib.Path]], optional) – {subject: {condition_label: per-type Evoked path}}. Required for the polarity-sum measures; a subject needs exactly two conditions, otherwise those columns are NaN.

  • harmonics (dict, optional) – Keyword arguments for ffrprep.analysis.harmonic_amplitudes() (f0, n_harmonics, bin_hz, tmin, tmax). Adds rms_snr_polarity_sum, f0_uv and upper_harmonics_uv.

  • stimulus (dict, optional) – {"path": wav, "stim_window": (t0, t1), "resp_window": (t0, t1)} plus optionally "lag_range_ms": (lo, hi) and "lag_resp_window": (t0, t1). Adds stim2resp_r, stim2resp_z, stim2resp_lag_ms (and stim2resp_lim_* when a lag range is given). The stimulus is resampled to the EEG rate.

  • n_trials_presented (int, optional) – Trials presented per recording; when given, usable_pct = 100 * kept trials / presented is added.

Returns:

metrics – One row per subject with columns subject, n_avg, rms_snr, band_power_90_110hz, response_consistency and the optional columns described above.

Return type:

pandas.DataFrame