ASLPrep not recognizing flipped M0s or fieldmaps

Software Support
,
1

Hi everyone,
I am using aslprep version 26.0 to preprocess pCASL data (Siemens) and am having a bit of trouble. The program does not seem to recognize the fieldmaps.

Here is the command I used. Directories are blanked out for privacy reasons.

docker run -ti --rm -m 20GB  \
 -v $HOME/freesurfer/license.txt:/license.txt  \
 -v         :/data:ro  \
 -v         /aslprep-out:/out:rw   \
-v     /aslprep-work:/work   \
pennlinc/aslprep:latest   \
/data /out participant \
--skip-bids-validation \
--participant-label KK01  \
--fs-license-file /license.txt  \
-w /work \
--force syn-sdc \
--disable-n4 \
--scorescrub \
--basil

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

I am running this in a docker container.

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

I uploaded the subject’s folder to the bids validator.

under the “invalid_location” tab it contains several repeats of this example below:
/ses-XX/fmap/sub-KK01_ses-XX_acq-btoadvTGSE2p5iso2x2s1MZerooPE_m0scan.nii.gz (Expected location: /sub-KK01/ses-XX/)

under the “intended_for”, again several repeats of this (the error was that the path had to be subject relative and not session relative; but ASLprep only worked for me when I used the session relative paths)
/ses-XX/perf/sub-KK01_ses-XX_m0scan.nii.gz

The ‘not_included’ tab contained the data that I specified bids to ignore (in the bidsmap)

Relevant log outputs (up to 20 lines): I have attached a screenshot below

TERMINAL_OUTPUT
TERMINAL_OUTPUT1920×693 94.1 KB

Screenshots / relevant information:

We use one m0 and one flipped m0 scan for both runs, per session.
I also double-checked that within the dataset_description.json file, DatasetType was set to ‘raw’.

For each subject, there is a /perf and /fmap folder. I can send screenshots of the fmap folder. (We also collect rsfMRI.) For more context, I previously had the MzerooPE_epi in the fMAP folder on its own, but since ASLprep did not seem to recognize this, I ran bidscoin again to obtain the AP and PA sbref files from the fMRI.

For the flipped M0 metadata (.json in the fmap folder), the ‘Intendedfor’ field points to the M0 in the perf folder

I would greatly appreciate any help on this. I can attach any missing screenshots.

2

Hi @kiwi-del and welcome to neurostars!

In the future, please provide text instead of screenshots for terminal code.

Does the m0 scan and fieldmaps have IntendedFor defined?

You are supposed to upload the root of the BIDS dataset to the validator. It would help to provide errors exactly as they were output by the BIDS validator.

Best,
Steven

3

Hi Steven, thank you for your quick reply.

This time, I uploaded the bidsfolder and I received the same errors in the “intended_for “and “invalid_location” tabs.

The opposite phase-encoded m0 scan has the following defined in IntendedFor: ses-XX/perf/sub-KK01_ses-XX_m0scan.nii.gz

If it’s relevant, the regular m0 scan (in the /perf folder) has the following defined in the IntendedFor: ses-XX/perf/sub-KK01_ses-XX_run-1_asl.nii.gz, ses-XX/perf/sub-KK01_ses-XX_run-2_asl.nii.gz

Regarding the fieldmaps, the PA and AP have the following defined in the IntendedFor: ses-01/perf/sub-01_ses-01_run-1_asl.nii.gz, ses-01/perf/sub-01_ses-01_run-2_asl.nii.gz, ses-01/perf/sub-01_ses-01_m0scan.nii.gz

4

Hi @kiwi-del,

May you please provide the tree outputs of the bids directory and example subject? Please format your text as code by using tickmarks / the </> button in the text editor. You can see I have made these edits for you on your previous posts.

And what are the exact outputs from the BIDS validator?

Are there any B0FieldSource/B0FieldIdentifier fields in the jsons?

It appears you accidentally intended the m0 scan for itself instead of the ASL file.

Best,
Steven

5

Hi Steven,
Here are the tree outputs of the bids directory and the Sample subject.
Bids directory

code
sub-KK01
sub-KKXX
sub-KKXX
sub-KKXX
dataset_description.json
license.txt
participants.json
participants.tsv
README

Example subject

