Some confusion about HCP Pipelines

[Zack Guo]

Dear all,

I am studying HCP Pipelines systematically recently, and I have some confusion about some details of FreeSurfer2CaretConvertAndRegisterNonlinear.sh in PostFreeSurfer.

1. Transform surface files from native space to MNI space：
${CARET7DIR}/wb_command -surface-apply-warpfield "$T1wFolder"/"$NativeFolder"/"$Subject"."$Hemisphere"."$Surface".native.surf.gii "$InverseAtlasTransform".nii.gz
 "$AtlasSpaceFolder"/"$NativeFolder"/"$Subject"."$Hemisphere"."$Surface".native.surf.gii -fnirt "$AtlasTransform".nii.gz

What exactly is this line doing? Is it to transform the coordinate of every vertex in the surface file from native to MNI space (or other more standard description)?

2. Get the sphere surface file registered to the fs_LR 164k space
${CARET7DIR}/wb_command -surface-sphere-project-unproject "$AtlasSpaceFolder"/"$NativeFolder"/"$Subject"."$Hemisphere".sphere.reg.native.surf.gii "$AtlasSpaceFolder"/fsaverage/"$Subject"."$Hemisphere".sphere."$HighResMesh"k_fs_"$Hemisphere".surf.gii "$AtlasSpaceFolder"/fsaverage/"$Subject"."$Hemisphere".def_sphere."$HighResMesh"k_fs_"$Hemisphere".surf.gii "$AtlasSpaceFolder"/"$NativeFolder"/"$Subject"."$Hemisphere".sphere.reg.reg_LR.native.surf.gii

The output file ("$AtlasSpaceFolder"/"$NativeFolder"/"$Subject"."$Hemisphere".sphere.reg.reg_LR.native.surf.gii) is the sphere surface (converted to MNI standard space)  registered to the fs_LR 164 template, right?

3.RegSphere="${AtlasSpaceFolder}/${NativeFolder}/${Subject}.${Hemisphere}.sphere.MSMSulc.native.surf.gii"
What does $RegSphere standard for exactly?


4. The following code:
#Create downsampled fs_LR spec file in structural space.
for Surface in white midthickness pial ; do
    ${CARET7DIR}/wb_command -surface-resample "$T1wFolder"/"$NativeFolder"/"$Subject"."$Hemisphere"."$Surface".native.surf.gii ${RegSphere} "$AtlasSpaceFolder"/fsaverage_LR"$LowResMesh"k/"$Subject"."$Hemisphere".sphere."$LowResMesh"k_fs_LR.surf.gii BARYCENTRIC "$T1wFolder"/fsaverage_LR"$LowResMesh"k/"$Subject"."$Hemisphere"."$Surface"."$LowResMesh"k_fs_LR.surf.gii
    ...
done

I don't fully understand why ${RegSphere} is used for the second parameter in wb_command -surface-resample. What I understand is that ${RegSphere} is in the MNI standard space, not the native space. Is there something wrong with my understanding?  And could you explain it further, please?

Thanks for your reply.

Best,
Zack

[Tim Coalson]

Inline replies.

Tim

On Tue, Oct 10, 2023 at 8:49 AM Zack Guo <zack...@gmail.com> wrote:

Dear all,

I am studying HCP Pipelines systematically recently, and I have some confusion about some details of FreeSurfer2CaretConvertAndRegisterNonlinear.sh in PostFreeSurfer.

1. Transform surface files from native space to MNI space：
${CARET7DIR}/wb_command -surface-apply-warpfield "$T1wFolder"/"$NativeFolder"/"$Subject"."$Hemisphere"."$Surface".native.surf.gii "$InverseAtlasTransform".nii.gz
 "$AtlasSpaceFolder"/"$NativeFolder"/"$Subject"."$Hemisphere"."$Surface".native.surf.gii -fnirt "$AtlasTransform".nii.gz

What exactly is this line doing? Is it to transform the coordinate of every vertex in the surface file from native to MNI space (or other more standard description)?

Yes, it moves the surface vertices so they align with the MNI-warped structural volume.  The result still uses the "native mesh" triangles and vertex count, but is not in "native volume space", those are entirely separate concepts.

 

2. Get the sphere surface file registered to the fs_LR 164k space
${CARET7DIR}/wb_command -surface-sphere-project-unproject "$AtlasSpaceFolder"/"$NativeFolder"/"$Subject"."$Hemisphere".sphere.reg.native.surf.gii "$AtlasSpaceFolder"/fsaverage/"$Subject"."$Hemisphere".sphere."$HighResMesh"k_fs_"$Hemisphere".surf.gii "$AtlasSpaceFolder"/fsaverage/"$Subject"."$Hemisphere".def_sphere."$HighResMesh"k_fs_"$Hemisphere".surf.gii "$AtlasSpaceFolder"/"$NativeFolder"/"$Subject"."$Hemisphere".sphere.reg.reg_LR.native.surf.gii

