Standardized Synchronization and Validation Pipeline for Physiological Biomarkers Across Multiple Devices

Code for paper "Standardized Synchronization and Validation Pipeline for Physiological Biomarkers Across Multiple Devices" published in Behavior Research Methods.

Signal-processing and statistical-agreement pipeline for comparing physiological signals recorded simultaneously by two different wearable devices — the Empatica E4 wristband and the Empatica EmbracePlus — across four modalities: electrodermal activity (EDA), blood volume pulse (BVP), skin temperature (TEMP), and 3-axis acceleration (ACC).

The pipeline preprocesses each signal, temporally aligns the two devices (cross-correlation + Dynamic Time Warping, with a Discrete Wavelet Transform amplitude adjustment), extracts physiological features, and quantifies device agreement using the Concordance Correlation Coefficient (CCC), Bland–Altman analysis, mutual information (MI / NMI), magnitude-squared coherence, phase-locking value (PLV), and KL divergence.

@article{acan2026standardized,
  title={Standardized synchronization and validation pipeline for physiological biomarkers across multiple devices},
  author={Acan, Selin and Valenzuela-Pascual, Cl{\`a}udia and Corponi, Filippo and Li, Bryan M and Hidalgo-Mazzei, Diego and Thijssen, Dick and Vos, Gideon and Bogaerts, Stefan and Hermans, Erno and Baratchi, Mitra and others},
  journal={Behavior Research Methods},
  volume={58},
  number={8},
  pages={239},
  year={2026}
}

Installation

This project uses uv for environment and dependency management.

1. Install uv (see the official guide):

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. From the repository root, create the environment and install all dependencies:

   uv sync

   uv automatically provisions Python 3.12 (pinned in .python-version), creates a virtual environment in .venv/, and installs the exact, locked dependency set from uv.lock.

Run any script through uv run, which executes inside the managed environment without needing to activate it manually:

uv run python <script>.py [arguments]

The formatting/notebook tools (black, isort, jupyter) live in an optional dev dependency group; run uv sync --no-dev to skip them.

Data

Place wearable recordings under a data/ folder at the repository root with the following structure:

data/
├── report_<DDMMYYYY>.xlsx                       # reference sheet (participant ⇄ session map)
├── E4/
│   └── <E4_SESSION_CODE>.zip                     # raw Empatica E4 export (one .zip per session)
├── EmbracePlus/
│   └── EmbracePlus_sessions_12_2023to10_2024/    # exact folder name expected by the code
│       └── <YYYY-MM-DD>/                         # recording date
│           └── <SESSION_ID>-.../
│               └── raw_data/
│                   └── v6/
│                       └── *.avro                # raw EmbracePlus AVRO files
└── Aligned/                                      # created by step 2 of the pipeline
    └── participantNN.pkl

• Reference sheet (report_<DDMMYYYY>.xlsx) — one row per recording, mapping each participant to their paired E4 and EmbracePlus sessions. The code reads at least the columns participant ID, E4 session code, EmbracePlus session ID, the recording date, and hour.
• E4 export (E4/<session>.zip) — the standard Empatica E4 archive containing EDA.csv, BVP.csv, TEMP.csv, ACC.csv, IBI.csv, HR.csv, and tags.csv. In each CSV the first row is the start time (Unix timestamp), the second row is the sampling rate (Hz), and the remaining rows are the samples.
• EmbracePlus export — the raw AVRO files under .../<date>/<session_id>-.../raw_data/v6/, as delivered by Empatica Care.

Usage

All commands are run from the repository root via uv run.

1. Preprocess & align a single session

Filters, detrends, resamples, and aligns (DTW + DWT) the E4 and EmbracePlus signals for one E4 session, then writes per-modality alignment plots and correlation results.

uv run python preprocessing/preprocessing_main.py \
  --reference-sheet data/report_<DDMMYYYY>.xlsx \
  --zip-file        data/E4/<E4_SESSION_CODE>.zip \
  --save-path       runs/<E4_SESSION_CODE>

Outputs are written under --save-path into eda/, temperature/, bvp/, and acc/{x,y,z}/ subfolders (alignment figures plus a corr_results.txt per modality).

2. Build aligned per-participant data

Iterates over every participant in the reference sheet, reads each paired E4 + EmbracePlus recording, runs the multivariate analysis, and saves one participantNN.pkl per participant into data/Aligned/ (figures go to --plot_dir).

uv run python exploratory_data_analysis/exploratory_analysis_main.py \
  --data_dir data \
  --plot_dir images

Notes

• For this step the reference sheet must be named report_14042025.xlsx and placed in --data_dir (the filename is currently hard-coded in the script).
• The --data_dir / --plot_dir defaults (../data, ../images) assume the script is launched from inside its own folder, so pass them explicitly when running from the repository root, as shown above.
• --participant_id is accepted but currently unused — the script always processes every participant in the sheet.

3. Extract features & agreement metrics

Point this at the folder of aligned participant files from step 2. For each participant it extracts EDA / BVP / TEMP / ACC features and computes the agreement metrics (CCC, Bland–Altman, MI / NMI, coherence, PLV, …), writing an outputs_raw.pkl and figures per participant.

uv run python feature_extraction_correlation/feature_extraction_and_analysis_main.py data/Aligned

4. Aggregate results across participants

Summarises every participant's metrics into mean ± std tables and heatmaps.

uv run python feature_extraction_correlation/get_averaged_results.py