The fsLR 32k mesh files produced by XCP-D do not match the description in document

[zhitao-guo]

Summary

The actual generated fsLR 32k mesh files do not match the description in document.

Additional details

• xcp_d version: 0.9.1
• Docker version: 27.2.0
• Apptainer version: None

What did you expect to happen?

https://xcp-d.readthedocs.io/en/0.9.1/outputs.html#surface-mesh-files As the document says, "The resulting mesh files will reflect the subject’s morphology with the same geometry and density as fsLR-32k surfaces, which may be useful for visualizing fsLR-space derivatives on a subject’s brain."

What actually happened?

I used the wb_view tool to check the alignment of the generated mesh files and volume files, founding that the results does not match the description in document.

In fact, the mesh files under anat folder reflect the morphology of the brain which has been registered to MNI space.

I also overlaied the resampled mesh files from /work_dir/xcp_d_0_9_wf/sub_100307_wf/postprocess_surfaces_wf/warp_surfaces_to_template_wf/{l, r}rh_apply_transforms_wf/resample_to_fsLR32k/mapflow/_resample_to_fsLR32k{0, 1} on the native T1w volume, and they aligned well.

So, I think the second image fits this description in the xcp-d document better. BTW, could you please consider saving the resampled native fsLR 32k mesh files in the anat folder as well? I think these files are useful personally.

Reproducing the bug

docker run --name "xcpd_${subject_id}" \
-v $input_data_dir:/fmri_dir:ro \
-v $results_dir:/output \
-v $freesurfer_license_dir/license.txt:/opt/freesurfer_license/license.txt:ro \
-v $work_dir:/work_dir \
pennlinc/xcp_d:${xcpd_version} /fmri_dir /output participant \
--mode none \
--participant-label ${subject_id} \
--input-type fmriprep \
--file-format cifti \
--dummy-scans 0 \
--despike y \
--nuisance-regressors 36P \
--smoothing 6 \
--combine-runs n \
--motion-filter-type none \
--head-radius 50 \
--fd-thresh 0.5 \
--min-time -1 \
--output-type interpolated \
--lower-bpf 0.01 \
--upper-bpf 0.08 \
--bpf-order 2 \
--skip-parcellation \
--warp-surfaces-native2std y \
--fs-license-file /opt/freesurfer_license/license.txt \
--nthreads $nthreads \
--stop-on-first-crash \
--work-dir /work_dir \
--resource-monitor \
--write-graph \
--abcc-qc y \
--linc-qc y \
--debug all -vvv

[madisoth]

If sticking to the BIDS specification's description, space-fsLR implies MNI152NLin6Asym as the volume space:

https://bids-specification.readthedocs.io/en/stable/appendices/coordinate-systems.html#standard-template-identifiers

The fsLR is a dual template providing both volumetric and surface coordinates references. The volumetric template corresponds to MNI152NLin6Asym.

I do think it would be helpful for the documentation to note this point though, especially since space-fsLR in BIDS is not 100% interchangeable with HCP's use of "fs_LR" (AFAIK the latter doesn't define a volume space, and HCPPipelines output an fsaverage_LR32k subdirectory in both T1w and MNINonLinear).

[tsalo]

The resulting mesh files will reflect the subject’s morphology with the same geometry and density as fsLR-32k surfaces, which may be useful for visualizing fsLR-space derivatives on a subject’s brain.

Yes, in the surface. Look at the surface ReHo or ALFF images in the HTML report, for example.

The anatomical workflow includes steps to warp the mesh files to MNI152NLin6Asym so that the pial and white matter segmentations can be overlaid on the MNI152NLin6Asym template. That's what the brainsprite in the executive summary is. It's a largely unmodified copy of the DCAN team's anatomical workflow, so I don't know a ton about it.

If the documentation can be updated to make that clearer, I'm happy to change it. Please let me know what changes you'd like to see.

[zhitao-guo]

https://bids-specification.readthedocs.io/en/stable/appendices/coordinate-systems.html#standard-template-identifiers The fsLR is a dual template providing both volumetric and surface coordinates references. The volumetric template corresponds to MNI152NLin6Asym.

Thank you for your careful and thoughtful clarification.

[zhitao-guo]

If the documentation can be updated to make that clearer, I'm happy to change it. Please let me know what changes you'd like to see.

Thanks for your feedback.

Regarding how to update the documentation, from my personal perspective, the key point is to ensure that readers can distinguish which volume the fsLR meshes reflect, whether it's native or MNI152NLin6Asym. And I believe it will require some additional time to carefully consider and refine the formal wording for the documentation.

[cindyhfls]

I can't say it for sure but you might want to check with the DCAN people whether this is still the case for the data using an infant/age-specific template. I recognize that the white matter mask in the DCAN-output for babies does not align with the standard output mask provided in the xcp-d (like not at all, because the size differed). (I would have copied the subject T1 overlayed with mask here but I don't know if that would violate the data use policy).