The output file ("$AtlasSpaceFolder"/"$NativeFolder"/"$Subject"."$Hemisphere".sphere.reg.reg_LR.native.surf.gii) is the sphere surface (converted to MNI standard space)  registered to the fs_LR 164 template, right?

No, spheres don't care about MNI space.  It is generating an original-freesurfer-segmentation-mesh ("native mesh") sphere that is in register with our fs_LR surface template, rather than the freesurfer surface template, by applying a precomputed deformation between the templates to the freesurfer-registered version of the subject's native sphere.

 

3.RegSphere="${AtlasSpaceFolder}/${NativeFolder}/${Subject}.${Hemisphere}.sphere.MSMSulc.native.surf.gii"
What does $RegSphere standard for exactly?

It stands for "registered sphere", and it sets what registration we use for resampling things to fs_LR space.  We strongly recommend MSMSulc, but this variable allows us to support using the freesurfer registration combined with the precomputed deformation (described in the previous question).

 

4. The following code:
#Create downsampled fs_LR spec file in structural space.
for Surface in white midthickness pial ; do
    ${CARET7DIR}/wb_command -surface-resample "$T1wFolder"/"$NativeFolder"/"$Subject"."$Hemisphere"."$Surface".native.surf.gii ${RegSphere} "$AtlasSpaceFolder"/fsaverage_LR"$LowResMesh"k/"$Subject"."$Hemisphere".sphere."$LowResMesh"k_fs_LR.surf.gii BARYCENTRIC "$T1wFolder"/fsaverage_LR"$LowResMesh"k/"$Subject"."$Hemisphere"."$Surface"."$LowResMesh"k_fs_LR.surf.gii
    ...
done

I don't fully understand why ${RegSphere} is used for the second parameter in wb_command -surface-resample. What I understand is that ${RegSphere} is in the MNI standard space, not the native space. Is there something wrong with my understanding?  And could you explain it further, please?

As stated above, surface registrations (and the spheres that represent them) are unrelated to MNI or any other volume space.  The pair of spheres used in these commands set the correspondence between the vertex indices of two different meshes.  If the freesurfer mesh for a specific subject has vertex 1234 in the foveal part of V1, if you take vertex 1234 of the MSMSulc or reg.reg_LR registered native sphere and find the closest vertex to it on a standard fs_LR sphere, that vertex will also be in foveal V1 in the fs_LR template data.  We generate resampled versions of every subject's surface using the template mesh, so that now, say, vertex 5678 is always in the foveal part of V1 in every single subject's 32k_fs_LR surfaces (while in the "native mesh", the fovea was represented by different vertex numbers in every subject).

 

Thanks for your reply.

Best,
Zack

--
You received this message because you are subscribed to the Google Groups "HCP-Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hcp-users+...@humanconnectome.org.
To view this discussion on the web visit https://groups.google.com/a/humanconnectome.org/d/msgid/hcp-users/0cdcd130-6c8f-48c9-9b52-076de93d8549n%40humanconnectome.org.

[Tim Coalson]

Sorry, to clarify, at the point of running PostFreeSurfer, MSMSulc is strongly preferred over freesurfer registration, because MSMSulc causes much less distortion, while achieving slightly better functional alignment.  MSMAll is our recommended final registration, but it requires fMRI data to be processed before it can be computed (and the fMRI processing relies the results from the freesurfer pipelines).

Tim

[Zack Guo]

Hi Tim,

 
Thanks for your very detailed answer!

