OSCR

A reproducible EEG hyperscanning dataset for triadic social decision-making during an iterated 3-player Prisoner's Dilemma.

Code ↔ Paper

6 matches between paragraphs of the paper and lines of its authors' code, computed by the harvester (lexical-v1). Click a colored paragraph or line to see its counterpart.

The 6 matches
  1. [1] § Experimental Design, Materials and Methods › Technical validation › Inter brain synchrony ↔ pd_eeg_analysis/ibs_analysis.py, lines 1–57 · score 0.94 · Inter brain synchrony, 14–25 Hz, 30–45 Hz, 8–12 Hz, 0–2000 ms, 4–7 Hz
  2. [2] § Experimental Design, Materials and Methods › Technical validation › Preprocessing ↔ pd_eeg_analysis/preprocess.py, lines 1–52 · score 0.91 · 1–100 Hz, ICLabel, eye blink, preprocessing pipeline, Task EEG, notch
  3. [3] § Experimental Design, Materials and Methods › Technical validation › Inter brain synchrony ↔ pd_eeg_analysis/ibs_analysis.py, lines 1–57 · score 0.83 · window matched, S1 S2, S1 S3, S2 S3, overlapping, onset
  4. [4] § Experimental Design, Materials and Methods › Technical validation › Preprocessing ↔ pd_eeg_analysis/ibs_analysis.py, lines 200–233 · score 0.61 · 1–45 Hz, resting IBS, cross, overlapping, filtering, window
  5. [5] § Experimental Design, Materials and Methods › Behavioral validation: computation of behavioral indices ↔ pd_eeg_analysis/ibs_analysis.py, lines 89–91 · score 0.59 · S1 S2, S1 S3, S2 S3
  6. [6] § Experimental Design, Materials and Methods › Technical validation › Behavioral validation: computation of behavioral indices ↔ pd_eeg_analysis/ibs_analysis.py, lines 89–91 · score 0.59 · S1 S2, S1 S3, S2 S3

Paper

Loaded from Europe PMC by your browser, not stored by OSCR: doi.org · Europe PMC

The paper is loaded when this pane is shown.

The authors' code

