scientific-skills/neurokit2/references/emg.md
Electromyography (EMG) measures electrical activity produced by skeletal muscles during contraction. EMG analysis in NeuroKit2 focuses on amplitude estimation, muscle activation detection, and temporal dynamics for psychophysiology and motor control research.
Automated EMG signal processing pipeline.
signals, info = nk.emg_process(emg_signal, sampling_rate=1000)
Pipeline steps:
Returns:
signals: DataFrame with:
EMG_Clean: Filtered EMG signalEMG_Amplitude: Linear envelope (smoothed rectified signal)EMG_Activity: Binary activation indicator (0/1)EMG_Onsets: Activation onset markersEMG_Offsets: Activation offset markersinfo: Dictionary with activation parametersTypical workflow:
Apply filtering to remove noise and prepare for amplitude extraction.
cleaned_emg = nk.emg_clean(emg_signal, sampling_rate=1000)
Filtering approach (BioSPPy method):
Rationale:
EMG signal characteristics:
Compute linear envelope representing muscle contraction intensity.
amplitude = nk.emg_amplitude(cleaned_emg, sampling_rate=1000)
Method:
Linear envelope:
Typical smoothing:
Detect periods of muscle activation (onsets and offsets).
activity, info = nk.emg_activation(emg_amplitude, sampling_rate=1000, method='threshold',
threshold='auto', duration_min=0.05)
Methods:
1. Threshold-based (default):
activity = nk.emg_activation(amplitude, method='threshold', threshold='auto')
threshold='auto': Automatic based on signal statistics (e.g., mean + 1 SD)threshold=0.1: Manual absolute threshold2. Gaussian Mixture Model (GMM):
activity = nk.emg_activation(amplitude, method='mixture', n_clusters=2)
3. Changepoint detection:
activity = nk.emg_activation(amplitude, method='changepoint')
4. Bimodality (Silva et al., 2013):
activity = nk.emg_activation(amplitude, method='bimodal')
Key parameters:
duration_min: Minimum activation duration (seconds)
threshold: Activation threshold (method-dependent)Returns:
activity: Binary array (0 = rest, 1 = active)info: Dictionary with onset/offset indicesActivation metrics:
Automatically select event-related or interval-related analysis.
analysis = nk.emg_analyze(signals, sampling_rate=1000)
Mode selection:
Analyze EMG responses to discrete events/stimuli.
results = nk.emg_eventrelated(epochs)
Computed metrics (per epoch):
EMG_Activation: Presence of activation (binary)EMG_Amplitude_Mean: Average amplitude during epochEMG_Amplitude_Max: Peak amplitudeEMG_Bursts: Number of activation burstsEMG_Onset_Latency: Time from event to first activation (if applicable)Use cases:
Analyze extended EMG recordings.
results = nk.emg_intervalrelated(signals, sampling_rate=1000)
Computed metrics:
EMG_Bursts_N: Total number of activation burstsEMG_Amplitude_Mean: Mean amplitude across entire intervalEMG_Activation_Duration: Total time in active stateEMG_Rest_Duration: Total time in rest stateUse cases:
Generate synthetic EMG signals for testing.
synthetic_emg = nk.emg_simulate(duration=10, sampling_rate=1000, burst_number=3,
noise=0.1, random_state=42)
Parameters:
burst_number: Number of activation bursts to includenoise: Background noise levelrandom_state: Reproducibility seedGenerated features:
Use cases:
Visualize processed EMG signal.
nk.emg_plot(signals, info, static=True)
Displays:
Interactive mode: Set static=False for Plotly visualization
Surface EMG (most common):
Muscle-specific guidelines:
Common muscles in psychophysiology:
ECG contamination:
Motion artifacts:
Electrode issues:
Cross-talk:
Standard workflow:
# 1. Clean signal (high-pass filter, detrend)
cleaned = nk.emg_clean(emg_raw, sampling_rate=1000)
# 2. Extract amplitude envelope
amplitude = nk.emg_amplitude(cleaned, sampling_rate=1000)
# 3. Detect activation periods
activity, info = nk.emg_activation(amplitude, sampling_rate=1000,
method='threshold', threshold='auto')
# 4. Comprehensive processing (alternative)
signals, info = nk.emg_process(emg_raw, sampling_rate=1000)
# 5. Analyze
analysis = nk.emg_analyze(signals, sampling_rate=1000)
Normalization:
# Maximum voluntary contraction (MVC) normalization
mvc_amplitude = np.max(mvc_emg_amplitude) # From separate MVC trial
normalized_emg = (amplitude / mvc_amplitude) * 100 # Express as % MVC
# Common in ergonomics, exercise physiology
# Allows comparison across individuals and sessions
Psychophysiology:
Motor control and rehabilitation:
Ergonomics and occupational health:
Sports science:
Biofeedback:
Sleep medicine:
Frequency domain:
Motor unit identification:
Muscle coordination:
Amplitude (linear envelope):
Activation threshold:
Burst characteristics: