autocleaneeg-sl 0.2.0

Statistical Learning analysis for EEG - Z-scored Inter-Trial Coherence (ZITC) computation

autocleaneeg-sl

Statistical Learning analysis for EEG data - computes Z-scored Inter-Trial Coherence (ZITC).

ZITC measures neural entrainment to rhythmic stimuli by comparing phase-locking values against a surrogate distribution, providing a statistically meaningful metric that accounts for baseline phase consistency.

Installation

pip install autocleaneeg-sl

Quick Start

Command Line

# Process a single file
autocleaneeg-sl subject01_epochs.set

# Extract specific target frequencies (e.g., word rate and syllable rate)
autocleaneeg-sl subject01_epochs.set --target-freqs 1.111 3.333

# Process multiple files with custom parameters
autocleaneeg-sl *.set --surrogates 200 --freq-min 0.5 --freq-max 5.0 --output-dir ./results/

Python API

from autocleaneeg_sl import compute_zitc

# Basic usage
result = compute_zitc("subject01_epochs.set")

# Get ZITC at specific frequency
word_zitc = result.get_zitc_at_freq(1.111)
print(f"Word rate ZITC: {word_zitc['zitc']:.3f}")

# Export to DataFrame
df = result.to_dataframe()
df.to_csv("subject01_zitc.csv", index=False)

Parameters

result = compute_zitc(
    epochs,                          # Path to .set file or MNE Epochs object
    freq_range=(0.2, 10.0),         # Frequency range in Hz
    n_surrogates=100,                # Number of surrogate iterations
    channels=None,                   # Channel selection (None = all)
    random_seed=42,                  # For reproducibility
    verbose=True,                    # Print progress
)

Method

ZITC is computed as:

ZITC = (True PLV - Surrogate Mean) / Surrogate Std

Where:

• True PLV: Phase-locking value computed from the actual data
• Surrogate Mean/Std: Statistics from null distribution generated by circular time-shifting each epoch

This z-scoring normalizes the raw PLV against chance-level phase consistency, allowing comparison across subjects and frequencies.

Output

The ZITCResult object contains:

• frequencies: Array of frequency bins (Hz)
• raw_itc: Raw PLV values (n_channels x n_freqs)
• zitc: Z-scored ITC values (n_channels x n_freqs)
• surrogate_mean, surrogate_std: Null distribution statistics
• channel_names: List of channel names
• sfreq: Sampling frequency
• n_epochs: Number of epochs
• n_surrogates: Number of surrogates used

Requirements

• Python >= 3.9
• NumPy >= 1.20
• MNE-Python >= 1.0
• Pandas >= 1.3

License

MIT