1. I used wb_command -file-information to verify the number of triangles and vertices of the two files. I also found that the vertex indexes that make up each triangle are the same (verified using Matlab's gifti function).

At the same time, I still have a few basic questions.

2. Where is the "precomputed deformation" you mentioned stored, is there some way to visualize it for better understanding?

3. How should I understand the vertex coordinates in the surface files? Or in other words, can I think that the surface files (pial, white and midthickness) under "$AtlasSpaceFolder", "$AtlasSpaceFolder"/"$NativeFolder", and "$AtlasSpaceFolder"/fsaverage_LR"$LowResMesh"k describe the surface of "$AtlasSpaceFolder"/T1w_restore_brain.nii.gz, while the surface files in "$T1wFolder"/"$NativeFolder", and "$T1wFolder"/fsaverage_LR"$LowResMesh"k describe the surface of "$T1wFolder"/T1w_acpc_dc_restore_brain.nii.gz?

Thanks again.

Best,
Zack

[Tim Coalson]

Inline again.

Tim

On Wed, Oct 11, 2023 at 4:52 AM Zack Guo <zack...@gmail.com> wrote:

Hi Tim,

 
Thanks for your very detailed answer!

1. I used wb_command -file-information to verify the number of triangles and vertices of the two files. I also found that the vertex indexes that make up each triangle are the same (verified using Matlab's gifti function).

At the same time, I still have a few basic questions.

2. Where is the "precomputed deformation" you mentioned stored, is there some way to visualize it for better understanding?

This line copies it from the pipelines repo into the subject's folder:

https://github.com/Washington-University/HCPpipelines/blob/21c0867c7f3a59554b9e28f5fe5cddd41e159170/PostFreeSurfer/scripts/FreeSurfer2CaretConvertAndRegisterNonlinear.sh#L385

So for the left hemisphere, the files used are here:

https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/standard_mesh_atlases/fs_L

It isn't particularly easy to visualize surface registrations, but you can load both of these spheres and a freesurfer fsaverage sulc map (not an fs_LR file, that will probably look garbled), and switch between the spheres to watch the sulc map move.

3. How should I understand the vertex coordinates in the surface files? Or in other words, can I think that the surface files (pial, white and midthickness) under "$AtlasSpaceFolder", "$AtlasSpaceFolder"/"$NativeFolder", and "$AtlasSpaceFolder"/fsaverage_LR"$LowResMesh"k describe the surface of "$AtlasSpaceFolder"/T1w_restore_brain.nii.gz, while the surface files in "$T1wFolder"/"$NativeFolder", and "$T1wFolder"/fsaverage_LR"$LowResMesh"k describe the surface of "$T1wFolder"/T1w_acpc_dc_restore_brain.nii.gz?

Yes, the anatomical surfaces anywhere under MNINonLinear/ use MNI coordinates corresponding to the structural volumes in that folder, while T1w/ uses rigidly-aligned coordinates.

[Zack Guo]

Thanks  a lot for your answer.

I don't fully understand your suggestion of the visualization of surface registration.
I tried to load "$AtlasSpaceFolder"/"$NativeFolder"/"$Subject".L.sphere.reg.native.surf.gii and "$AtlasSpaceFolder"/"$NativeFolder"/"$Subject".L.sphere.reg.reg_LR.native.surf.gii. And I load "$FreeSurferFolder"/surf/lh.sulc (or "$AtlasSpaceFolder"/"$NativeFolder"/"$Subject".L.sulc.native.shape.gii) as an overlay.

Could you please provide more detailed instructions for visualization?

Best,
Zack

[Tim Coalson]

wb_view needs gifti format files, freesurfer's standard formats won't work.  The native-mesh sulc .shape.gii file should work for the spheres you mentioned.  Once the sulc layer is enabled, use the controls at the top to change which sphere surface is being used for display, and the data should shift around in the visualization (because the vertices are at different coordinates).  I'm not as familiar with freeview, so I can't give specific instructions there.

Surface registration may not be doing what you expect (and here, it is merely changing between templates that are mostly just in different orientations).  What do you want to know about the registrations?

Tim

[Zack Guo]

Aha, I just want to have a look.
I used wb_view to load the sphere.reg.reg_LR.native.surf.gii and sphere.reg.native.surf.gii, and load sulc .shape.gii as a overlay.
I toke a screenshot for visualization. Sphere file sphere.reg.reg_LR.native.surf.gii is on the left and the other sphere is on the right. According to your experience, does the image below look reasonable?

[Tim Coalson]

The difference between these spheres is just the precomputed registration between the freesurfer and fs_LR templates, and doesn't change per-subject, so we generally don't look at it.  The difference in rotation is about the amount I would expect, but I don't have an intuitive sense for what direction it should be.  If you wanted to check if the final alignment was good, you should compare the subject's 32k or 164k sulc map to the fs_LR template sulc map (you don't need to load multiple surfaces, they should line up on any surface), which are the refsulc files here:

https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/standard_mesh_atlases

If you downloaded the 32k/164k sulc files from connectomeDB, they probably used MSMSulc for resampling, not the reg.reg_LR sphere.

Tim

[Zack Guo]

Hi Tim,

Thanks again.

According to your kind suggestion, for example I want to check the final alignment of fs_LR 164k, I would load these files below. Could you help me check if there is anything wrong?
Load fs_LR 164k sphere file: "$SurfaceAtlasDIR"/fsaverage."$Hemisphere"_LR.spherical_std."$HighResMesh"k_fs_LR.surf.gii (maybe subject's fs_LR 164k midthickness is OK?).
Load subject's fs_LR 164k sulc map: "$AtlasSpaceFolder"/"$Subject"."$Hemisphere".sulc."$HighResMesh"k_fs_LR.shape.gii
Load fs_LR 164k templeate sulc map: "$SurfaceAtlasDIR"/"$Hemisphere".refsulc."$HighResMesh"k_fs_LR.shape.gii

Best,
Zack

[Tim Coalson]

That should work.  The midthickness is highly folded and that makes it hard to see the data in sulci, we typically use very_inflated or inflated for display purposes.

Tim

[Zack Guo]

Thank you very much, Tim.

Best,

Zack