From 48b575566faccff27c6e606b2cddf718a3037597 Mon Sep 17 00:00:00 2001 From: natinew77-creator Date: Thu, 11 Dec 2025 15:39:32 -0500 Subject: [PATCH 1/5] DOC: Clarify read_raw_nirx expects directory path, not file path This improves the documentation for read_raw_nirx to prevent the common 'OSError: Need a directory for fname but found a file' error that users encounter when passing a single file path instead of a directory path. Changes: - Added a note in the read_raw_nirx docstring explaining the directory requirement and suggesting read_raw_snirf for .snirf files - Added an important note in the fNIRS tutorial with correct/incorrect examples and troubleshooting guidance Fixes #13353 --- mne/io/nirx/nirx.py | 12 +++++++++++- tutorials/io/30_reading_fnirs_data.py | 18 ++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/mne/io/nirx/nirx.py b/mne/io/nirx/nirx.py index 5d9b79b57cc..9e19e90eb0d 100644 --- a/mne/io/nirx/nirx.py +++ b/mne/io/nirx/nirx.py @@ -38,10 +38,20 @@ def read_raw_nirx( ) -> "RawNIRX": """Reader for a NIRX fNIRS recording. + .. note:: + This function expects a **directory path** containing all NIRx data + files (e.g., ``.hdr``, ``.wl1``, ``.wl2``, etc.), not a path to a + single file. Passing a file path (e.g., ``"data.nirs"``) will result + in an error. If you have a ``.snirf`` file, use + :func:`mne.io.read_raw_snirf` instead. + Parameters ---------- fname : path-like - Path to the NIRX data folder or header file. + Path to the NIRX data folder (directory containing NIRx files) or + the ``.hdr`` header file within that folder. The function will + automatically find and read all required NIRx files from the + directory. %(saturated)s %(preload)s %(encoding_nirx)s diff --git a/tutorials/io/30_reading_fnirs_data.py b/tutorials/io/30_reading_fnirs_data.py index a40935e9e19..9e52f1a9a75 100644 --- a/tutorials/io/30_reading_fnirs_data.py +++ b/tutorials/io/30_reading_fnirs_data.py @@ -90,6 +90,24 @@ version 15.0 and above and Aurora version 2021 and above. MNE-Python supports reading data from NIRScout and NIRSport devices. +.. important:: + The :func:`~mne.io.read_raw_nirx` function expects a **directory path** + (the folder containing all NIRx data files), not a path to a single file. + For example:: + + # Correct: pass the directory path + raw = mne.io.read_raw_nirx("/path/to/nirx_recording_folder/") + + # Incorrect: passing a single file will cause an error + raw = mne.io.read_raw_nirx("/path/to/file.nirs") # OSError! + + If you receive an ``OSError: Need a directory for fname but found a + file...`` error, ensure you are passing the parent directory that + contains the NIRx files, not a single file path. + + If your data is in SNIRF format (``.snirf``), use + :func:`mne.io.read_raw_snirf` instead. + .. _import-hitachi: From e5fc1dfce96cbd86621fbfa7233ccecd4db1206d Mon Sep 17 00:00:00 2001 From: natinew77-creator Date: Fri, 19 Dec 2025 20:36:41 -0500 Subject: [PATCH 2/5] Doc: proper placement of definition in nirx reader Address review comments from @larsoner: move directory clarification to Notes section in read_raw_nirx and remove redundant warning in tutorial. --- mne/io/nirx/nirx.py | 13 ++++++------- tutorials/io/30_reading_fnirs_data.py | 18 ------------------ 2 files changed, 6 insertions(+), 25 deletions(-) diff --git a/mne/io/nirx/nirx.py b/mne/io/nirx/nirx.py index 9e19e90eb0d..7954661f71b 100644 --- a/mne/io/nirx/nirx.py +++ b/mne/io/nirx/nirx.py @@ -38,13 +38,6 @@ def read_raw_nirx( ) -> "RawNIRX": """Reader for a NIRX fNIRS recording. - .. note:: - This function expects a **directory path** containing all NIRx data - files (e.g., ``.hdr``, ``.wl1``, ``.wl2``, etc.), not a path to a - single file. Passing a file path (e.g., ``"data.nirs"``) will result - in an error. If you have a ``.snirf`` file, use - :func:`mne.io.read_raw_snirf` instead. - Parameters ---------- fname : path-like @@ -70,6 +63,12 @@ def read_raw_nirx( Notes ----- %(nirx_notes)s + + This function expects a **directory path** containing all NIRx data + files (e.g., ``.hdr``, ``.wl1``, ``.wl2``, etc.), not a path to a + single file. Passing a file path (e.g., ``"data.nirs"``) will result + in an error. If you have a ``.snirf`` file, use + :func:`mne.io.read_raw_snirf` instead. """ return RawNIRX( fname, saturated, preload=preload, encoding=encoding, verbose=verbose diff --git a/tutorials/io/30_reading_fnirs_data.py b/tutorials/io/30_reading_fnirs_data.py index 9e52f1a9a75..a40935e9e19 100644 --- a/tutorials/io/30_reading_fnirs_data.py +++ b/tutorials/io/30_reading_fnirs_data.py @@ -90,24 +90,6 @@ version 15.0 and above and Aurora version 2021 and above. MNE-Python supports reading data from NIRScout and NIRSport devices. -.. important:: - The :func:`~mne.io.read_raw_nirx` function expects a **directory path** - (the folder containing all NIRx data files), not a path to a single file. - For example:: - - # Correct: pass the directory path - raw = mne.io.read_raw_nirx("/path/to/nirx_recording_folder/") - - # Incorrect: passing a single file will cause an error - raw = mne.io.read_raw_nirx("/path/to/file.nirs") # OSError! - - If you receive an ``OSError: Need a directory for fname but found a - file...`` error, ensure you are passing the parent directory that - contains the NIRx files, not a single file path. - - If your data is in SNIRF format (``.snirf``), use - :func:`mne.io.read_raw_snirf` instead. - .. _import-hitachi: From 5441f9ebcdcccbb6f2d880abd5f4bfbfca15ce1e Mon Sep 17 00:00:00 2001 From: natinew77-creator Date: Fri, 19 Dec 2025 20:55:37 -0500 Subject: [PATCH 3/5] Doc: move nirx directory warning to centralized nirx_notes This ensures the clarification appears in both read_raw_nirx and RawNIRX documentation while maintaining cleaner docstring code. --- mne/io/nirx/nirx.py | 6 ------ mne/utils/docs.py | 6 ++++++ 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/mne/io/nirx/nirx.py b/mne/io/nirx/nirx.py index 7954661f71b..1654b54ea7a 100644 --- a/mne/io/nirx/nirx.py +++ b/mne/io/nirx/nirx.py @@ -63,12 +63,6 @@ def read_raw_nirx( Notes ----- %(nirx_notes)s - - This function expects a **directory path** containing all NIRx data - files (e.g., ``.hdr``, ``.wl1``, ``.wl2``, etc.), not a path to a - single file. Passing a file path (e.g., ``"data.nirs"``) will result - in an error. If you have a ``.snirf`` file, use - :func:`mne.io.read_raw_snirf` instead. """ return RawNIRX( fname, saturated, preload=preload, encoding=encoding, verbose=verbose diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 54b2c9f1363..669f1dad433 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -2884,6 +2884,12 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): called .nosatflags_wlX. As NaN values can cause unexpected behaviour with mathematical functions the default behaviour is to return the saturated data. + +This function expects a **directory path** containing all NIRx data +files (e.g., ``.hdr``, ``.wl1``, ``.wl2``, etc.), not a path to a +single file. Passing a file path (e.g., ``"data.nirs"``) will result +in an error. If you have a ``.snirf`` file, use +:func:`mne.io.read_raw_snirf` instead. """ docdict["niter"] = """ From 8cf299edbdeb5461172d79907a833a9aa42ceb51 Mon Sep 17 00:00:00 2001 From: natinew77-creator Date: Thu, 25 Dec 2025 14:23:18 -0500 Subject: [PATCH 4/5] Doc: update nirx_notes to use .. note:: directive Incorporated feedback to format the directory requirement as a proper admonition note. --- mne/utils/docs.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 669f1dad433..fe1bc00d5ef 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -2885,11 +2885,10 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): mathematical functions the default behaviour is to return the saturated data. -This function expects a **directory path** containing all NIRx data -files (e.g., ``.hdr``, ``.wl1``, ``.wl2``, etc.), not a path to a -single file. Passing a file path (e.g., ``"data.nirs"``) will result -in an error. If you have a ``.snirf`` file, use -:func:`mne.io.read_raw_snirf` instead. +.. note:: + This function expects ``fname`` to be a path to a directory containing the + NIRX data files (e.g., ``.hdr``, ``.wl1``, ``.wl2``, etc.). If you have a + ``.snirf`` file, use :func:`mne.io.read_raw_snirf` instead. """ docdict["niter"] = """ From 9f2f34b2b82cb2cf6117bea8bb88f4043d64d0bd Mon Sep 17 00:00:00 2001 From: natinew77-creator Date: Thu, 25 Dec 2025 18:24:10 -0500 Subject: [PATCH 5/5] Doc: fix NIRX capitalization in docstring --- mne/io/nirx/nirx.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mne/io/nirx/nirx.py b/mne/io/nirx/nirx.py index 1654b54ea7a..eb4101be0af 100644 --- a/mne/io/nirx/nirx.py +++ b/mne/io/nirx/nirx.py @@ -41,9 +41,9 @@ def read_raw_nirx( Parameters ---------- fname : path-like - Path to the NIRX data folder (directory containing NIRx files) or + Path to the NIRX data folder (directory containing NIRX files) or the ``.hdr`` header file within that folder. The function will - automatically find and read all required NIRx files from the + automatically find and read all required NIRX files from the directory. %(saturated)s %(preload)s