Metadata-Version: 2.4
Name: autocleaneeg-sl
Version: 0.1.0
Summary: Statistical Learning analysis for EEG - Z-scored Inter-Trial Coherence (ZITC) computation
Project-URL: Homepage, https://github.com/cincibrainlab/autocleaneeg-sl
Project-URL: Repository, https://github.com/cincibrainlab/autocleaneeg-sl
Author: Cincinnati Brain Lab
License-Expression: MIT
License-File: LICENSE
Keywords: eeg,inter-trial-coherence,itc,neuroscience,signal-processing,statistical-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Requires-Dist: mne>=1.0
Requires-Dist: numpy>=1.20
Requires-Dist: pandas>=1.3
Provides-Extra: dev
Requires-Dist: eeglabio>=0.0.2; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install autocleaneeg-sl
```

## Quick Start

### Command Line

```bash
# 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

```python
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

```python
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