Python · 531 lines · 24 KB · no license · 5 matches

  1. """
  2. ibs_analysis.py
  3. ===============
  4. Inter-Brain Synchrony (IBS) analysis for three-person hyperscanning EEG.
  6. Requires cleaned_eeg.pkl produced by preprocess.py.
  8. Analysis
  9. --------
  10. - Metrics : PLV, Coherence (ccorr) via HyPyP
  11. - Windows : 0–1000 ms, 0–2000 ms post-stimulus onset
  12. - Tasks : decision, feedback
  13. - Pairs : all 3 dyads within each trio (S1-S2, S1-S3, S2-S3)
  14. - Condition: Cooperative (both chose cooperate) vs. Other
  15. - Resting : non-overlapping windows matched to task window length (baseline)
  16. - Stats : cluster-permutation test (HyPyP, 2000 permutations, two-tailed)
  18. Frequency bands
  19. ---------------
  20. delta 1–3 Hz
  21. theta 4–7 Hz
  22. alpha 8–12 Hz
  23. beta 14–25 Hz
  24. gamma 30–45 Hz
  26. Output
  27. ------
  28. results/
  29. ibs_data.pkl IBS arrays per task / window / metric / condition
  30. cluster_stats.pkl Cluster-permutation results (min_p, n_sig, F_obs)
  31. stats_ibs_by_band.csv Per-band summary (mean ± SEM, Cohen's d, cluster p)
  32. fig_ibs_plv.png Bar figure — PLV
  33. fig_ibs_coh.png Bar figure — Coherence
  35. Usage
  36. -----
  37. python ibs_analysis.py
  38. python ibs_analysis.py --cache results/cleaned_eeg.pkl --output_dir results
  39. """
  41. import os
  42. import argparse
  43. import pickle
  44. import warnings
  46. import numpy as np
  47. import scipy.signal as sig
  48. import scipy.sparse as sparse
  49. import matplotlib
  50. matplotlib.use('Agg')
  51. import matplotlib.pyplot as plt
  52. import mne
  53. import hypyp.analyses as hana
  54. import hypyp.stats as hstats
  56. warnings.filterwarnings('ignore', category=RuntimeWarning)
  57. warnings.filterwarnings('ignore', category=UserWarning)
  59. # ── Default paths ──────────────────────────────────────────────────────────────
  60. BASE_DIR = os.path.dirname(os.path.abspath(__file__))
  61. _CACHE = os.path.abspath(os.path.join(BASE_DIR, '..', 'results', 'cleaned_eeg.pkl'))
  62. _OUTPUT_DIR = os.path.abspath(os.path.join(BASE_DIR, '..', 'results'))
  64. # ── Recording parameters ───────────────────────────────────────────────────────
  65. SRATE = 300
  66. GROUP_IDS = list(range(1, 12))
  67. N_SUBJ = 3
  68. N_CH = 19
  69. N_TRIALS = 40
  71. CH_NAMES = ['P3','C3','F3','Fz','F4','C4','P4','Cz','Pz',
  72. 'Fp1','Fp2','T3','T5','O1','O2','F7','F8','T6','T4']
  74. MONTAGE = mne.channels.make_standard_montage('standard_1020')
  76. # ── Frequency bands ────────────────────────────────────────────────────────────
  77. BANDS = {
  78. 'delta': ( 1, 3),
  79. 'theta': ( 4, 7),
  80. 'alpha': ( 8, 12),
  81. 'beta' : (14, 25),
  82. 'gamma': (30, 45),
  83. }
  84. BAND_NAMES = list(BANDS.keys())
  85. FREQS_MEAN = [2.0, 5.5, 10.0, 19.5, 37.5] # representative frequency per band
  86. N_BANDS = len(BANDS)
  87. N_FEAT = N_BANDS * N_CH # 95
  89. # ── Subject pairs within each trio ────────────────────────────────────────────
  90. PAIRS = [(0, 1), (0, 2), (1, 2)]
  91. PAIR_LABELS = ['S1-S2', 'S1-S3', 'S2-S3']
  93. # ── Analysis windows (ms relative to stimulus onset at 0 ms) ──────────────────
  94. WIN_ONSET_SMP = int(1000 * SRATE / 1000) # pre-stimulus = 1000 ms = 300 samples
  95. WINDOWS = [(0, 1000), (0, 2000)]
  96. WIN_LABELS = ['0-1000 ms', '0-2000 ms']
  98. # ── Resting state ──────────────────────────────────────────────────────────────
  99. REST_N_RUNS = 3
  101. # ── Statistics ─────────────────────────────────────────────────────────────────
  102. N_PERMS = 2000
  104. # ── Figure colors ──────────────────────────────────────────────────────────────
  105. COND_COLORS = {'coop': '#2166AC', 'other': '#D6604D'}
  108. # ══════════════════════════════════════════════════════════════════════════════
  109. # Utilities
  110. # ══════════════════════════════════════════════════════════════════════════════
  111. def ms_to_smp(ms):
  112. return int(ms * SRATE / 1000)
  115. def _sig_label(p):
  116. if p < 0.001: return '***'
  117. if p < 0.01: return '**'
  118. if p < 0.05: return '*'
  119. return 'n.s.'
  122. def _per_band_means(arr):
  123. """arr: (n, 95) → dict band → (mean, sem)"""
  124. out = {}
  125. for bi, band in enumerate(BAND_NAMES):
  126. chunk = arr[:, bi * N_CH:(bi + 1) * N_CH].mean(axis=1)
  127. out[band] = (chunk.mean(), chunk.std(ddof=1) / np.sqrt(len(chunk)))
  128. return out
  131. # ══════════════════════════════════════════════════════════════════════════════
  132. # HyPyP adjacency matrix (memoised per window length)
  133. # ══════════════════════════════════════════════════════════════════════════════
  134. _adj_cache = {}
  136. def get_adjacency(win_len_smp):
  137. if win_len_smp in _adj_cache:
  138. return _adj_cache[win_len_smp]
  139. info = mne.create_info(CH_NAMES, sfreq=SRATE, ch_types='eeg')
  140. info.set_montage(MONTAGE, on_missing='ignore')
  141. ep = mne.EpochsArray(np.zeros((5, N_CH, win_len_smp)), info, verbose=False)
  142. ch_con = hstats.con_matrix(ep, freqs_mean=FREQS_MEAN, draw=False)
  143. meta = hstats.metaconn_matrix_2brains(
  144. [(i, i) for i in range(N_CH)], ch_con.ch_con,
  145. freqs_mean=FREQS_MEAN, plot=False)
  146. adj = sparse.csr_matrix(meta.metaconn_freq)
  147. _adj_cache[win_len_smp] = adj
  148. return adj
  151. # ══════════════════════════════════════════════════════════════════════════════
  152. # IBS computation
  153. # ══════════════════════════════════════════════════════════════════════════════
  154. def _band_analytic(eeg_win, flo, fhi):
  155. """Bandpass + Hilbert for task epochs.
  157. Parameters
  158. ----------
  159. eeg_win : ndarray (n_ch, n_times, n_trials)
  161. Returns
  162. -------
  163. ndarray (n_trials, n_ch, 1, n_times) complex
  164. """
  165. sos = sig.butter(4, [flo, fhi], btype='bandpass', fs=SRATE, output='sos')
  166. filt = sig.sosfiltfilt(sos, eeg_win, axis=1)
  167. anal = sig.hilbert(filt, axis=1)
  168. return anal.transpose(2, 0, 1)[:, :, np.newaxis, :]
  171. def compute_task_ibs(eeg_a, eeg_b, win_start_smp, win_end_smp):
  172. """PLV and Coherence (ccorr) between two subjects across all task trials.
  174. Parameters
  175. ----------
  176. eeg_a, eeg_b : ndarray (n_ch, n_times, n_trials)
  177. win_start_smp : int start sample index within epoch
  178. win_end_smp : int end sample index within epoch
  180. Returns
  181. -------
  182. plv_mat, coh_mat : ndarray (n_trials, N_FEAT=95)
  183. """
  184. seg_a = eeg_a[:, win_start_smp:win_end_smp, :]
  185. seg_b = eeg_b[:, win_start_smp:win_end_smp, :]
  186. plv_bands, coh_bands = [], []
  187. for (flo, fhi) in BANDS.values():
  188. cs = np.stack([_band_analytic(seg_a, flo, fhi),
  189. _band_analytic(seg_b, flo, fhi)], axis=0)
  190. plv_f = hana.compute_sync(cs, mode='plv', epochs_average=False)
  191. coh_f = hana.compute_sync(cs, mode='ccorr', epochs_average=False)
  192. plv_ibs = plv_f[0, :, 0:N_CH, N_CH:2*N_CH]
  193. coh_ibs = coh_f[0, :, 0:N_CH, N_CH:2*N_CH]
  194. plv_bands.append(np.array([np.diag(plv_ibs[t]) for t in range(N_TRIALS)]))
  195. coh_bands.append(np.array([np.diag(np.real(coh_ibs[t])) for t in range(N_TRIALS)]))
  196. return (np.concatenate(plv_bands, axis=1),
  197. np.concatenate(coh_bands, axis=1))
  200. def compute_resting_ibs(rest_a, rest_b, win_len_smp):
  201. """PLV and Coherence for resting-state non-overlapping windows.
  203. Parameters
  204. ----------
  205. rest_a, rest_b : ndarray (n_ch, n_times) µV, 1–45 Hz filtered
  206. win_len_smp : int window length in samples
  208. Returns
  209. -------
  210. plv_mat, coh_mat : ndarray (n_windows, N_FEAT=95)
  211. """
  212. n_windows = rest_a.shape[1] // win_len_smp
  213. plv_bands, coh_bands = [], []
  214. for (flo, fhi) in BANDS.values():
  215. sos = sig.butter(4, [flo, fhi], btype='bandpass', fs=SRATE, output='sos')
  216. anal_a = sig.hilbert(sig.sosfiltfilt(sos, rest_a, axis=1), axis=1)
  217. anal_b = sig.hilbert(sig.sosfiltfilt(sos, rest_b, axis=1), axis=1)
  218. plv_wins, coh_wins = [], []
  219. for w in range(n_windows):
  220. sl = slice(w * win_len_smp, (w + 1) * win_len_smp)
  221. sa, sb = anal_a[:, sl], anal_b[:, sl]
  222. phi = np.angle(sa) - np.angle(sb)
  223. plv = np.abs(np.mean(np.exp(1j * phi), axis=1))
  224. cross = sa * np.conj(sb)
  225. coh = (np.abs(np.mean(cross, axis=1)) /
  226. (np.sqrt(np.mean(np.abs(sa)**2, axis=1) *
  227. np.mean(np.abs(sb)**2, axis=1)) + 1e-12))
  228. plv_wins.append(plv)
  229. coh_wins.append(coh)
  230. plv_bands.append(np.array(plv_wins))
  231. coh_bands.append(np.array(coh_wins))
  232. return (np.concatenate(plv_bands, axis=1),
  233. np.concatenate(coh_bands, axis=1))
  236. # ══════════════════════════════════════════════════════════════════════════════
  237. # Aggregate IBS across all groups
  238. # ══════════════════════════════════════════════════════════════════════════════
  239. def aggregate_ibs(cache):
  240. """Compute IBS for all tasks / windows / pairs and resting state.
  242. Returns
  243. -------
  244. results : dict
  245. results[task][(start_ms, end_ms)][metric]['coop'] → ndarray (n, 95)
  246. results[task][(start_ms, end_ms)][metric]['other'] → ndarray (n, 95)
  247. results['resting'][dur_ms][metric]['all'] → ndarray (n, 95)
  248. """
  249. tasks = {'decision': 'decision', 'feedback': 'feedback'}
  251. results = {}
  252. for task in tasks:
  253. results[task] = {}
  254. for win in WINDOWS:
  255. results[task][win] = {m: {'coop': [], 'other': []}
  256. for m in ('plv', 'coh')}
  258. rest_durations = sorted(set(end - start for start, end in WINDOWS))
  259. results['resting'] = {d: {m: {'all': []} for m in ('plv', 'coh')}
  260. for d in rest_durations}
  262. for g in GROUP_IDS:
  263. score = cache[g]['score'] # (40, 3) 1 = coop
  265. for task in tasks:
  266. cleaned = cache[g][task] # (57, n_times, 40)
  267. for (start_ms, end_ms) in WINDOWS:
  268. w_start = WIN_ONSET_SMP + ms_to_smp(start_ms)
  269. w_end = WIN_ONSET_SMP + ms_to_smp(end_ms)
  270. for sa, sb in PAIRS:
  271. mask = (score[:, sa] == 1) & (score[:, sb] == 1)
  272. ea = cleaned[sa * N_CH:(sa + 1) * N_CH]
  273. eb = cleaned[sb * N_CH:(sb + 1) * N_CH]
  274. plv_mat, coh_mat = compute_task_ibs(ea, eb, w_start, w_end)
  275. key = (start_ms, end_ms)
  276. results[task][key]['plv']['coop'].append(plv_mat[mask])
  277. results[task][key]['plv']['other'].append(plv_mat[~mask])
  278. results[task][key]['coh']['coop'].append(coh_mat[mask])
  279. results[task][key]['coh']['other'].append(coh_mat[~mask])
  281. for run_idx in range(REST_N_RUNS):
  282. rest = cache[g]['resting'][run_idx] # (57, 18000)
  283. for sa, sb in PAIRS:
  284. ra = rest[sa * N_CH:(sa + 1) * N_CH]
  285. rb = rest[sb * N_CH:(sb + 1) * N_CH]
  286. for dur_ms in rest_durations:
  287. plv_r, coh_r = compute_resting_ibs(ra, rb, ms_to_smp(dur_ms))
  288. results['resting'][dur_ms]['plv']['all'].append(plv_r)
  289. results['resting'][dur_ms]['coh']['all'].append(coh_r)
  291. print(f' G{g:02d} done.', flush=True)
  293. # Concatenate
  294. for task in tasks:
  295. for win in WINDOWS:
  296. for metric in ('plv', 'coh'):
  297. for cond in ('coop', 'other'):
  298. results[task][win][metric][cond] = np.concatenate(
  299. results[task][win][metric][cond], axis=0)
  300. for dur_ms in rest_durations:
  301. for metric in ('plv', 'coh'):
  302. results['resting'][dur_ms][metric]['all'] = np.concatenate(
  303. results['resting'][dur_ms][metric]['all'], axis=0)
  304. return results
  307. # ══════════════════════════════════════════════════════════════════════════════
  308. # Cluster-permutation test
  309. # ══════════════════════════════════════════════════════════════════════════════
  310. def run_cluster_test(coop, other, win_len_smp):
  311. adj = get_adjacency(win_len_smp)
  312. result = hstats.statscondCluster(
  313. data=[coop, other],
  314. freqs_mean=FREQS_MEAN,
  315. ch_con_freq=adj,
  316. tail=0,
  317. n_permutations=N_PERMS,
  318. alpha=0.05,
  319. )
  320. pvs = result.cluster_p_values
  321. min_p = min(pvs) if len(pvs) else 1.0
  322. n_sig = sum(p < 0.05 for p in pvs)
  323. return min_p, n_sig, result
  326. # ══════════════════════════════════════════════════════════════════════════════
  327. # Figures
  328. # ══════════════════════════════════════════════════════════════════════════════
  329. def plot_ibs_bars(results, cluster_stats, output_dir):
  330. metric_labels = {'plv': 'PLV', 'coh': 'Coherence (ccorr)'}
  331. tasks = [t for t in results if t != 'resting']
  333. for metric in ('plv', 'coh'):
  334. fig, axes = plt.subplots(len(tasks), len(WINDOWS),
  335. figsize=(5 * len(WINDOWS), 4.5 * len(tasks)),
  336. sharey='row')
  337. fig.suptitle(
  338. f'Inter-Brain Synchrony — {metric_labels[metric]}\n'
  339. f'Cooperative vs. Other (mean ± SEM, cluster permutation n={N_PERMS})',
  340. fontsize=12, fontweight='bold')
  342. x = np.arange(N_BANDS)
  343. w = 0.35
  344. band_caps = [b.capitalize() for b in BAND_NAMES]
  346. for ri, task in enumerate(tasks):
  347. for ci, (win, win_lbl) in enumerate(zip(WINDOWS, WIN_LABELS)):
  348. ax = axes[ri, ci]
  349. coop_bm = _per_band_means(results[task][win][metric]['coop'])
  350. other_bm = _per_band_means(results[task][win][metric]['other'])
  352. for bi, band in enumerate(BAND_NAMES):
  353. c_m, c_s = coop_bm[band]
  354. o_m, o_s = other_bm[band]
  355. ax.bar(x[bi] - w/2, c_m, w, color=COND_COLORS['coop'],
  356. yerr=c_s, capsize=3, error_kw=dict(elinewidth=1),
  357. label='Cooperative' if bi == 0 else '')
  358. ax.bar(x[bi] + w/2, o_m, w, color=COND_COLORS['other'],
  359. yerr=o_s, capsize=3, error_kw=dict(elinewidth=1),
  360. label='Other' if bi == 0 else '')
  362. min_p, n_sig = cluster_stats[task][metric][win]['min_p'], \
  363. cluster_stats[task][metric][win]['n_sig']
  364. slbl = _sig_label(min_p)
  365. if min_p < 0.001:
  366. p_str = f'cluster p < 0.001 {slbl}'
  367. elif min_p < 0.01:
  368. p_str = f'cluster p < 0.01 {slbl}'
  369. elif min_p < 0.05:
  370. p_str = f'cluster p = {min_p:.3f} {slbl}'
  371. else:
  372. p_str = f'cluster p = {min_p:.3f} n.s.'
  373. color_sig = 'red' if min_p < 0.05 else 'dimgray'
  374. ax.text(0.98, 0.97, p_str, transform=ax.transAxes,
  375. ha='right', va='top', fontsize=9, color=color_sig,
  376. bbox=dict(boxstyle='round,pad=0.3',
  377. facecolor='white', edgecolor=color_sig, alpha=0.85))
  379. ax.set_xticks(x)
  380. ax.set_xticklabels(band_caps, fontsize=10)
  381. ax.set_title(f'{task.capitalize()} [{win_lbl}]', fontsize=11)
  382. ax.set_ylabel(metric_labels[metric], fontsize=10)
  383. ax.spines['top'].set_visible(False)
  384. ax.spines['right'].set_visible(False)
  385. if ri == 0 and ci == 0:
  386. ax.legend(fontsize=8, loc='upper left')
  388. plt.tight_layout()
  389. path = os.path.join(output_dir, f'fig_ibs_{metric}.png')
  390. plt.savefig(path, dpi=200, bbox_inches='tight')
  391. plt.close()
  392. print(f' Saved: {os.path.basename(path)}')
  395. def plot_fstat(cluster_stats, output_dir):
  396. for task in ('decision', 'feedback'):
  397. for metric in ('plv', 'coh'):
  398. sig_wins = [(win, cluster_stats[task][metric][win])
  399. for win in WINDOWS
  400. if cluster_stats[task][metric][win]['n_sig'] > 0]
  401. if not sig_wins:
  402. continue
  403. n = len(sig_wins)
  404. fig, axes = plt.subplots(1, n, figsize=(6 * n, 4.5))
  405. if n == 1:
  406. axes = [axes]
  407. fig.suptitle(f'Cluster F-statistic — {task.capitalize()} {metric.upper()}',
  408. fontsize=12, fontweight='bold')
  409. for ax, (win, info) in zip(axes, sig_wins):
  410. F = info['F_obs'].reshape(N_BANDS, N_CH)
  411. lim = np.abs(F).max()
  412. im = ax.imshow(F, aspect='auto', cmap='RdBu_r',
  413. vmin=-lim, vmax=lim)
  414. ax.set_xticks(range(N_CH))
  415. ax.set_xticklabels(CH_NAMES, rotation=90, fontsize=7)
  416. ax.set_yticks(range(N_BANDS))
  417. ax.set_yticklabels([b.capitalize() for b in BAND_NAMES], fontsize=9)
  418. min_p = info['min_p']
  419. p_str = '< 0.001' if min_p < 0.001 else f'= {min_p:.3f}'
  420. ax.set_title(f'[{win[0]}-{win[1]} ms] p {p_str}', fontsize=10)
  421. plt.colorbar(im, ax=ax, fraction=0.046, label='F-statistic')
  422. plt.tight_layout()
  423. path = os.path.join(output_dir, f'fig_fstat_{task}_{metric}.png')
  424. plt.savefig(path, dpi=200, bbox_inches='tight')
  425. plt.close()
  426. print(f' Saved: {os.path.basename(path)}')
  429. # ══════════════════════════════════════════════════════════════════════════════
  430. # CSV export
  431. # ══════════════════════════════════════════════════════════════════════════════
  432. def export_csv(results, cluster_stats, output_dir):
  433. import csv
  435. rows = []
  436. for task in ('decision', 'feedback'):
  437. for win in WINDOWS:
  438. win_lbl = f'{win[0]}-{win[1]}ms'
  439. for metric in ('plv', 'coh'):
  440. info = cluster_stats[task][metric][win]
  441. coop_bm = _per_band_means(results[task][win][metric]['coop'])
  442. other_bm = _per_band_means(results[task][win][metric]['other'])
  443. for bi, band in enumerate(BAND_NAMES):
  444. c_m, c_s = coop_bm[band]
  445. o_m, o_s = other_bm[band]
  446. diff = c_m - o_m
  447. nc = results[task][win][metric]['coop'].shape[0]
  448. no = results[task][win][metric]['other'].shape[0]
  449. ca = results[task][win][metric]['coop'][:, bi*N_CH:(bi+1)*N_CH].mean(axis=1)
  450. oa = results[task][win][metric]['other'][:, bi*N_CH:(bi+1)*N_CH].mean(axis=1)
  451. pool = np.sqrt(((nc-1)*ca.std(ddof=1)**2 + (no-1)*oa.std(ddof=1)**2) / (nc+no-2))
  452. rows.append({
  453. 'task': task, 'window': win_lbl, 'metric': metric, 'band': band,
  454. 'coop_mean': f'{c_m:.6f}', 'coop_sem': f'{c_s:.6f}',
  455. 'other_mean': f'{o_m:.6f}', 'other_sem': f'{o_s:.6f}',
  456. 'diff': f'{diff:.6f}',
  457. 'cohens_d': f'{diff / (pool + 1e-12):.4f}',
  458. 'cluster_p': f'{info["min_p"]:.4f}',
  459. 'n_sig_clusters': info['n_sig'],
  460. 'sig': _sig_label(info['min_p']),
  461. })
  463. path = os.path.join(output_dir, 'stats_ibs_by_band.csv')
  464. with open(path, 'w', newline='') as f:
  465. w = csv.DictWriter(f, fieldnames=rows[0].keys())
  466. w.writeheader(); w.writerows(rows)
  467. print(f' Saved: {os.path.basename(path)}')
  470. # ══════════════════════════════════════════════════════════════════════════════
  471. # CLI
  472. # ══════════════════════════════════════════════════════════════════════════════
  473. def parse_args():
  474. p = argparse.ArgumentParser(description='Hyperscanning IBS analysis')
  475. p.add_argument('--cache', default=_CACHE,
  476. help='Path to cleaned_eeg.pkl from preprocess.py')
  477. p.add_argument('--output_dir', default=_OUTPUT_DIR,
  478. help='Directory to write figures and CSVs')
  479. return p.parse_args()
  482. def main():
  483. args = parse_args()
  484. os.makedirs(args.output_dir, exist_ok=True)
  486. print('=== IBS Analysis ===')
  487. print(f' cache : {args.cache}')
  488. print(f' output_dir : {args.output_dir}')
  490. print('\n[1/4] Loading preprocessed cache...')
  491. with open(args.cache, 'rb') as f:
  492. cache = pickle.load(f)
  494. print('\n[2/4] Computing IBS (PLV + Coherence)...')
  495. results = aggregate_ibs(cache)
  496. with open(os.path.join(args.output_dir, 'ibs_data.pkl'), 'wb') as f:
  497. pickle.dump(results, f)
  499. print('\n[3/4] Cluster-permutation tests...')
  500. cluster_stats = {}
  501. for task in ('decision', 'feedback'):
  502. cluster_stats[task] = {'plv': {}, 'coh': {}}
  503. for (start_ms, end_ms) in WINDOWS:
  504. win = (start_ms, end_ms)
  505. win_smp = ms_to_smp(end_ms - start_ms)
  506. for metric in ('plv', 'coh'):
  507. coop = results[task][win][metric]['coop']
  508. other = results[task][win][metric]['other']
  509. print(f' {task} [{start_ms}-{end_ms}ms] {metric.upper()}'
  510. f' coop n={coop.shape[0]}, other n={other.shape[0]}',
  511. flush=True)
  512. min_p, n_sig, result = run_cluster_test(coop, other, win_smp)
  513. print(f' min_p = {min_p:.4f} n_sig = {n_sig} {_sig_label(min_p)}')
  514. cluster_stats[task][metric][win] = {
  515. 'min_p': min_p, 'n_sig': n_sig,
  516. 'F_obs': result.F_obs_plot,
  517. }
  519. with open(os.path.join(args.output_dir, 'cluster_stats.pkl'), 'wb') as f:
  520. pickle.dump(cluster_stats, f)
  522. print('\n[4/4] Figures and CSV...')
  523. plot_ibs_bars(results, cluster_stats, args.output_dir)
  524. plot_fstat(cluster_stats, args.output_dir)
  525. export_csv(results, cluster_stats, args.output_dir)
  527. print('\nDone.')
  530. if __name__ == '__main__':
  531. main()