ses-XX
ses-XX
     fmap
        sub-KK01_ses-XX_acq-APSBRefe1_run-1_epi.json
        sub-KK01_ses-XX_acq-APSBRefe1_run-1_nii.gz
        sub-KK01_ses-XX_acq-APSBRefe1_run-2_epi.json
        sub-KK01_ses-XX_acq-APSBRefe1_run-2_nii.gz
        sub-KK01_ses-XX_acq-APSBRefe1_run-3_epi.json
        sub-KK01_ses-XX_acq-APSBRefe1_run-3_nii.gz
        sub-KK01_ses-XX_acq-MZerooPE_m0scan.json
        sub-KK01_ses-XX_acq-PASBRefe1_run-1_epi.json
        sub-KK01_ses-XX_acqPASBRefe1_run-1_nii.gz
        sub-KK01_ses-XX_acq-PASBRefe1_run-2_epi.json
        sub-KK01_ses-XX_acq-PASBRefe1_run-2_nii.gz
        sub-KK01_ses-XX_acq-PASBRefe1_run-3_epi.json
        sub-KK01_ses-XX_acq-PASBRefe1_run-3_nii.gz
     perf
        sub-KK01_ses-XX_m0scan.json
        sub-KK01_ses-XX_m0scan.nii.gz
        sub-KK01_ses-XX_run-1_asl.json
        sub-KK01_ses-XX_run-1_asl.nii.gz
        sub-KK01_ses-XX_run-1_aslcontext.tsv
        sub-KK01_ses-XX_run-2_asl.json
        sub-KK01_ses-XX_run-2_asl.nii.gz
        sub-KK01_ses-XX_run-2_aslcontext.tsv
   sub-KK01_ses-XX_scans.tsv
ses-XX
ses-anatomical

For the B0FieldIdentifiers, they were blank, so I assigned values to them. I’m unsure if this is the correct way to do this.

The B0FieldIdentifier for all AP fmaps is: phasediff_fmap0
The B0FieldIdentifier for all PA fmaps is: fmap0
The B0FieldIdentifier for the flipped m0 scan is: B0

There are no B0FieldIdentifier metadata for the files in the /perf folder.

As for the outputs from the BIDS validator…

ERROR: INTENDED_FOR
 'IntendedFor' field needs to point to an existing file. Files must be subject-relative paths or BIDS URIs.
   /sub-KKXX/ses-XX/perf/sub-KKXX_ses-XX_run-2_asl.nii.gz
    /sub-KKXX/ses-XX/perf/sub-KKXX_ses-XX_run-1_asl.nii.gz
    /sub-KK01/ses-XX/perf/sub-KK01_ses-XX_run-1_asl.nii.gz

ASLprep works fine otherwise, I just cannot seem to get it to recognize the field maps.
Thank you,
kiwi-del

6

Hi @kiwi-del,

This shouldn’t be in your BIDS root directory.

Looks like you defined these relative to BIDS root instead of subject folder. Please remove /sub-KKXX/ from them.

This would not be correct. Let’s just try to do IntendedFor for now and remove any B0Field* metadata from your jsons (otherwise IntendedFor may not work).

Your file naming is not correct. As you can see here (Magnetic Resonance Imaging - Brain Imaging Data Structure 1.11.1) the dir-<> entity, e.g. dir-PA or dir-AP are required for PEPOLAR style fieldmaps. And their file suffix should be epi.nii.gz. It looks like you do not have a suffix. I would rename them sub-X_ses-X_acq-SBRef_dir-[AP or PA]_run-X_epi.[nii.gz or json]. What version of the BIDS validator are you using? I am surprised these didn’t raised as an error.

Can you describe your desired fmap pairing? As to what files you want to correct which images? I notice you have 3 reverse phase-encoded pairs, and only two ASL files. Trying to pair more than one RPE pair to ASL will cause errors.

Best,
Steven

7

Hi Steven,

I am using BIDS validator version 2.4.1.

For the fmap pairing, I wanted to use the flipped M0 scans to correct for distortion in the _asl files. I only introduced the FMAP scans when I saw that ASLprep was not recognizing the M0. I am unsure if it would help to include our echo imaging (include a /func folder) as ASLprep only preprocesses ASL data from my understanding.

I removed the B0FieldIdentifier maps and fixed the IntendedFor fields. I also renamed the _epi scans as you’ve suggested.
Here is a snippet of the /fmap folder

sub-KK01_ses-XX_acq-SBREFe1_dir-AP_run-1_epi.json
sub-KK01_ses-XX_acq-SBREFe1_dir-AP_run-1_epi.nii.gz
sub-KK01_ses-XX_acq-SBREFe2_dir-PA_run-1_epi.json
sub-KK01_ses-XX_acq-SBREFe2_dir-PA_run-1_epi.nii.gz
sub-KK01_ses-XX_acq-btoadvTGSE2p5iso2x2s1MZerooPE_dir-AP_m0scan.json
sub-KK01_ses-XX_acq-btoadvTGSE2p5iso2x2s1MZerooPE_dir-AP_m0scan.nii.gz

I re-ran everything with the new naming and I saw this in the terminal.

100%|████████████████████████████████████████| 205M/205M [01:17<00:00, 2.65MB/s]
260313-10:33:38,118 nipype.workflow WARNING:
	 More than one M0 file found for /data/sub-KK01/ses-XX/perf/sub-KK01_ses-XX_run-2_asl.nii.gz. Using the first one (/data/sub-KK01/ses-XX/fmap/sub-KK01_ses-XX_acq-btoadvTGSE2p5iso2x2s1MZerooPE_dir-AP_m0scan.nii.gz)
