Installation

Installation

How to get processFNIRS2 onto your MATLAB path and verify it works. This page is for anyone setting the toolbox up for the first time, on a new machine, or in a CI/batch environment.

Requirements

• MATLAB R2025b.
• Statistics and Machine Learning Toolbox — required for LME-based group statistics in exploreFNIRS (statsAutoLME and related).
• No other toolboxes are required for the default processing pipeline: filtering, wavelet, Savitzky-Golay, and median-filter routines are implemented first-party (+pf2_base/+external, +pf2_base/+wavelet), so the core import → process → Hb pipeline needs neither the Signal Processing nor the Wavelet Toolbox.
• Signal Processing Toolbox — not needed for the core pipeline, but still used by a few specific features: the QC power spectrum (pf2.qc.powerSpectrum, via pwelch/findpeaks), coherence-based connectivity (exploreFNIRS.coupling.coherence/partialCoherence, via cpsd/mscohere), and the optional equiripple-FIR filter variant in pf2_lpf. If that toolbox is unavailable, everything else in the toolbox still runs.

Get the toolbox onto your path

1. Clone or download the repository.
2. Add only the repository root to your MATLAB path:

   addpath('/path/to/processFNIRS2');

That is genuinely all that is required. The current (v1.0.1) layout is:

processFNIRS2/
├── +pf2/            # main user-facing package
├── +pf2_base/        # advanced/internal APIs
├── +exploreFNIRS/    # group-analysis package
├── base_functions/    # legacy support functions (GUI plumbing, plotting helpers)
├── functions/         # processing algorithm implementations (pipeline steps)
├── GUI/                # .fig/.m files for the interactive GUIs
├── devices/            # device configuration files (.cfg)
├── sampledata/         # bundled example datasets
├── examples/scripts/   # runnable tutorial scripts
├── processFNIRS2.m     # main entry point (non-GUI capable)
└── exploreFNIRS.m      # entry point for the exploreFNIRS GUI

+-prefixed folders (+pf2, +pf2_base, +exploreFNIRS) are MATLAB packages and resolve automatically from the root being on the path — you never add them individually. The three loose folders base_functions, functions, and GUI are not something you need to addpath by hand either: pf2_initialize() adds them for you automatically the first time you call processFNIRS2 or any pf2.* function (+pf2_base/pf2_initialize.m: addpath(PF2.defaultRootPath, 'base_functions', 'functions', 'GUI')). If you have used an older processFNIRS2 wiki page or README that told you to manually add base_functions, GUI, and functions to the path yourself — that instruction is obsolete; a plain root-level addpath is sufficient as of the current release.

If you want the toolbox available in every MATLAB session without re-running addpath, save the path once after adding the root:

addpath('/path/to/processFNIRS2');
savepath;

Verify your install

Run the sample-data quick start headlessly from a terminal:

cd /path/to/processFNIRS2 && \
/Applications/MATLAB_R2025b.app/bin/matlab -batch "data = pf2.import.sampleData.fNIR2000(); processed = processFNIRS2(data); disp('Done')"

(Adjust the MATLAB binary path for your platform — e.g. matlab -batch "..." if matlab is already on your system PATH.) A successful run prints Done and exits with status 0. -batch is preferred over -r for automation: it auto-exits and returns a non-zero exit code on error. See Getting Started for the interactive version of the same workflow.

Or, from within an already-running MATLAB session:

data = pf2.import.sampleData.fNIR2000();
processed = processFNIRS2(data);
disp('Done')

Where methods and preferences are stored

The first time processFNIRS2/pf2 runs, pf2_initialize() seeds a working set of default processing methods and writes them to your MATLAB preferences directory (prefdir), not into the repository:

• Raw-stage methods: <prefdir>/pf2_raw_methods_stored_processFNIRS2.cfg
• Oxy-stage methods: <prefdir>/pf2_oxy_methods_stored_processFNIRS2.cfg

These are per-user, machine-local files — safe to delete if the toolbox gets into a bad state (they will be regenerated with defaults on the next run). Device probe geometries ship as .cfg files under devices/ in the repo itself (loaded via pf2.Device.load), and are separate from the per-user method files above. Default processing parameters (DPF mode/value, baseline window, channel-rejection level) live on the PF2 global structure and can be inspected/changed via pf2.settings.*; see Processing Pipeline for the parameter reference.

See also

• Home
• Getting Started
• Processing Pipeline
• API Reference