ibs_analysis.py at commit 0862853, no license · at the source

Overview

Authors: H Kim1, SC Jun1, CS Nam2
ORCID iDs: SC Jun, CS Nam
  1. Department of AI Convergence, Gwangju Institute of Science and Technology, Gwangju, 61005, South Korea
  2. Center of Excellence in Product Design and Advanced Manufacturing, North Carolina A&T State University, Greensboro, NC, 27411, USA
Institutions: Gwangju Institute of Science and Technology (South Korea); North Carolina Agricultural and Technical State University (United States)
Journal: Data in brief, volume 68, article 113064
Dates: received 22 May 2026; accepted 3 July 2026; published online 10 July 2026
Type: Data paper · Language: English
License: CC BY
Identifiers: DOI 10.1016/j.dib.2026.113064 · PMID 42541318 · PMCID PMC13427532 · OpenAlex W7167941105
Open access: gold, a free copy (OpenAlex)
Status: code verified
Categories: EEG (modality), human (organism), methods / tools (subfield)
Methods: Spectral & time-frequency, Preprocessing, Statistics, Smoothing, state filtering, decompositions, Connectivity, Evoked potentials, Graphs, Physiology & signal measures
Keywords: EEG hyperscanning, Triadic interaction, Prisoner’s Dilemma, Inter-brain synchrony, Phase-locking value, Event-related potentials
Topic: Reinforcement Learning in Robotics (Artificial Intelligence, Computer Science), according to OpenAlex
Funding: Ministry of Science and ICT, South Korea (2019-0-01842); Ministry of Education (RS-2025-25425143, RS-2024-00361688); Institute for Information and Communications Technology Promotion; National Research Foundation of Korea (NRF-2023S1A5A2A01076552); National Science Foundation (IIS-2554482)
Citations: not cited yet (Europe PMC); 14 references in the paper

