TEPpy

TMS-EEG Evoked Potential Analysis Framework
Explore the docs »

 

About The Project

TEPpy is a Python package for analyzing Transcranial Magnetic Stimulation combined with Electroencephalography (TMS-EEG) data. It provides tools for characterizing TMS-EEG evoked potential (TEP) temporal and spectral features, with automated peak detection and time-frequency analysis methods.

Key Features

• Convert MNE-Python Epochs objects to TEP objects
• Automatic detection of TEP peaks
• Automatic selection of most reponsive channels
• Time-frequency analysis using Stockwell transform
• Extraction of temporal and spectral features
• Visualization of temporal and spectral features
• Customizable analysis parameters for research flexibility

Analysis Workflow

Typical TEPpy analysis workflow from MNE Epochs to extracted features

Getting Started

Dependencies

• numpy>=2.0.1
• scipy>=1.14.0
• mne>=1.9.0
• matplotlib>=3.9.1
• stockwell>=1.2

Installation

Install from PyPI:

pip install teppy

Core Concepts

TEP Class

Converts MNE Epochs objects into analyzable TEP data structures:

• Performs automatic peak detection (P1, P2, P3)
• Extracts amplitude, latency, and peak-to-peak features
• Provides channel selection methods

TEP(epochs, exclude_channels=None, p1_range=[0.01, 0.04], low_limit=35, sign_corr='convexity')

Key methods:

compute_timefreq(): Perform time-frequency analysis

get_ntop_ch(): Get top channel names

plot_summary(): Generate summary plot

Feature accessors: get_amplitudes(), get_latencies(), etc.

TimeFreq Class

Stores and analyzes time-frequency decomposition results:

• Computes power and inter-trial coherence
• Estimates natural frequency
• Provides visualization tools

Key methods:

plot_natfreq1(): Comprehensive natural frequency visualization

plot_natfreq2(): Compact visualization

get_natfreq(): Compute natural frequency

Data accessors: get_power(), get_itc(), get_complex()

Usage

1. Loading Data

import mne
from teppy import TEP

# Load EEG epochs
epochs = mne.read_epochs('your_data.fif', verbose=False)

# Define channels to exclude
exclude_channels = ['Fp1', 'Fpz', 'Fp2', 'F7', 'F8', 'FT7', 'FT8', 'T7',
                    'T8', 'TP7', 'TP8', 'TP9', 'TP10', 'P7', 'P8', 'Iz']

2. Creating TEP Object

tep = TEP(
    epochs,
    exclude_channels=exclude_channels,
    p1_range=[0.01, 0.04],  # P1 detection window (s)
    low_limit=35,            # Minimum peak separation (Hz)
    sign_corr='convexity'    # Signal correction method
)

3. Extracting Features

# Get top 4 channels
top_channels = tep.get_ntop_ch(ntop=4)

# Get comprehensive feature summary
feature_summary = tep.info_ntop(ntop=4)

4. Generating Summary Plot

fig = tep.plot_summary(
    ntop=4,
    tlim=(-0.1, 0.3),      # Time limits (s) of the plot
    cmap_topo='Reds',    # Topomap colormap
)
fig.savefig('tep_summary.png', dpi=300)

5. Time-Frequency Analysis

# Compute time-frequency decomposition
timefreq = tep.compute_timefreq(
    ntop=4,                 # Use top 4 channels
    method='stock1',        # MNE's Stockwell implementation
    fmin=4, fmax=45,        # Frequency range
    baseline_correction=True,
    baseline_range=(-0.5, -0.1)
)

# Plot natural frequency map
fig = timefreq.plot_natfreq1(
    natfreq_window=[0.02, 0.15],  # Natural frequency window
    plot_tlim=(-0.1, 0.3), # Time limits (s) of the plot
    plot_ms=True, # plot the time axis in ms
    cmap='RdBu_r'
)
fig.savefig('timefreq_analysis.png', dpi=300)

Advanced Features

Custom Channel Selection

# Select specific channels
timefreq_custom = tep.compute_timefreq(
    pick_ch=['Cz', 'Pz', 'Fz'],  # Custom channel selection
    method='stock2',              # Alternative Stockwell implementation
    gamma=1.5,                    # Gamma parameter for stock2
    return_complex=True            # Return complex coefficients
)

Batch Processing

results = []
subjects = ['sub-01', 'sub-02', 'sub-03']

for subject in subjects:
    epochs = mne.read_epochs(f'{subject}_epo.fif')
    tep = TEP(epochs, exclude_channels=exclude_channels)
    tf = tep.compute_timefreq(ntop=4)
    
    results.append({
        'subject': subject,
        'nat_freq': tf.get_natfreq(natfreq_window=[0.02, 0.15]),
        'top_channels': tep.get_ntop_ch(ntop=4),
        'p1p2_amplitude': tep.get_peaktopeak(ntop=4).mean(0)[0] # [0]: Get P1-P2 amplitude 
    })

Accessing Underlying Data

# Get raw power data
power_data = timefreq.get_power(average_channels=True)

# Get complex coefficients
complex_data = timefreq.get_complex()

# Get evoked spectrum
evoked_spectrum = timefreq.get_evoked_spectrum(
    sum_window=[0.02, 0.12]
)

Citation

Contact

Contributing

Contributions are welcome! Please fork the repository and submit pull requests. Report issues on the GitHub issue tracker.

License