260313-10:33:38,120 nipype.workflow INFO:
	 Collected run data for /data/sub-KK01/ses-XX/perf/sub-KK01_ses-XX_run-2_asl.nii.gz:
aslcontext: /data/sub-KK01/ses-XX/perf/sub-KK01_ses-XX_run-2_aslcontext.tsv
m0scan: /data/sub-KK01/ses-XXfmap/sub-KK01_ses-XX_acq-btoadvTGSE2p5iso2x2s1MZerooPE_dir-AP_m0scan.nii.gz
sbref: null

260313-10:33:38,520 nipype.workflow INFO:
	 No single-band-reference found for sub-KK01_ses-XX_run-2_asl.nii.gz.
260313-10:33:38,594 nipype.workflow INFO:
	 Stage 1: Adding HMC aslref workflow
260313-10:33:38,599 nipype.workflow INFO:
	 Stage 2: Adding motion correction workflow
260313-10:33:38,602 nipype.workflow INFO:
	 Stage 2b: Adding M0 scan registration workflow
260313-10:33:38,604 nipype.workflow INFO:
	 No fieldmap correction - skipping Stage 3
260313-10:33:38,604 nipype.workflow INFO:
	 Stage 4: Adding coregistration aslref workflow

Is there anything that I should re-run?

Thanks,
Kiwi-del

8

Hi @kiwi-del,

These shouldn’t be in fmap folder either, they are an ASL file and should be in /perf. Also, m0 scans are to my knowledge only used for calibration, not distortion correction.

This is also problematic - I would imagine you want the same phase encoded M0 to be used for calibration, not the RPE one you put in fmap.

I am sorry but I am confused by this question. Everything should be in the BIDS root folder, regardless of if ASLPrep uses it or not. ASLPrep will use perf and fmap data.

Can you share the contents of your fmap jsons and also the full output from the BIDS validator?

Best,
Steven

9

Hi Steven, thank you for your reply.
I moved the flipped M0s to the /perf folder.
The question I asked was completely naive [I am mostly unfamiliar with aslprep and fmriprep]. When I was referring to the aslprep example BIDS tree Quick Start Tutorial — aslprep version documentation the example only contained the /anat and /perf folders. So I was unsure if aslprep would crash if I included anything other than the contents of the /fmap and aforementioned folders.

I ended up filling the B0FieldIdentifier fields with the dicomtag<session-id>_pepolar in the fmap.json files.

I referenced these B0FieldIdentifier fields in the _asl.json metadata in the B0FieldSource.

aslprep seems to be recognizing these now… but I have a couple of questions

I don’t know if it’s normal for the field maps to look like this.

fmap_with_epi
fmap_with_epi1920×962 155 KB

here is the command I used
ASLPrep command: /app/.pixi/envs/aslprep/bin/aslprep /data /out participant --skip-bids-validation --participant-label KK01 --fs-license-file /license.txt -w /work --force syn-sdc --disable-n4 --scorescrub --basil --use-syn-sdc --stop-on-first-crash

In any case, I tested the --use syn-sdc argument on another participant. I re-ran bidscoiner for the participant I used this command (below) on. There was no /fmap folder. I also filled the B0FieldIdentifier field for the m0.json using a dicomtag<<session_ID>>_m0. The B0FieldSource fields for the _asl.json files referenced this.

fmap_experimental_SDC
fmap_experimental_SDC1920×891 160 KB

ASLPrep command: /app/.pixi/envs/aslprep/bin/aslprep /data /out participant --skip-bids-validation --participant-label KKXX --fs-license-file /license.txt -w /work --disable-n4 --ignore fieldmaps --scorescrub --use-syn-sdc --stop-on-first-crash

I checked the values of the quality control metrics that I had prior to using the sdc arguments. After having attempted the fieldmaps, I can say that some of the values under the quality control metrics have become questionable.

Thank you again,
kiwi-del

10

Hi @kiwi-del,

Do you have multiple AP/PA pairs of fmaps, as alluded to in previous posts? If so, wouldn’t this scheme give both pairs the same identifier, since they were acquired with the same session ID? Or if the dicomtag is different for each image, then each fmap component image would have its own identifier, which also isn’t right. The two images in the pair (that is, the AP and PA image) would each have the same identifier, which is then referred to as the source in the ASL json you want to have the resulting fmap correct.

That can be normal, but it would be better to check the SDC results in the HTML itself. If SDC was performed then you should see a dedicated component in the HTML report for it, with a before/after GIF. If the resulting correction makes the image more “brain-like” and without geometric “smears/smudges” towards problematic areas (typically frontal and temporal), then that’s usually a success.

Unless your fmaps are bad / result in bad correction, I would avoid this. In any case you want to make sure the nature of the correction is reasonable like I described above. The fmap Hz image alone won’t give you that information.

Best,
Steven