Abstract

This data article describes an open EEG hyperscanning dataset acquired during an iterated 3-player Prisoner’s Dilemma (PD) task, designed to support reproducible research on triadic social decision-making. EEG was recorded simultaneously from three participants per group (11 groups; 33 subjects) using synchronized acquisition, with decision-locked and feedback-locked epochs provided for 40 task trials per subject and three 60-s resting-state runs per group. The released BIDS format contain 19-channel EEG arrays sampled at 300 Hz, with explicit epoch definitions for decision (−1000 to 4000 ms) and feedback (−1000 to 2000 ms) periods, as well as trial-wise behavioral choice labels (1=cooperate, 2=defect) enabling reconstruction of dyad- and triad-level outcomes. Questionnaire metadata (personal information and pre/mid/post state measures) Yare also provided as supplementary spreadsheets. To facilitate reuse and benchmarking, we release Python code that reproduces the preprocessing pipeline (average reference, FIR filtering, ICA + ICLabel for task EEG), ERP summaries, and inter-brain synchrony measures (PLV and coherence) with window-matched resting baselines and cluster-permutation statistics. The dataset is intended for method development and benchmarking in ERP analysis, inter-brain synchrony estimation, and modeling of dynamic group interaction states in triadic games.

Reproduced under the paper's license (CC BY), from the paper cited above.

