If Naming Fails BIDS Validation, Cannot Use fMRIPrep?

Software Support
,
1

Summary of what happened:

I am getting an error message stating that there are no BOLD images in my dataset for a single subject. There are, in fact, BOLD files but fMRIprep seems unable to find them. This dataset it being used by many, many people at my lab, and they have all developed scripts based on the names here, so I am not at liberty to change them. My question is whether this means I am unable to use fMRIprep at all, as it is not finding my BOLD files or whether there is some other issue at play here. Thanks again!

Command used (and if a helper script was used, a link to the helper script or the command generated):

#!/bin/bash
export DOCKER_CONTENT_TRUST=0

if [ $# -ne 1 ]; then
    echo "Usage: $0 <subject_number>"
    exit 1
fi

subj=$1
echo "Starting subject ${subj}"

bids_root_dir="/lbc/lbc1/Brain150/BIDS/EE_BIDS/YA"
project_dir="/lbc/lbc1/derivatives/ED/fMRI_Preproc_Comparison"
bids_deriv_dir="${project_dir}/fmriprep"
workdir="${project_dir}/work/sub-${subj}"
license_file="/lbc/lbc1/derivatives/ED/fMRI_Preproc_Comparison/license.txt"

mkdir -p "$workdir"

docker run --rm --user $(id -u):$(id -g) \
  -v ${bids_root_dir}:/data:ro \
  -v ${bids_deriv_dir}:/out \
  -v ${workdir}:/work \
  -v ${license_file}:/license.txt:ro \
  nipreps/fmriprep:25.2.5 \
  /data /out participant \
  --skip-bids-validation
  --participant-label ${subj} \
  --task-id ['rest'] \
  --session-label ['02'] \
  --echo-idx 2 \
  --fs-license-file /license.txt \

echo "Finished subject ${subj}"

Version:

25.2.5

Environment (Docker, Singularity / Apptainer, custom installation):

Docker

Data formatted according to a validatable standard? Please provide the output of the validator:

No. Minor naming inconsistencies appear to plague my data. For example:

[ERR] acq Name contain an Illegal Character hyphen or underscore. Please edit the filename as per BIDS spec. (code: 59 - ACQ_NAME_CONTAIN_ILLEGAL_CHARACTER)
		./sub-087/ses-01/anat/sub-087_ses-01_acq-MP2RAGE_T1w_TB1-map_ROI1_run-01.nii.gz

Relevant log outputs (up to 20 lines):

260313-16:21:47,771 nipype.workflow IMPORTANT:
	 Running fMRIPrep version 25.2.5

         License NOTICE ##################################################
         fMRIPrep 25.2.5
         Copyright The NiPreps Developers.
         
         This product includes software developed by
         the NiPreps Community (https://nipreps.org/).
         
         Portions of this software were developed at the Department of
         Psychology at Stanford University, Stanford, CA, US.
         
         This software is also distributed as a Docker container image.
         The bootstrapping file for the image ("Dockerfile") is licensed
         under the MIT License.
         
         This software may be distributed through an add-on package called
         "Docker Wrapper" that is under the BSD 3-clause License.
         #################################################################
260313-16:21:47,771 nipype.workflow IMPORTANT:
	 Building fMRIPrep's workflow:
           * BIDS dataset path: /data.
           * Participants and sessions: sub-087.
           * Run identifier: 20260313-162108_f0a4d9d5-f1a7-47da-b1a1-4ee3920775e0.
           * Output spaces: MNI152NLin2009cAsym:res-native.
           * Pre-run FreeSurfer's SUBJECTS_DIR: /out/sourcedata/freesurfer.
Process Process-2:
Traceback (most recent call last):
  File "/app/.pixi/envs/fmriprep/lib/python3.12/multiprocessing/process.py", line 314, in _bootstrap
    self.run()
  File "/app/.pixi/envs/fmriprep/lib/python3.12/multiprocessing/process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "/app/.pixi/envs/fmriprep/lib/python3.12/site-packages/fmriprep/cli/workflow.py", line 116, in build_workflow
    retval['workflow'] = init_fmriprep_wf()
                         ^^^^^^^^^^^^^^^^^^
  File "/app/.pixi/envs/fmriprep/lib/python3.12/site-packages/fmriprep/workflows/base.py", line 108, in init_fmriprep_wf
    single_subject_wf = init_single_subject_wf(subject_id, sessions, name=wf_name)
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.pixi/envs/fmriprep/lib/python3.12/site-packages/fmriprep/workflows/base.py", line 244, in init_single_subject_wf
    raise RuntimeError(
RuntimeError: No BOLD images found for participant 087 and task [rest]. All workflows require BOLD images.
Finished subject 087
emilyd@burgundy:/lbc/lbc1/derivatives/ED/fMRI_Preproc_Comparison/scripts$

Screenshots / relevant information:

2

Hi @ejdavid,

Yes, if the files names are not BIDS valid (e.g the anatomical file you put in your post that had extra entities after _T1w), then fMRIPrep will not locate them. At the very least, the file organization, subject/session name, and file suffix (e.g. _bold.nii.gz/json, _T1w.nii.gz) needs to be right. And obvious rules cannot be broken (e.g. extra hyphens or underscores in invalid places).

You are welcome to symlink the data under different names in a new BIDS-valid directory. Symlinks will not take up additional storage.

Best,
Steven

3

Hi Steven,

Thanks for your quick response. I’ve created the Symlink files, and adjusted the non-BIDS compliant naming. I am now running into he following issue:

bids-validator@1.14.10
(node:9) Warning: Closing directory handle on garbage collection
(Use `node --trace-warnings ...` to show where the warning was created)
	1: [ERR] Files with such naming scheme are not part of BIDS specification. This error is most commonly caused by typos in file names that make them not BIDS compatible. Please consult the specification and make sure your files are named correctly. If this is not a file naming issue (for example when including files not yet covered by the BIDS specification) you should include a ".bidsignore" file in your dataset (see https://github.com/bids-standard/bids-validator#bidsignore for details). Please note that derived (processed) data should be placed in /derivatives folder and source data (such as DICOMS or behavioural logs in proprietary formats) should be placed in the /sourcedata folder. (code: 1 - NOT_INCLUDED)
		./sub-087/ses-02/anat/sub-087_T1w.json
			Evidence: sub-087_T1w.json
		./sub-087/ses-02/anat/sub-087_T1w.nii.gz
			Evidence: sub-087_T1w.nii.gz

	Please visit https://neurostars.org/search?q=NOT_INCLUDED for existing conversations about this issue.

	2: [ERR] Dataset does not contain any T1w scans. (code: 53 - NO_T1W)

	Please visit https://neurostars.org/search?q=NO_T1W for existing conversations about this issue.

	3: [ERR] Session label in the filename doesn't match with the path of the file. File seems to be saved in incorrect session directory. (code: 65 - SESSION_LABEL_IN_FILENAME_DOESNOT_MATCH_DIRECTORY)
		./sub-087/ses-02/anat/sub-087_T1w.json
			Evidence: File: /sub-087/ses-02/anat/sub-087_T1w.json is saved in incorrect session directory as per ses-id in filename.
		./sub-087/ses-02/anat/sub-087_T1w.nii.gz
			Evidence: File: /sub-087/ses-02/anat/sub-087_T1w.nii.gz is saved in incorrect session directory as per ses-id in filename.

	Please visit https://neurostars.org/search?q=SESSION_LABEL_IN_FILENAME_DOESNOT_MATCH_DIRECTORY for existing conversations about this issue.

	1: [WARN] The recommended file /README is missing. See Section 03 (Modality agnostic files) of the BIDS specification. (code: 101 - README_FILE_MISSING)

	Please visit https://neurostars.org/search?q=README_FILE_MISSING for existing conversations about this issue.

        Summary:                Available Tasks:        Available Modalities: 
        91 Files, 9.19GB                                MRI                   
        1 - Subject                                                           
        1 - Session                                                           


	If you have any questions, please post on https://neurostars.org/tags/bids.
Traceback (most recent call last):
  File "/app/.pixi/envs/fmriprep/bin/fmriprep", line 10, in <module>
    sys.exit(main())
             ^^^^^^
  File "/app/.pixi/envs/fmriprep/lib/python3.12/site-packages/fmriprep/cli/run.py", line 40, in main
    parse_args()
  File "/app/.pixi/envs/fmriprep/lib/python3.12/site-packages/fmriprep/cli/parser.py", line 949, in parse_args
    validate_input_dir(
  File "/app/.pixi/envs/fmriprep/lib/python3.12/site-packages/fmriprep/utils/bids.py", line 287, in validate_input_dir
    subprocess.check_call(['bids-validator', str(bids_dir), '-c', temp.name])  # noqa: S607
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.pixi/envs/fmriprep/lib/python3.12/subprocess.py", line 413, in check_call
    raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['bids-validator', '/data', '-c', '/tmp/tmpyb10wls8.json']' returned non-zero exit status 1.
Finished subject 087

I have adjusted my code the following:

#!/bin/bash
export DOCKER_CONTENT_TRUST=0

if [ $# -ne 1 ]; then
    echo "Usage: $0 <subject_number>"
    exit 1
fi

subj=$1
echo "Starting subject ${subj}"

bids_root_dir="/lbc/lbc1/derivatives/ED/fMRI_Preproc_Comparison/EE_BIDS"
project_dir="/lbc/lbc1/derivatives/ED/fMRI_Preproc_Comparison"
bids_deriv_dir="${project_dir}/fmriprep"
workdir="${project_dir}/work/sub-${subj}"
license_file="${project_dir}/license.txt"

mkdir -p "$workdir"
mkdir -p "$bids_deriv_dir"

docker run --rm --user $(id -u):$(id -g) \
  -v /lbc:/lbc:ro \
  -v "${bids_root_dir}:/data:ro" \
  -v "${bids_deriv_dir}:/out" \
  -v "${workdir}:/work" \
  -v "${license_file}:/license.txt:ro" \
  nipreps/fmriprep:25.2.5 \
  /data /out participant \
  --participant-label "${subj}" \
  --echo-idx 2 \
  --fs-license-file /license.txt \
  -w /work

echo "Finished subject ${subj}"

Is there a reason I am running intot his error that might be specific to the Symlink files? Or is this something else? Any information you may have would be highly useful. Thanks again!

4

Hi @ejdavid,

Please refer to the BIDS validator output:

Your files are missing ses-<> labels.

Also keep in mind that when you symlink you have to make sure both the source and target of the symlink are available to docker via mounts. For that reason, it is usually safer to not rename the input folder when mounted, as those renamings are likely not reflected in the symlink.

Best,
Steven

5

Thanks again,

Last issue, I hope.

When I run my script without --echo-idx 2 it is working fine now, but when I include this, I am getting the error:

RuntimeError: No BOLD images found for participant 087 and task <all>. All workflows require BOLD images.

My files are named as follows:
sub-087_ses-02_task-rest_acq-1p4mm_run-01_echo-02_part-mag_bold.nii.gz (I have matching .json files for each).

I’ve tried changing --echo-idx 2 to --echo-idx 02 and --echo-idx "02" neither of which worked. is there a reason it is able to find BOLD files without the echo-idx tag, but not with it?

6

Hi @ejdavid,

If you only want to only process the second echo, you might be better off with a BIDS filter file instead of using that CLI argument. e.g.,:

"bold": {"datatype": "func", "suffix": "bold", "echo": "02"}

Best,
Steven