fMRIPost-AROMA command specifications and troubleshooting documentation

Summary of what happened:

I am attempting to use fmripost-aroma but am encountering difficulties with some of the specifications that I previously had not encountered when ICA-AROMA was still integrated in fmriprep. I have gotten various errors (related to dummy scans, extraction of motion parameters, etc.), which leads me to think that my initial specification within the command is incorrect/incomple. I did not yet find a clear documentation for troubleshooting with fmripost-aroma. I based my specification based on this post but know it may differ.

Any ideas what aspects of the command may be incorrect or where to look (beyond the relatively limited fmripost-aroma read the docs)?

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

fmriprep:

fmriprep-docker {$PROJ_DIR}/niftidata/ {$PROJ_DIR}/2_fmriprep participant --participant-label P001 --fs-license-file {$PROJ_DIR}/FreeSurfer/license.txt --bids-filter-file {$PROJ_DIR}/2_fmriprep/code/P001_for-bids-filter-file.json --output-spaces MNI152NLin6Asym:res-02 --nthreads 24 --omp-nthreads 8


fmripost-aroma

docker run --rm -it \
	-v {$PROJ_DIR}/niftidata:/data \
	-v {$PROJ_DIR}/3_fmripost-aroma:/out \
	-v {$PROJ_DIR}/2_fmriprep:/prep \
	nipreps/fmripost-aroma:main \
	/data  \
	/out \
	participant \
	--derivatives fmriprep=/prep \
	--denoising-method nonaggr \
	--participant-label P001

Version:

Presumably the latest version as pulled from here: GitHub - nipreps/fmripost-aroma: Run ICA-AROMA on fMRIPrep derivatives · GitHub .
I cannot get the fmripost-aroma -h to work to check the version.

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

Both fmriprep and fmripost-aroma were installed with Docker containerization.

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

The data was already run through fmriprep without issues (–skip-bids-validation was not set).

Relevant log outputs (up to 20 lines):