Repository

Its files are read in the Code ↔ Paper reader above, with 6 matches between paragraphs and lines of code.

heegyukim4043/PD_EEG_hyperscan_processing

License: none: the authors keep all their rights
State: the link answers, verified on 27 September 2026
Evidence: files inventoried
Commit: 0862853f1095404db1f4df04f7c5ac17d8da3865, 15 July 2026
Languages: Python (6)
Size: 8 files, 6 scripts
Software Heritage: not archived
Found in: “Code availability”
Holds: README, environment (pd_eeg_analysis/requirements.txt)
Not found: license file, CITATION.cff, tests, continuous integration, documentation
Tools: NumPy (5 files), MNE-Python (4 files), SciPy (3 files), ICLabel (2 files), Matplotlib (2 files), pandas (1 file)
Availability: 1 check, the latest on 27 September 2026: the link answers
  • 27 September 2026: the link answers
7 files
At the source: github.com/heegyukim4043/PD_EEG_hyperscan_processing

Code availability

The analysis code is available at: https://github.com/heegyukim4043/PD_EEG_hyperscan_processing.

The repository provides a fully reproducible workflow to generate the main technical validation outputs from the released BIDS, including (i) preprocessing to create a cleaned cache (cleaned_eeg.pkl), (ii) inter-brain synchrony (IBS) analyses using PLV and circular correlation coefficient (ccorr) with cluster-based permutation testing, and (iii) ERP analyses for decision- and feedback-locked epochs. All scripts are organized to enable direct execution with minimal configuration, supporting full reproducibility of the reported results. The repository is structured to allow users to reproduce, verify, and extend all analyses from raw data to final outputs.

