Weird brain mask from ASLPrep

lei_wei · November 5, 2025, 7:46pm

Summary of what happened:

I tried running ASLPrep on several subjects, but the brain masks it produced were all very strange. In contrast, when I applied BET directly, the results were correct.

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

BIDS=/gs/gsfs0/users/BIDS/HP
OUT=/gs/gsfs0/users/ASL_out
WORK=/gs/gsfs0/users/ASL_work
FS_DIR=/gs/gsfs0/users/BIDS/freesurfer  
FS_LICENSE=/gs/gsfs0/users/BIDS/freesurfer/license.txt
IMG=~/toolbox/aslprep/aslprep-25.1.0.sif
SUB=sub-003
mkdir -p "$OUT" "$WORK"
singularity run --cleanenv \
  -B "$BIDS":/bids:ro \
  -B "$OUT":/out \
  -B "$WORK":/work \
  -B "$FS_DIR":/fsdir \
  -B "$FS_LICENSE":/license.txt \
  "$IMG" \
  /bids /out participant \
  --participant-label "$SUB" \ 
  --nprocs 8 \
  --omp-nthreads 8 \
  --mem 32GB \
  --basil \
  --output-spaces T1w \
  --fs-license-file /license.txt \
  --fs-subjects-dir ${FS_DIR} \
  --fs-no-reconall

Version:

25.1.0

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

Singularity

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

PASTE VALIDATOR OUTPUT HERE

Relevant log outputs (up to 20 lines):

My first asl volume is M0, but second is a dummy scan. I just set the seconde line as noRF

volume_type
m0scan
noRF
label
control
label
control
label
control
label
...

Here is my json file for ASL

{
        "Modality": "MR",
        "MagneticFieldStrength": 3,
        "ImagingFrequency": 123.248,
        "Manufacturer": "Siemens",
        "ManufacturersModelName": "Prisma",
        "BodyPartExamined": "HEAD",
        "PatientPosition": "HFS",
        "SoftwareVersions": "syngo MR E11",
        "MRAcquisitionType": "3D",
        "SeriesDescription": "tgse_pcasl_Multi_Delay_ve11e_3.5iso_default",
        "ProtocolName": "tgse_pcasl_Multi_Delay_ve11e_3.5iso_default",
        "ScanningSequence": "EP",
        "SequenceVariant": "SK",
        "ScanOptions": "FS",
        "SequenceName": "tgse3d1_2268",
        "ImageType": ["ORIGINAL", "PRIMARY", "ASL", "NONE", "ND", "MOSAIC"],
        "NonlinearGradientCorrection": false,
        "SeriesNumber": 10,
        "AcquisitionTime": "15:47:2.145000",
        "AcquisitionNumber": 1,
        "SliceThickness": 3.5,
        "SpacingBetweenSlices": 3.5,
        "SAR": 0.103204,
        "EchoTime": 0.03168,
        "RepetitionTime": 4.35,
        "FlipAngle": 120,
        "RFGap": 0.00036,
        "MeanGzx10": 6,
        "ArterialSpinLabelingType": "PCASL",
        "M0Type": "Included",
        "RepetitionTimePreparation": 4.35,
        "LabelingDuration": 0.7,
        "PostLabelingDelay": 1.8,
        "BackgroundSuppression": true,
        "LabelingEfficiency": 0.85,
        "ArterialSpinLabelingType": "PCASL",
        "AcquisitionVoxelSize": [
                3.5,
                3.5,
                3.5     ],
        "PartialFourier": 1,
        "BaseResolution": 64,
        "ShimSetting": [
                4321,
                -1983,
                5074,
                576,
                72,
                187,
                14,
                35      ],
        "TxRefAmp": 216.302,
        "PhaseResolution": 0.984375,
        "ReceiveCoilName": "HeadNeck_64",
        "ReceiveCoilActiveElements": "HC3-6",
        "PulseSequenceDetails": "%CustomerSeq%\\tgse_pcasl_ve11e",
        "CoilCombinationMethod": "Sum of Squares",
        "ConsistencyInfo": "N4_VE11E_LATEST_20181129",
        "MatrixCoilMode": "SENSE",
        "RepetitionTimePreparation": 4350,
        "PercentPhaseFOV": 100,
        "PercentSampling": 98.4375,
        "EchoTrainLength": 63,
        "PhaseEncodingSteps": 63,
        "AcquisitionMatrixPE": 63,
        "ReconMatrixPE": 64,
        "PixelBandwidth": 3125,
        "DwellTime": 2.5e-06,
        "PhaseEncodingDirection": "j-",
        "ImageOrientationPatientDICOM": [
                1,
                0,
                0,
                0,
                0.999781,
                -0.0209424      ],
        "ImageOrientationText": "Tra>Cor(-1.2)",
        "InPlanePhaseEncodingDirectionDICOM": "COL",
        "ConversionSoftware": "dcm2niix",
        "ConversionSoftwareVersion": "v1.0.20220720"
}

Screenshots / relevant information:

tsalo · November 6, 2025, 3:05pm

This is definitely the most common issue ASLPrep users have. Unfortunately, I haven’t come up with a good solution. If you are able to create your own brain mask in ASL reference space, you can place it in a derivatives dataset and pass that into ASLPrep. ASLPrep’s fit/apply approach should grab the brain mask and use it instead of creating a new (bad) one. If you just replace the mask file in your current ASLPrep derivatives and re-run ASLPrep while passing in those derivatives via the --derivatives parameter, that should work.

lei_wei · November 6, 2025, 7:24pm

