CKC EEGMoCap Pipeline

This repository contains a processing pipeline combining EEG and motion capture (MoCap) data to analyze corticokinematic coherence (CKC) and related time-frequency metrics. The scripts were used in the publication:

Evaluating corticokinematic coherence using electroencephalography and human pose estimation
Emanuel Alexander Lorenz, Xiaomeng Su and Nina Skjæret-Maroni
Biomedical Physics & Engineering Express
DOI: 10.1088/2057-1976/ae27d5

It is designed to:

• Preprocess and segment synchronized EEG and MoCap dat
• Compute CKC per joint and condition
• Perform downstream statistical analyses

📁 Project Structure

ckc/
├── prepareData/                # MoCap preprocessing and data segmentation
│   ├── prepareData.m           # 1. Script: Preprocesses synchronized data
│   ├── epochData.m             # 2. Script: Epoch segmentation
│   ├── computeCMC.m            # Helper: CMC analysis
│   ├── getMarkerData.m         # Helper: Reads MoCap joint marker files
│   ├── processMarkerPair.m     # Helper: Calculates joint center based on two markers
│   └── computeAverageDistance.m# Helper: Computes average distance between two markers
│
├── convert_xdf_to_set/         # Python scripts for converting EEG recordings
│   ├── xdf_to_set_converter_all.py # 0. Script: Converts all XDFs into EEGLAB-compatible .set
│   └── new_xdf.py              # Modified utility loader for single XDFs
│
├── ckc_eeg/                    # EEG preprocessing and coherence computation
│   ├── eeglab_pipeline.m       # 3. Script: Preprocess EEG and calculate CKC
│   ├── clean_EEG_costume.m     # Helper: Statistics-based artifact removal
│   ├── CKC_EEG_function.m      # Helper: Main function computing CKC (and dPTE)
│   ├── PhaseTE_MF.m            # Helper: dPTE calculation (not validated!)
│   ├── calculateTopFrequencies.m # Helper: Detect F0 and F1 peaks for CKC
│   ├── pop_epoch_modified.m    # Helper: Modified EEGLAB epoching helper script
│   ├── cosine_filter.m         # Helper: High-pass filtering to prevent low-frequency artifacts
│   ├── eeg_laplac.m            # Helper: Compute surface Laplacian
│   ├── linear_mixing.m         # Helper: Mix movement and EEG signal for surrogate data
│   ├── phase_shuffle.m         # Helper: Shuffle the phase of the EEG signal for surrogate data
│   ├── subplot_tfpos_for_scalp.m # Helper: Plots topographic map
│   ├── surrogate_data.m        # Helper: Generates surrogate data
│   ├── add_noise.m             # Helper: Adds noise to surrogate data
│   └── bst_get.m               # Helper: Brainstorm structure helper function
│
├── statistics/                 # EEG preprocessing and coherence computation

🛠 Requirements

• MATLAB (tested with R2023a or later)
• EEGLAB (2024.2 or later)
• Python 3.8+ with pyxdf, mne, scipy (convert_xdf_to_set/)

🧭 Workflow Description

1. Experimental Setup and Recording

All required software and configuration files to run the EEGMoCap study, integrating EEG, video, motion capture, and VR streams via LabStreamingLayer (LSL), are available in this repo.

2. Extraction of joint position from video

For extracting joint center positions from synchronized video recordings using Mediapipe or similar HPE methods, use the tools in this repo.

3. Convert EEG Recordings to set

cd convert_xdf_to_set
python xdf_to_set_converter_all.py

Converts .xdf files to EEGLAB .set files.

4. Prepare MoCap Data

cd prepareData
epochData

• Iterates through all participants and sessions,
• Loads raw HPE and marker-based motion data,
• Epochs EEG data and aligns it with motion epochs,
• Computes joint center trajectories (e.g., elbow, wrist),
• Resamples, filters, and saves data for CKC analysis.

5. Segement data

cd ckc_eeg
epochData

Segments joint trajectories into epochs based on experimental markers (e.g., movement onsets, TTL triggers).

6. Preprocess EEG and Compute CKC

cd ckc_eeg
eeglab_pipeline

• Loads .set files,
• Applies filtering and ICA-based cleaning,
• Epochs EEG data and aligns it with motion epochs,
• Computes CKC values per joint and condition using CKC_EEG_function.m
• F0/F1 frequency extraction and surrogate-based significance testing.

7. Statistics

The statistics/ directory includes scripts for performing reliability assessment, group-level analysis, and visualization of CKC and movement metrics.

Main Scripts

• statistics.m / statistics_2.m: Perform group-level comparisons across modalities, joints, and conditions (those scripts are a bit chaotic and have not been cleaned up yet).

Agreement and Reliability

• bland_altman_analysis.m: Conduct Bland–Altman plots and compute bias/agreement limits between systems (e.g., HPE vs. MoCap).
• ICC.m: Computes intraclass correlation coefficient (e.g., ICC(3,1)) for within-subject reliability.

Visualization Utilities

• daboxplot.m: Custom boxplot function for group comparisons.
• examplary_movement.m: Displays representative joint trajectories or PCA components.
• polyfitZero.m: Fits constrained linear models (e.g., zero-intercept).
• mynum2str.m: Utility for formatted numeric output.

📌 Feedback

Please let me know if you have any suggestions. I would be happy to improve this repo further.

📄 License

This project is licensed under the MIT License. You are free to use, modify, and distribute this code, provided that the original copyright notice and permission notice are included in all copies or substantial portions of the software.