Preprocessing (bids.py): loads BIDS (.set) and produces results/cleaned_eeg.pkl after average referencing, band-pass filtering, and ICA-based artifact rejection for task EEG (Infomax ICA + ICLabel; eye blink/muscle, probability > 0.80). Resting EEG is processed with filtering and average reference (no ICA). This step generates a standardized intermediate dataset that serves as the input for all subsequent analyses and ensures consistency across the pipeline.

IBS analysis (ibs_analysis.py): computes dyad-wise IBS for all within-triad pairs (S1–S2, S1–S3, S2–S3) in the decision and feedback epochs using 0–1000 ms and 0–2000 ms windows, with a window-matched resting baseline and cluster-permutation tests (n=2000, two-tailed). Outputs include figures and per-band summary CSV tables. This analysis design enables statistically robust and comparable estimation of inter-brain synchrony across conditions.

Reproduced under the paper's license (CC BY), from the paper cited above.

Tracing map

Proposed by the machine: these links were found in the paper and verified at the source, without human review. The map will receive a Zenodo DOI once one of the paper's authors has validated it with their ORCID.

What the map holds:

  • 1 repository of the authors' code, each at its verified commit, with its license and how the link was found in the paper;
  • 6 scripts, each with its path and the digest of its content;
  • 6 matches between paragraphs of the paper and lines of the code (method lexical-v1);
  • neither the text of the paper nor the code itself.