Process Process-2:
Traceback (most recent call last):
  File "/opt/conda/envs/fmripost_aroma/lib/python3.11/multiprocessing/process.py", line 314, in _bootstrap
    self.run()
  File "/opt/conda/envs/fmripost_aroma/lib/python3.11/multiprocessing/process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "/opt/conda/envs/fmripost_aroma/lib/python3.11/site-packages/fmripost_aroma/cli/workflow.py", line 115, in build_workflow
    retval['workflow'] = init_fmripost_aroma_wf()
                         ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/conda/envs/fmripost_aroma/lib/python3.11/site-packages/fmripost_aroma/workflows/base.py", line 71, in init_fmripost_aroma_wf
    single_subject_wf = init_single_subject_wf(subject_id)
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/conda/envs/fmripost_aroma/lib/python3.11/site-packages/fmripost_aroma/workflows/base.py", line 280, in init_single_subject_wf
    single_run_wf = init_single_run_wf(bold_file)
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/conda/envs/fmripost_aroma/lib/python3.11/site-packages/fmripost_aroma/workflows/base.py", line 334, in init_single_run_wf
    raise ValueError(
ValueError: No confounds detected. Automatical dummy scan detection cannot be performed. Please set the `--dummy-scans` flag explicitly.

Edit: I did already insert --dummy-scans with some value. However, this lent to subsequent issues, such as the extraction of motion parameters mentioned in the summary. This made me think that my initial command was anyways incorrect and the source of the issue that I am unsure how to solve.

Can you post the tree output for your fMRIPrep derivatives and raw dataset?

Yes, sure. From the raw data, I only called T1w, the fmaps, task-absent, task-present_run-02, and task-rest for processing with fMRIPrep.

raw:

├── anat
│   ├── sub-P001_acq-prenorm_T1w.json
│   ├── sub-P001_acq-prenorm_T1w.nii.gz
│   ├── sub-P001_T1w.json
│   └── sub-P001_T1w.nii.gz
├── fmap
│   ├── sub-P001_acq-dwi_magnitude1.json
│   ├── sub-P001_acq-dwi_magnitude1.nii.gz
│   ├── sub-P001_acq-dwi_magnitude2.json
│   ├── sub-P001_acq-dwi_magnitude2.nii.gz
│   ├── sub-P001_acq-dwi_phasediff.json
│   ├── sub-P001_acq-dwi_phasediff.nii.gz
│   ├── sub-P001_magnitude1.json
│   ├── sub-P001_magnitude1.nii.gz
│   ├── sub-P001_magnitude2.json
│   ├── sub-P001_magnitude2.nii.gz
│   ├── sub-P001_phasediff.json
│   └── sub-P001_phasediff.nii.gz
└── func
    ├── sub-P001_task-absent_bold.json
    ├── sub-P001_task-absent_bold.nii.gz
    ├── sub-P001_task-present_run-01_bold.json
    ├── sub-P001_task-present_run-01_bold.nii.gz
    ├── sub-P001_task-present_run-02_bold.json
    ├── sub-P001_task-present_run-02_bold.nii.gz
    ├── sub-P001_task-rest_bold.json
    └── sub-P001_task-rest_bold.nii.gz

fmriprep output:

anat
│   ├── sub-P001_desc-aparcaseg_dseg.nii.gz
│   ├── sub-P001_desc-aseg_dseg.nii.gz
│   ├── sub-P001_desc-brain_mask.json
│   ├── sub-P001_desc-brain_mask.nii.gz
│   ├── sub-P001_desc-preproc_T1w.json
│   ├── sub-P001_desc-preproc_T1w.nii.gz
│   ├── sub-P001_desc-ribbon_mask.json
│   ├── sub-P001_desc-ribbon_mask.nii.gz
│   ├── sub-P001_dseg.nii.gz
│   ├── sub-P001_from-fsnative_to-T1w_mode-image_xfm.txt
│   ├── sub-P001_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5
│   ├── sub-P001_from-MNI152NLin6Asym_to-T1w_mode-image_xfm.h5
│   ├── sub-P001_from-T1w_to-fsnative_mode-image_xfm.txt
│   ├── sub-P001_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5
│   ├── sub-P001_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5
│   ├── sub-P001_hemi-L_curv.shape.gii
│   ├── sub-P001_hemi-L_desc-cortex_mask.json
│   ├── sub-P001_hemi-L_desc-cortex_mask.label.gii
│   ├── sub-P001_hemi-L_inflated.surf.gii
│   ├── sub-P001_hemi-L_midthickness.surf.gii
│   ├── sub-P001_hemi-L_pial.surf.gii
│   ├── sub-P001_hemi-L_space-fsaverage_desc-reg_sphere.surf.gii
│   ├── sub-P001_hemi-L_space-fsLR_desc-msmsulc_sphere.surf.gii
│   ├── sub-P001_hemi-L_space-fsLR_desc-reg_sphere.surf.gii
│   ├── sub-P001_hemi-L_sphere.surf.gii
│   ├── sub-P001_hemi-L_sulc.shape.gii
│   ├── sub-P001_hemi-L_thickness.shape.gii
│   ├── sub-P001_hemi-L_white.surf.gii
│   ├── sub-P001_hemi-R_curv.shape.gii
│   ├── sub-P001_hemi-R_desc-cortex_mask.json
│   ├── sub-P001_hemi-R_desc-cortex_mask.label.gii
│   ├── sub-P001_hemi-R_inflated.surf.gii
│   ├── sub-P001_hemi-R_midthickness.surf.gii
│   ├── sub-P001_hemi-R_pial.surf.gii
│   ├── sub-P001_hemi-R_space-fsaverage_desc-reg_sphere.surf.gii
│   ├── sub-P001_hemi-R_space-fsLR_desc-msmsulc_sphere.surf.gii
│   ├── sub-P001_hemi-R_space-fsLR_desc-reg_sphere.surf.gii
│   ├── sub-P001_hemi-R_sphere.surf.gii
│   ├── sub-P001_hemi-R_sulc.shape.gii
│   ├── sub-P001_hemi-R_thickness.shape.gii
│   ├── sub-P001_hemi-R_white.surf.gii
│   ├── sub-P001_label-CSF_probseg.nii.gz
│   ├── sub-P001_label-GM_probseg.nii.gz
│   ├── sub-P001_label-WM_probseg.nii.gz
│   ├── sub-P001_space-MNI152NLin6Asym_res-02_desc-brain_mask.json
│   ├── sub-P001_space-MNI152NLin6Asym_res-02_desc-brain_mask.nii.gz
│   ├── sub-P001_space-MNI152NLin6Asym_res-02_desc-preproc_T1w.json
│   ├── sub-P001_space-MNI152NLin6Asym_res-02_desc-preproc_T1w.nii.gz
│   ├── sub-P001_space-MNI152NLin6Asym_res-02_dseg.json
│   ├── sub-P001_space-MNI152NLin6Asym_res-02_dseg.nii.gz
│   ├── sub-P001_space-MNI152NLin6Asym_res-02_label-CSF_probseg.nii.gz
│   ├── sub-P001_space-MNI152NLin6Asym_res-02_label-GM_probseg.nii.gz
│   └── sub-P001_space-MNI152NLin6Asym_res-02_label-WM_probseg.nii.gz
├── figures
│   ├── sub-P001_desc-about_T1w.html
│   ├── sub-P001_desc-conform_T1w.html
│   ├── sub-P001_desc-reconall_T1w.svg
│   ├── sub-P001_desc-summary_T1w.html
│   ├── sub-P001_dseg.svg
│   ├── sub-P001_fmapid-auto00001_desc-phasediff_fieldmap.svg
│   ├── sub-P001_space-MNI152NLin6Asym_T1w.svg
│   ├── sub-P001_task-absent_desc-carpetplot_bold.svg
│   ├── sub-P001_task-absent_desc-compcorvar_bold.svg
│   ├── sub-P001_task-absent_desc-confoundcorr_bold.svg
│   ├── sub-P001_task-absent_desc-coreg_bold.svg
│   ├── sub-P001_task-absent_desc-fmapCoreg_bold.svg
│   ├── sub-P001_task-absent_desc-rois_bold.svg
│   ├── sub-P001_task-absent_desc-sdc_bold.svg
│   ├── sub-P001_task-absent_desc-summary_bold.html
│   ├── sub-P001_task-absent_desc-validation_bold.html
│   ├── sub-P001_task-present_run-02_desc-carpetplot_bold.svg
│   ├── sub-P001_task-present_run-02_desc-compcorvar_bold.svg
│   ├── sub-P001_task-present_run-02_desc-confoundcorr_bold.svg
│   ├── sub-P001_task-present_run-02_desc-coreg_bold.svg
│   ├── sub-P001_task-present_run-02_desc-fmapCoreg_bold.svg
│   ├── sub-P001_task-present_run-02_desc-rois_bold.svg
│   ├── sub-P001_task-present_run-02_desc-sdc_bold.svg
│   ├── sub-P001_task-present_run-02_desc-summary_bold.html
│   ├── sub-P001_task-present_run-02_desc-validation_bold.html
│   ├── sub-P001_task-rest_desc-carpetplot_bold.svg
│   ├── sub-P001_task-rest_desc-compcorvar_bold.svg
│   ├── sub-P001_task-rest_desc-confoundcorr_bold.svg
│   ├── sub-P001_task-rest_desc-coreg_bold.svg
│   ├── sub-P001_task-rest_desc-fmapCoreg_bold.svg
│   ├── sub-P001_task-rest_desc-rois_bold.svg
│   ├── sub-P001_task-rest_desc-sdc_bold.svg
│   ├── sub-P001_task-rest_desc-summary_bold.html
│   └── sub-P001_task-rest_desc-validation_bold.html
├── fmap
│   ├── sub-P001_fmapid-auto00001_desc-brain_mask.nii.gz
│   ├── sub-P001_fmapid-auto00001_desc-coeff_fieldmap.nii.gz
│   ├── sub-P001_fmapid-auto00001_desc-magnitude_fieldmap.nii.gz
│   ├── sub-P001_fmapid-auto00001_desc-preproc_fieldmap.json
│   └── sub-P001_fmapid-auto00001_desc-preproc_fieldmap.nii.gz
├── func
│   ├── sub-P001_task-absent_desc-brain_mask.json
│   ├── sub-P001_task-absent_desc-brain_mask.nii.gz
│   ├── sub-P001_task-absent_desc-confounds_timeseries.json
│   ├── sub-P001_task-absent_desc-confounds_timeseries.tsv
│   ├── sub-P001_task-absent_desc-coreg_boldref.json
│   ├── sub-P001_task-absent_desc-coreg_boldref.nii.gz
│   ├── sub-P001_task-absent_desc-hmc_boldref.json
│   ├── sub-P001_task-absent_desc-hmc_boldref.nii.gz
│   ├── sub-P001_task-absent_from-boldref_to-auto00001_mode-image_desc-fmap_xfm.json
│   ├── sub-P001_task-absent_from-boldref_to-auto00001_mode-image_desc-fmap_xfm.txt
│   ├── sub-P001_task-absent_from-boldref_to-T1w_mode-image_desc-coreg_xfm.json
│   ├── sub-P001_task-absent_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt
│   ├── sub-P001_task-absent_from-orig_to-boldref_mode-image_desc-hmc_xfm.json
│   ├── sub-P001_task-absent_from-orig_to-boldref_mode-image_desc-hmc_xfm.txt
│   ├── sub-P001_task-absent_space-MNI152NLin6Asym_res-02_boldref.json
│   ├── sub-P001_task-absent_space-MNI152NLin6Asym_res-02_boldref.nii.gz
│   ├── sub-P001_task-absent_space-MNI152NLin6Asym_res-02_desc-brain_mask.json
│   ├── sub-P001_task-absent_space-MNI152NLin6Asym_res-02_desc-brain_mask.nii.gz
│   ├── sub-P001_task-absent_space-MNI152NLin6Asym_res-02_desc-preproc_bold.json
│   ├── sub-P001_task-absent_space-MNI152NLin6Asym_res-02_desc-preproc_bold.nii.gz
│   ├── sub-P001_task-present_run-02_desc-brain_mask.json
│   ├── sub-P001_task-present_run-02_desc-brain_mask.nii.gz
│   ├── sub-P001_task-present_run-02_desc-confounds_timeseries.json
│   ├── sub-P001_task-present_run-02_desc-confounds_timeseries.tsv
│   ├── sub-P001_task-present_run-02_desc-coreg_boldref.json
│   ├── sub-P001_task-present_run-02_desc-coreg_boldref.nii.gz
│   ├── sub-P001_task-present_run-02_desc-hmc_boldref.json
│   ├── sub-P001_task-present_run-02_desc-hmc_boldref.nii.gz
│   ├── sub-P001_task-present_run-02_from-boldref_to-auto00001_mode-image_desc-fmap_xfm.json
│   ├── sub-P001_task-present_run-02_from-boldref_to-auto00001_mode-image_desc-fmap_xfm.txt
│   ├── sub-P001_task-present_run-02_from-boldref_to-T1w_mode-image_desc-coreg_xfm.json
│   ├── sub-P001_task-present_run-02_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt
│   ├── sub-P001_task-present_run-02_from-orig_to-boldref_mode-image_desc-hmc_xfm.json
│   ├── sub-P001_task-present_run-02_from-orig_to-boldref_mode-image_desc-hmc_xfm.txt
│   ├── sub-P001_task-present_run-02_space-MNI152NLin6Asym_res-02_boldref.json
│   ├── sub-P001_task-present_run-02_space-MNI152NLin6Asym_res-02_boldref.nii.gz
│   ├── sub-P001_task-present_run-02_space-MNI152NLin6Asym_res-02_desc-brain_mask.json
│   ├── sub-P001_task-present_run-02_space-MNI152NLin6Asym_res-02_desc-brain_mask.nii.gz
│   ├── sub-P001_task-present_run-02_space-MNI152NLin6Asym_res-02_desc-preproc_bold.json
│   ├── sub-P001_task-present_run-02_space-MNI152NLin6Asym_res-02_desc-preproc_bold.nii.gz
│   ├── sub-P001_task-rest_desc-brain_mask.json
│   ├── sub-P001_task-rest_desc-brain_mask.nii.gz
│   ├── sub-P001_task-rest_desc-confounds_timeseries.json
│   ├── sub-P001_task-rest_desc-confounds_timeseries.tsv
│   ├── sub-P001_task-rest_desc-coreg_boldref.json
│   ├── sub-P001_task-rest_desc-coreg_boldref.nii.gz
│   ├── sub-P001_task-rest_desc-hmc_boldref.json
│   ├── sub-P001_task-rest_desc-hmc_boldref.nii.gz
│   ├── sub-P001_task-rest_from-boldref_to-auto00001_mode-image_desc-fmap_xfm.json
│   ├── sub-P001_task-rest_from-boldref_to-auto00001_mode-image_desc-fmap_xfm.txt
│   ├── sub-P001_task-rest_from-boldref_to-T1w_mode-image_desc-coreg_xfm.json
│   ├── sub-P001_task-rest_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt
│   ├── sub-P001_task-rest_from-orig_to-boldref_mode-image_desc-hmc_xfm.json
│   ├── sub-P001_task-rest_from-orig_to-boldref_mode-image_desc-hmc_xfm.txt
│   ├── sub-P001_task-rest_space-MNI152NLin6Asym_res-02_boldref.json
│   ├── sub-P001_task-rest_space-MNI152NLin6Asym_res-02_boldref.nii.gz
│   ├── sub-P001_task-rest_space-MNI152NLin6Asym_res-02_desc-brain_mask.json
│   ├── sub-P001_task-rest_space-MNI152NLin6Asym_res-02_desc-brain_mask.nii.gz
│   ├── sub-P001_task-rest_space-MNI152NLin6Asym_res-02_desc-preproc_bold.json
│   └── sub-P001_task-rest_space-MNI152NLin6Asym_res-02_desc-preproc_bold.nii.gz
└── log
    └── 20260529-143556_d5296993-9af9-4e31-8daf-2d00a357cad1
        └── fmriprep.toml

Ah right. I think maybe the problem is that fMRIPost-AROMA is trying to process the run(s) you filtered out in your fMRIPrep run. I suggest running fMRIPost-AROMA with just the fMRIPrep derivatives (i.e., don’t pass in the raw BIDS dataset).

docker run --rm -it \
	-v {$PROJ_DIR}/3_fmripost-aroma:/out \
	-v {$PROJ_DIR}/2_fmriprep:/prep \
	nipreps/fmripost-aroma:main \
	/prep  \
	/out \
	participant \
	--denoising-method nonaggr \
	--participant-label P001

This way, fMRIPost-AROMA will just be trying to process the runs that have fMRIPrep derivatives. An alternative would be to use a bids-filter-file for fMRIPost-AROMA like you did for fMRIPrep, but I think just passing in the fMRIPrep derivatives is easier.

Thank you - this seems to work! After you mentioned, I also tried out specifying the bids-filter-file but got errors regarding t1w as an entity. Running without the raw data specification worked though.

Just out of curiosity, could you perhaps mention why or when both the sourcedata and the fmriprep data would need specified for fmripost-aroma?

At the moment, I don’t believe the raw BIDS data are ever necessary, but there are configurations that we’ll want to support in the future that would require it. For example, if you ran fMRIPrep with MNI152NLin6Asym and res-native, you won’t get the necessary MNI152NLin6Asym 2 mm outputs for ICA-AROMA, and getting the MNI-space outputs to 2 mm would require an extra resampling step, so it would be better to grab the raw data and apply the necessary transforms to get it straight into MNI 2 mm space with a single resampling step.