Phase-restricted wavelet detection of event-related fNIRS responses: calibrated and latency-robust detection under physiological noise

Description

Code and data to reproduce the analyses in "Phase-restricted wavelet detection of event-related fNIRS responses: calibrated and latency-robust detection under physiological noise." The bundle contains three fully commented R scripts and the fourteen resting-state fNIRS recordings used in the paper. Script 01 runs a single-channel Monte Carlo simulation that sweeps hemodynamic latency and signal-to-noise ratio and compares a phase-restricted continuous-wavelet detector against canonical, informed-basis, and finite-impulse-response (FIR) general linear models on false-positive rate and amplitude recovery. Script 02 injects a known hemodynamic response into each real recording, which is used only as an empirical noise carrier so that the ground truth is exact, and compares every detector, including autoregressive-prewhitened GLMs, at a matched 5% false-positive rate, reporting sensitivity with across-subject dispersion. Script 03 is a phase-restriction ablation showing that the phase mask, rather than band-limited wavelet power alone, drives the detector's advantage. The recordings are the plain resting-state files from von Lühmann et al. (2020), redistributed under the dataset's original open-access terms (see DATA_SOURCE.md); please cite that dataset in any reuse. All random draws are seeded, so the reported numbers reproduce exactly. Software: R (version 4.0 or later) with the biwavelet, fmrihrf, hdf5r, and openxlsx packages.

Steps to reproduce

1- Install R (4.0 or later) and the packages: install.packages(c("biwavelet","hdf5r","openxlsx")), and install fmrihrf from its source (for example remotes::install_github("bbuchsbaum/fmrihrf"); see https://bbuchsbaum.github.io/fmrihrf/). 2- Set R's working directory to the Study_Materials folder, so the relative path data resolves to the bundled recordings. 3- Run the three scripts (each ships with QUICK = FALSE to reproduce the full published numbers; set QUICK = TRUE for a fast subset check). Outputs are written into the same folder. - source("code/01_simulation_latency_snr.R") produces 01_Method_Comparison_LatencySNR.xlsx and Method_Comparison_plots.pdf (simulation). - source("code/02_realfnirs_detection.R") produces fNIRS_Analysis1_real.xlsx (real-fNIRS detection). - source("code/03_wavelet_ablation.R") produces Wavelet_Ablation_real.xlsx (phase-restriction ablation). 4- Map outputs to the manuscript: Table 2 false-positive rates come from the TypeI sheet of 01 (Simulation column) and the Thresholds sheet of 02 (Real fNIRS column); Table 3 and Figure 1A from the Summary sheet of 01; Table 4 and Figure 2 from the Comparison sheet of 02 (sensitivity with across-subject SD); Table 5 from the Comparison sheet of 03 (wavelet_no_sig is phase + cone-of-influence, wavelet_power is cone-of-influence only). Runtime: the simulation takes a few minutes; each real-fNIRS script takes roughly 30 to 60 minutes because of the wavelet transforms and autoregressive fits across 14 subjects, 16 channels, and 2 schedule offsets.

Institutions

• University of Haifa

  Haifa, Haifa

Categories

Licence