Its JSON (tracing-map.json) is deposited on Zenodo with its DOI once the map is validated.

Data

Datasets cited

Data Availability Statement

The dataset is publicly available on OpenNeuro (DOI: https://doi.org/10.18112/openneuro.ds007822.v1.0.0). The repository contains BIDS format, questionnaire spreadsheets, behavioral annotations, and metadata required for reuse.

FigshareEEG and Hyperscanning, triadic Prisoner's dilemma game (Original data) (https://doi.org/10.6084/m9.figshare.32197038)

Reproduced under the paper's license (CC BY), from the paper cited above.

Versions

The history of this record: each version stored by the harvester or made by a correction of its authors or of the maintainers of its code, and what changed in its facts. The texts of the paper (its abstract, its availability statements) are not part of it; versions that changed only those are not listed.

Version 2, 28 September 2026

  • Authors: added SC Jun (0000-0001-5357-4436); CS Nam (0000-0001-9005-0703); removed SC Jun; CS Nam

Version 1, 27 September 2026: the first record

Recorded: type, language, journal, volume, pages, dates, 3 authors, 6 keywords, 5 funders, 14 references.

Cite

This paper

Kim, H., Jun, S., & Nam, C. (2026). A reproducible EEG hyperscanning dataset for triadic social decision-making during an iterated 3-player Prisoner's Dilemma. Data in brief, 68, 113064. https://doi.org/10.1016/j.dib.2026.113064

BibTeX

@article{kim2026reproducible,
author = {Kim, H and Jun, SC and Nam, CS},
title = {{A reproducible EEG hyperscanning dataset for triadic social decision-making during an iterated 3-player Prisoner's Dilemma}},
journal = {Data in brief},
year = {2026},
month = jul,
volume = {68},
pages = {113064},
publisher = {Elsevier},
issn = {2352-3409},
doi = {10.1016/j.dib.2026.113064},
url = {https://doi.org/10.1016/j.dib.2026.113064},
pmid = {42541318},
pmcid = {PMC13427532}
}

RIS

TY - JOUR
AU - Kim, H
AU - Jun, SC
AU - Nam, CS
TI - A reproducible EEG hyperscanning dataset for triadic social decision-making during an iterated 3-player Prisoner's Dilemma
T2 - Data in brief
J2 - Data Brief
PY - 2026
DA - 2026/07/10
VL - 68
SP - 113064
SN - 2352-3409
PB - Elsevier
DO - 10.1016/j.dib.2026.113064
UR - https://doi.org/10.1016/j.dib.2026.113064
LA - en
ER -

CSL-JSON

{
"id": "10.1016/j.dib.2026.113064",
"type": "article-journal",
"title": "A reproducible EEG hyperscanning dataset for triadic social decision-making during an iterated 3-player Prisoner's Dilemma",
"container-title": "Data in brief",
"author": [
{
"family": "Kim",
"given": "H"
},
{
"family": "Jun",
"given": "SC"
},
{
"family": "Nam",
"given": "CS"
}
],
"container-title-short": "Data Brief",
"volume": "68",
"page": "113064",
"DOI": "10.1016/j.dib.2026.113064",
"PMID": "42541318",
"PMCID": "PMC13427532",
"ISSN": "2352-3409",
"publisher": "Elsevier",
"URL": "https://doi.org/10.1016/j.dib.2026.113064",
"language": "en",
"issued": {
"date-parts": [
[
2026,
7,
10
]
]
}
}

The tracing map gets a citation of its own once an author has validated it and it has a DOI.

Similar papers

The papers with a page that share the most with this one: the tools found in their code, their categories, datasets, cited references and authors, the rarest counting most.

[1] doi:10.1093/cercor/bhag113 [code]
Long-term reliability and stability of parameterized resting state EEG: evidence from a five-year follow-up.
Journal: Cerebral cortex (New York, N.Y. : 1991)
In common: ICLabel, MNE-Python, pandas, 3 other tools, methods / tools, EEG, 2 references
[2] doi:10.1097/j.pain.0000000000004044 [code]
No effect of rhythmic visual stimulation on experimental pain perception.
Journal: Pain
In common: ICLabel, MNE-Python, pandas, 3 other tools, EEG, 2 references
[3] doi:10.3758/s13428-026-02997-z [code]
PyLossless: A non-destructive EEG processing pipeline.
Journal: Behavior research methods
In common: ICLabel, MNE-Python, pandas, 2 other tools, methods / tools, EEG, 2 references
[4] doi:10.1371/journal.pcbi.1014043 [code]
EEG-Pype: An accessible MNE-Python pipeline with graphical user interface for preprocessing and analysis of resting-state electroencephalography data.
Journal: PLoS computational biology
In common: ICLabel, MNE-Python, pandas, 3 other tools, methods / tools, EEG, 1 reference
[5] doi:10.1038/s41597-025-05174-7 [code]
A large-scale MEG and EEG dataset for object recognition in naturalistic scenes
Journal: n/a
In common: ICLabel, MNE-Python, pandas, 3 other tools, methods / tools, EEG, 1 reference
[6] doi:10.1002/hbm.70528 [code]
Explainable AI Insights Into EEG Classification and Its Alignment to Neural Correlates.
Journal: Human brain mapping
In common: ICLabel, MNE-Python, pandas, 3 other tools, EEG, 1 reference
[7] doi:10.3390/s26134019 [code]
NeuroStat: An Open-Source EEG Connectivity Platform for Randomised Controlled Trials.
Journal: Sensors (Basel, Switzerland)
In common: ICLabel, MNE-Python, pandas, 3 other tools, EEG, 1 reference
[8] doi:10.1038/s41597-026-07807-x [code]
A Multimodal fNIRS-EEG Dataset for Unilateral Limb Motor Imagery.
Journal: Scientific data
In common: ICLabel, MNE-Python, SciPy, 2 other tools, methods / tools, EEG, 1 reference
[9] doi:10.1038/s41597-026-07146-x [code]
Intention-Action Conflict EEG-Hand Kinematics Dataset for Unimanual Control under Congruent and Incongruent Conditions.
Journal: Scientific data
In common: ICLabel, MNE-Python, pandas, 3 other tools, methods / tools, EEG
[10] doi:10.1186/s12967-026-08108-y [code]
An explainable multimodal machine learning model for diagnosing disorders of consciousness: evidence from a large multicenter Chinese cohort.
Journal: Journal of translational medicine
In common: ICLabel, MNE-Python, pandas, 2 other tools, EEG, 1 reference

Contribute

The authors of this paper can claim it, correct its record and validate its tracing map, and the maintainers of its code (its owner, or a public member of its organization) correct what it says of their repository; anyone signed in can ask for its removal. Every request goes to OSCR's own machine, which answers it; your account page follows them.

Sign in with ORCID to claim this paper as one of its authors, correct its record or validate its tracing map: when the paper's metadata lists your ORCID iD, you are recognized at once. Maintainers of its code: sign in with GitHub, then claim the repository on your account page.

Request its removal

To ask OSCR to remove this record, the copies of its authors' scripts or its tracing map, use the removal request page: signed in, you say who you are, what to remove and why, then review and confirm the request. Published rules decide every request (how).

Discussion, reproductions, activity

Discussion: questions and error reports about this paper and its code, from signed-in readers and its authors. It opens with sign-in.

Reproductions: reports from readers who ran the authors' code: what they reproduced, with which environment, commit and data. It opens with sign-in.

Activity: what happens around this paper: new versions of its record, its map's validation, discussions and reproductions. It opens with sign-in.