Hi
Thanks for your reply.
I replaced sub-002_ses-1_desc-brain_mask.nii.gz in the previous derivatives folder and re-ran ASLPrep pointing --derivatives to that directory. ASLPrep detects the preprocessed T1w and the brain mask but it still generates a new mask during the perfusion workflow.

BIDS=/gs/gsfs0/BIDS/HP
NEWOUT=/gs/gsfs0/ASL_out_rerun
WORK=/gs/gsfs0/BIDS/ASL_work
FS_DIR=/gs/gsfs0/BIDS/freesurfer
FS_LICENSE=/gs/gsfs0/BIDS/freesurfer/license.txt
IMG=~/toolbox/aslprep/aslprep-25.1.0.sif
SUB=002
PREV=/gs/gsfs0/BIDS/ASL_out 

singularity run --cleanenv \
  -B "$BIDS":/bids:ro \
  -B "$NEWOUT":/out \
  -B "$WORK":/work \
  -B "$FS_DIR":/fsdir \
  -B "$FS_LICENSE":/license.txt \
  -B "$PREV":/prevderiv:ro \
  "$IMG" \
  /bids /out participant \
  --participant-label "$SUB" \
  --derivatives /prevderiv \
  --nprocs 8 --omp-nthreads 8 --mem 32 \
  --basil \
  --output-spaces T1w \
  --fs-license-file /license.txt \
  --fs-subjects-dir /fsdir \
  --scorescrub \
  --fs-no-reconall

ASLprep tried to use the preivious derivatives but still generated a new wrong mask

251106-14:05:22,147 nipype.workflow IMPORTANT:
         Building ASLPrep's workflow:
           * BIDS dataset path: /bids.
           * Participant list: ['002'].
           * Run identifier: 20251106-140504_dc6d068d-3ba7-452b-b5cb-f87a4459c330.
           * Output spaces: T1w.
           * Searching for derivatives: {'prevderiv': PosixPath('/prevderiv')}.
           * Pre-run FreeSurfer's SUBJECTS_DIR: /fsdir.
251106-14:05:48,550 nipype.workflow INFO:
         ANAT Found preprocessed T1w - skipping Stage 1
251106-14:05:48,554 nipype.workflow INFO:
         ANAT Found brain mask
251106-14:05:48,557 nipype.workflow INFO:
         ANAT Skipping Stage 2
251106-14:05:48,557 nipype.workflow INFO:
         ANAT Skipping Stage 3
251106-14:05:48,557 nipype.workflow INFO:
         ANAT Found discrete segmentation
251106-14:05:48,557 nipype.workflow INFO:
         ANAT Found tissue probability maps
251106-14:05:48,557 nipype.workflow INFO:
         ANAT Stage 4: Found pre-computed registrations for {'MNI152NLin2009cAsym': {'forward': '/prevderiv/sub-002/ses-1/anat/sub-002_ses-1_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5', 'reverse': '/prevderiv/sub-002/ses-1/anat/sub-002_ses-1_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5'}}
251106-14:05:48,557 nipype.workflow INFO:
         ANAT Skipping Stages 5+
251106-14:06:08,113 nipype.workflow INFO:
         Collected run data for /bids/sub-002/ses-1/perf/sub-002_ses-1_asl.nii.gz:
aslcontext: /bids/sub-002/ses-1/perf/sub-002_aslcontext.tsv
m0scan: null
sbref: null

251106-14:06:08,772 nipype.workflow INFO:
         No single-band-reference found for sub-002_ses-1_asl.nii.gz.
251106-14:06:08,870 nipype.workflow INFO:
         Found HMC aslref - skipping Stage 1
251106-14:06:08,872 nipype.workflow INFO:
         Found motion correction transforms - skipping Stage 2
251106-14:06:08,872 nipype.workflow INFO:
         No fieldmap correction - skipping Stage 3
251106-14:06:08,872 nipype.workflow INFO:
         Found coregistration reference - skipping Stage 4
251106-14:06:08,875 nipype.workflow INFO:
         Found coregistration transform - skipping Stage 5
251106-14:06:12,65 nipype.workflow INFO:
         ASLPrep workflow graph with 228 nodes built successfully.

Is there an additional file I shoud put into the previous folder ?
The mri_synthstrip in freesurfer works fine for my M0 brain extraction, can I just call the function within the container ?

tsalo · November 10, 2025, 8:28pm

That’s unfortunate. @mattcieslak and I will spend Thursday and Friday this week trying to figure out what’s going wrong with the brain masks. Hopefully we’ll be able to push a fix soon after that.

farfa · June 25, 2026, 2:45pm

Hi,

I was wondering if there has been any update on this?

I’m facing the same problem where the mask computed on the perfusion data is cropped for some subjects.

I have tried to follow the above suggestion for using my own mask and re-running ASLPrep, so I replaced the perfusion and T1 masks with my own masks and re-ran ASLPrep docker, but I’m running into a FileNotFoundError.

Happy to share more info if needed, but first I thought to double check here whether it’s possible to use my own mask at all, before further troubleshooting.

Thanks in advance for any help

tsalo · June 25, 2026, 2:58pm

Starting in 26.0.3, ASLPrep calculates CBF across the whole field of view instead of just within the mask. Can you try that version to see if your results improve?

farfa · June 25, 2026, 3:28pm

Thanks so much for the fast response.

I’m actually using the 26.0.3 version (latest docker image). The CBF maps, in both native (sub-_cbf.nii.gz) and T1w (sub-*_space-T1w_cbf.nii.gz) spaces, include the full field of view. However, the BASIL outputs are masked, so they’re affected by the cropped mask.