Home

processFNIRS2 Wiki

processFNIRS2 (package name pf2) is a modular MATLAB toolbox for functional Near-Infrared Spectroscopy (fNIRS) analysis, covering the full workflow from raw device import through signal processing, hemoglobin conversion, quality control, visualization, and group-level statistics. It can be driven entirely as a script (headless, batch-friendly) or through its GUIs.

This wiki is for fNIRS researchers using or extending the toolbox. Start with Getting Started if this is your first time here.

Two-layer architecture

processFNIRS2 splits single-subject processing from multi-subject group analysis. The boundary between the two is a plain processed-data struct (or a cell array of them), so you can hand off from one layer to the other at any point in a script:

┌─────────────────────────────────────────────────────────────────┐
│              LAYER 2: GROUP ANALYSIS (exploreFNIRS)              │
│  Multi-subject statistics, LME modeling, group visualization     │
│  Input: cell array of processed fNIRS structs                    │
└─────────────────────────────────────────────────────────────────┘
                              ▲
                              │ processed fNIRS structs
┌─────────────────────────────────────────────────────────────────┐
│            LAYER 1: SINGLE-SUBJECT PROCESSING (pf2)               │
│  Raw data import, signal processing, hemoglobin conversion       │
│  Input: raw device files (.nir, .snirf, .oxy3, ...)              │
└─────────────────────────────────────────────────────────────────┘

Layer	Package	Handles
Layer 1 — Single-subject	pf2 (+pf2, +pf2_base)	Import, signal processing, motion correction, Beer-Lambert/Hb conversion, QC, probe/anatomy, DOT, visualization, export
Layer 2 — Group analysis	exploreFNIRS (+exploreFNIRS)	The Experiment/GLMExperiment classes, grouping/aggregation, connectivity, hyperscanning, LME-based statistics, group visualization

Quick Start

% Import bundled sample data (no files needed)
data = pf2.import.sampleData.fNIR2000();   % synthesized recording with TaskA/TaskB markers

% Process: raw intensity -> optical density -> hemoglobin.
% Assigning an output suppresses the GUI (headless).
processed = processFNIRS2(data);

% Visualize the result
pf2.data.plot.oxy(processed);              % HbO/HbR time series

That is the whole loop: import → process → visualize. See Getting Started for the next steps (markers, block averaging, and group analysis), or Installation if you have not put the toolbox on your MATLAB path yet.

Feature map

Page	What it covers
Getting Started	A first end-to-end walkthrough: import sample data, process to hemoglobin, inspect and plot the result.
Importing Data	Reading raw device files (fNIR Devices/Biopac .nir, SNIRF, Hitachi ETG-4000, NIRx, Artinis .oxy3), batch/directory import, and tidy-table import via fromTable.
Processing Pipeline	The three-stage raw → optical density → hemoglobin pipeline: motion correction, filtering, and DPF modes.
Block Averaging and Epoching	Defining event-locked blocks from markers, extracting epochs, and trial/grand averaging; marker-free sliding-window epoching.
Group Analysis	The exploreFNIRS Experiment/GLMExperiment classes: grouping, aggregation, GLM, connectivity, hyperscanning, and LME-based statistics.
Visualization	Time series, 2D/3D topographic maps, high-quality brain renders, activation movies, connectomes, and dark-mode plotting.
Quality Control	The headless QC pipeline (SCI, saturation, cardiac, CoV, Takizawa rejection), the interactive ChannelCheck GUI, and one-call QC snapshots.
Auxiliary Signals	Typed HR/EKG/PPG/ACCEL/GSR/EEG signals: grid alignment, feature extraction, and use as nuisance regressors or covariates.
Diffuse Optical Tomography	Image-space HbO/HbR reconstruction on the cortical surface via a forward sensitivity model and a regularized inverse.
Export and Interoperability	Writing NIR, SNIRF, true BIDS-NIRS datasets, tables, and self-describing HDF5 tensors.
API Reference	Package-by-package function reference across pf2, pf2_base, and exploreFNIRS.

Requirements

processFNIRS2 targets MATLAB R2025b; the Statistics and Machine Learning Toolbox is required for LME-based group statistics in exploreFNIRS. See Installation for the full requirements list and how to get the toolbox onto your MATLAB path.

See also

• Installation
• Getting Started
• API Reference