Beauchamp:UseCortSurfMod

Finishing the Surface Model

The @finish script assumes that the cortical surface model has already been constructed, see Creating Cortical Surface Models

To finish the surface model, first change to the AFNI directory, e.g.

 cd /Volumes/data1/UT/DB/afni

And then run the @finish script. The name of the anatomy which the surface will be registered to (probably the same anatomy used in the @prep_dir script).

 /Volumes/data1/scripts/@finish DBanatavg+orig

The anatomyfile will be registered to the surface in the fs/SUMA directory. A common reason for this script to fail is that you do not have permissions for the AFNI or surfaces directory (fix this with chmod).

Automation

The first three steps below are contained in the script file /Volumes/data/scripts/@finish. The other steps are mainly obsolete but are included here for educational value.

Converting Freesurfer surfaces to SUMA Files

After creating the surface in FreeSurfer, the files must be converted to a format readable by SUMA. From the surface directory folder (e.g. /Volumes/data/UT/NA/fs) run the following

 @SUMA_Make_Spec_FS -GIFTI -sid fs

This copies files for the surfaces into a new folder called SUMA and converts them into AFNI/SUMA format. If a SUMA directory already exists, it is safest to delete the SUMA folder and other associated files before running this command and the others below, i.e.

  rm -rf SUMA
 @SUMA_Make_Spec_FS -GIFTI -sid fs
 cd ../afni
 rm *Alnd* *aparc*
 rm NAanatavg_shft.1D
 @SUMA_AlignToExperiment -align_centers  -exp_anat NAanatavg+orig -surf_anat ../fs/SUMA/fs_SurfVol.nii -prefix fs_SurfVol_Alnd_Exp

Align subject to experiment

This command aligns the Surface Volume with the Experiment Anatomy, so that the surface and the functional data are in register. The "followers" option applies the same transformation to other datasets, such as anatomical parcellation. For instance,

 @SUMA_AlignToExperiment -align_centers  -exp_anat $1 -surf_anat ../fs/SUMA/fs_SurfVol+orig -prefix fs_SurfVol_Alnd_Exp -surf_anat_followers ../fs/SUMA/aparc.a2009s+aseg_rank.nii

If @SUMA_AlignToExperiment has already been run, 3dAllineate can be used to apply the same transformation (equivalent to surf_anat_followers) with the 1D file written out by @SUMA, called something like

 IE_SurfVol_Alnd_Exp.A2E.1D

like this:

 3dAllineate -master IEanatavg+orig -1Dmatrix_apply IE_SurfVol_Alnd_Exp.A2E.1D -input aparc.a2009s+aseg_rank.nii -prefix ./aparc.a2009s+aseg_rank_Alnd_Exp -final NN

It may also be necessary to manually do a few other steps that are in the new @finish script:

 3drefit -labeltable ./aparc.a2009s+aseg_rank.niml.lt  aparc.a2009s.rank_axialized+orig
 3drefit -labeltable ./aparc.a2009s+aseg_rank.niml.lt  aparc.a2009s+aseg_rank_Alnd_Exp+orig

The @finish script makes an @ec script file that points to the appropriate directory to automate loading SUMA and AFNI:

OBSOLETE (Ziad has fixed this) The purpose of @SUMA_AlignToExperiment is to align the original anatomy and the modified FreeSurfer version of the anatomy used to make the surface. If this fails, wildly wrong results can occur when attempting to use the surface for analysis and visualization. Therefore, it is critical to load the original and SurfVol_Alnd_Exp anatomy in AFNI and make sure that they are aligned. If they do not match, then the anatomies must re-aligned. A typical problem is that FreeSurfer adds a great deal of empty space around the anatomy and centers it causing the alignment process to fail because the SurfVol and the ExpAnat are too different. This can be remedied by using the "wd" option

 @SUMA_AlignToExperiment -wd 

Ziad suggests using the @Align_Centers program to shift the ExpAnat so that it is in register with the SurfVol

 @Align_Centers -base SurfVol -dset ExpAnat -child AllFuncDsets

By default, this creates new copies of all datasets. Alternately, the "no_cp" option can be used.

Create an "@" file

A handy script is useful to automatically load AFNI and SUMA. This command puts one in the current directory and can be started by typing @ec

 cp /Volumes/data/scripts/@ec ./

FreeSurfer Parcellation Data

The @finish script automatically creates an AFNI BRIK with the FreeSurfer 2009 parcellation data,

 aparc.a2009s+aseg_rank.nii

The color scale automatically changes if this BRIK is chosen as an overlay. The anatomical region under the crosshairs is shown in the bottom right of the AFNI window. To see the correspondence between labels and numbers, type

 cat ../fs/SUMA/aparc.a2009s+aseg_rank.niml.lt

OBSOLETE: Creating Partially Inflated Surfaces

@SUMA_Make_Spec_FS now automatically creates partially inflated surfaces so everything in this step is no longer needed. Partially inflated surfaces are good because they allow the viewer to see the cortex buried in sulci while preserving the major anatomical landmarks. SurfSmooth will begin inflate a surface for a given number of iterations. Use the following two lines to create partially inflated surfaces.

SurfSmooth -spec {$ec}_lh.spec -surf_A lh.smoothwm.asc -met NN_geom -surf_out lh.smoothwm.SS500.ply -Niter 500 -match_area 0.01
SurfSmooth -spec {$ec}_rh.spec -surf_A rh.smoothwm.asc -met NN_geom -surf_out rh.smoothwm.SS500.ply -Niter 500 -match_area 0.01

These commands take FreeSurfer .asc files as input and writes out Suma .ply files as output. For Suma to load these files correctly, the spec file must be modified to read SurfaceType = Ply. If you are curious, It is easy to make movies to show the inflation process, see Beauchamp:InflationMovies.

If new surfaces are created, they must be added to the .spec files so that they are loaded when SUMA is as SPEC files are text files which tells SUMA which surfaces to load. In the previous step, new surfaces were created so these must be added to the SPEC file. It is convenient to create a single SPEC file with both left and right hemispheres. The easiest way is to copy a previously made SPEC file or a text editor can be used to combine the lh.spec and rh.spec files, and to add the following

NewSurface
       SurfaceFormat = ASCII
       SurfaceType = FreeSurfer
       FreeSurferSurface = lh.smoothwm.SS500.asc
       LocalDomainParent = lh.smoothwm.asc
       SurfaceState = SS500
       EmbedDimension = 3
       Anatomical = N

NewSurface
       SurfaceFormat = ASCII
       SurfaceType = FreeSurfer
       FreeSurferSurface = rh.smoothwm.SS500.asc
       LocalDomainParent = rh.smoothwm.asc
       SurfaceState = SS500
       EmbedDimension = 3
       Anatomical = N

OBSOLETE: Converting Sulc (Cortical Surface Curvature) Files for use in SUMA

Use sulc files for background in SUMA instead of the default SUMA background to better show the anatomy. First, create them with these commands:

 mris_convert -c ../surf/lh.sulc ../surf/lh.smoothwm lh.sulc.asc
 mris_convert -c ../surf/rh.sulc ../surf/rh.smoothwm rh.sulc.asc

Then, the files can be loaded into SUMA using the Load Dataset button or with the following command line

 DriveSuma -com surf_cont -load_dset /Volumes/data1/UT/{$ec}/{$ec}.lh.sulc.asc \
 -I_sb 4 -surf_label lh.smoothwm.asc  -view_surf_cont y -load_cmap ~/nice.1D.cmap -Dim 0.6

 DriveSuma -com surf_cont -load_dset /Volumes/data1/UT/{$ec}/{$ec}.rh.sulc.asc  \
 -I_sb 4 -surf_label rh.smoothwm.asc -view_surf_cont y -switch_cmap nice.1D -Dim 0.6

 DriveSuma -com viewer_cont -key b

This will show global depth, instead of local curvature (the default), as the SUMA anatomical background.

Importing Cortical Parcellation Data from FreeSurfer

FreeSurfer automatically determines ROIs based on two of its atlas brains. The following lines can be run to create 1D roi’s that can be overlayed on the surface in SUMA. This will look nicer than viewing the parcellation data on the surface after it has been converted to the volume.

FSread_annot -input ../label/rh.aparc.a2005s.annot -col_1D rh.aparc.a2005s.1D.col -roi_1D rh.aparc.a2005s.1D.roi
FSread_annot -input ../label/lh.aparc.a2005s.annot -col_1D lh.aparc.a2005s.1D.col -roi_1D lh.aparc.a2005s.1D.roi
FSread_annot -input ../label/rh.aparc.annot -col_1D rh.aparc.1D.col -roi_1D rh.aparc.1D.roi
FSread_annot -input ../label/lh.aparc.annot -col_1D lh.aparc.1D.col -roi_1D lh.aparc.1D.roi

Usually we only use the ROI files, so this can be simplified to

FSread_annot -input ../label/rh.aparc.a2005s.annot -roi_1D rh.aparc.a2005s.1D.roi
FSread_annot -input ../label/lh.aparc.a2005s.annot  -roi_1D lh.aparc.a2005s.1D.roi

To find out which number corresponds to which anatomical structure, we use the command

 FSread_annot -show_FScmap -input ../label/rh.aparc.a2005s.annot

The output of this is here FreeSurferParcellation

There is also a spread sheet showing the numbering scheme relative to the actual ROI name. This can be found on /Volumes/data9/surfaces/FS_aparc.xls

Viewing FreeSurfer Parcellation Data in SUMA

The 1D files produced in the previous step can be loaded into SUMA. To do this manually, right click on the hemisphere of interest and open the surface viewer for that hemisphere. Then click "Load Dataset" and enter the parcellation file for that hemisphere. The parcellation file is different for each hemisphere, so separate surface controllers must be opened for left and right hemispheres and the correct parcellation files loaded into each one. In the Dset mapping part of the surface controller window, select sub-BRIK #1 for the Intensity (color scale). This display the second column of the parcellation file (since AFNI starts counting at 0) which contains the parcellation information. Otherwise you will simply display the first column of the parcellation file, which is the node number and is not informative. The color scale and threshold can be adjusted in SUMA in order to make a pretty picture. Select the ROI128 or ROI256 colormaps to give each parcellated region a different color. The FreeSurfer colormap may also give good results.

These steps can be automated using the DriveSuma program; for instance

 DriveSuma -com surf_cont -load_dset /Volumes/data9/surfaces/jagar_ashley/AZ/SUMA/AZrh.aparc.a2005s.1D.dset \
  -I_sb 1 -surf_label rh.smoothwm.asc  -view_surf_cont y 

Right clicking on a node will move the SUMA crosshairs to that node. The surface controller window will then tell you the Value at that node (next to "Val", under "Intens") which can be compared with the parcellation file (above) to learn the identity of that node.

For finer control, the 1deval program can be used (in combination with the spreadsheet above) to create a dataset file that will display only certain ROIs. For instance, spreadsheet says that STS is ROI #80.

 1deval -index AZrh.aparc.a2005s.1D.dset'[0]' -b AZrh.aparc.a2005s.1D.dset'[1]' \
 -expr "equals(b,80)" > AZrh.aparc.a2005s.onlySTS.1D.dset

Produces a new dataset where only STS nodes have a non-zero value.

Converting Surface Parcellation Data for use in AFNI

Use the Surf2Vol command to take the parcellation data and put it in the volume. Then it can be used, for instance, to calculate average time series. Note that the output has 4 sub-BRIKS (values) for each voxel. Only the 0th sub-BRIK contains the parcellation information; also these values are floats (which they do not need to be) so we convert them to shorts. Also see the next step for an alternative way of doing this.

 3dSurf2Vol -spec {$d}/both.spec -surf_A {$d}/rh.smoothwm.asc -surf_B {$d}/rh.pial -sv {$ec}_SurfVol_Alnd_Exp+orig. -grid_parent {$ec}EPIanatAlbl+orig\
-sdata_1D {$d}/rh.aparc.a2005s.1D.roi -map_func max -f_steps 15 -prefix {$ec}_rh_all_Surf2Vol_ROI
 3dSurf2Vol -spec {$d}/both.spec -surf_A {$d}/lh.smoothwm.asc -surf_B {$d}/lh.pial -sv {$ec}_SurfVol_Alnd_Exp+orig. -grid_parent {$ec}EPIanatAlbl+orig\
-sdata_1D {$d}/lh.aparc.a2005s.1D.roi -map_func max -f_steps 15 -prefix {$ec}_lh_all_Surf2Vol_ROI
 3dcalc -datum short -prefix {$ec}_aparc -a0 {$ec}_rh_all_Surf2Vol_ROI+orig -b0 {$ec}_lh_all_Surf2Vol_ROI+orig -expr "max(a,b)"

Converting Volume Parcellation Data for use in AFNI

FreeSurfer itself creates a volume dataset that contains parcellation information. Therefore, instead of the previous step, it is also possible to use the existing volume parcellation information. This is what is done by the @finish script.

 @SUMA_AlignToExperiment -exp_anat {$ec}anatavg+orig -surf_anat {$ec}_SurfVol+orig -prefix {$ec}_SurfVol_Alnd_Exp \

-surf_anat_followers brainmask.auto.nii aseg.auto.nii aseg.nii aparc.a2005s+aseg.nii aparc+aseg.nii

After @SUMA_AlignToExperiment aligns the SurfVol to the experiment anatomy, it applies the same transformation to the FreeSurfer parcellation BRIKs. Therefore, they should be in perfect alignment with the experiment anatomy. Because the FreeSurfer parcellation BRIKs have the same name for each subject, @finish renames them as follows for clarity:

 3drename aparc.a2005s+aseg.nii_Alnd_Exp+orig {$ec}_FS_aparc.a2005s_Alnd_Exp
 3drename aparc+aseg.nii_Alnd_Exp+orig {$ec}_FS_aparc_Alnd_Exp
 3drename brainmask.auto.nii_Alnd_Exp+orig.HEAD {$ec}_FS_brainmask.auto.nii_Alnd_Exp
 3drename aseg.nii_Alnd_Exp+orig.HEAD {$ec}_FS_aseg.nii_Alnd_Exp
 3drename aseg.auto.nii_Alnd_Exp+orig.HEAD {$ec}_FS_aseg.auto.nii_Alnd_Exp

Finally, @finish copies the files to the experiment directory

 foreach ds (*Alnd_Exp*HEAD)
 set ds2 = `echo $ds | cut -d "+" -f 1 -`
 echo copying FreeSurfer file {$ds2} to experiment directory
 3dcopy {$ds2}+orig {$p}/{$ds2}
 end

The way that @SUMA_AlignToExperiment aligns the files can be seen in the @Align_Centers script:

 @Align_Centers -base  EB_SurfVol+orig -dset aparc.a2005s.nii -no_cp

Using Volume Parcellation Data in AFNI

The numbering scheme for the volume parcellation BRIK is slightly different than the surface ROIs decribed above. In the file

 DY_FS_aparc.a2005s_Alnd_Exp+orig

Voxels in the right STS have value 2180 Voxels in the left STS have value 1180

Using FreeSurfer Volume Parcellation as Masks in AFNI and DTI Query

The FreeSurfer parcellations will have the same voxel dimensions as the surface volume. To use them as masks for DTI or fMRI analysis, they must be converted to the same resolution as the DTI or fMRI data. This is done above with the 3dSurf2Vol command, but it can also be done with 3dWarp. Tim has written a script to do this automatically, in

 /Volumes/data9/surfaces/scripts/@prep_aseg4afni

Resampling Parcellation

Because EPI data is lower resolution than atlases, resampling must be used. It is easier to resample the atlas to the lower resolution than the other way around. In this example, we take the parcellation into +tlrc space to allow automatic selection of parts of the atlas regions (e.g. posterior to y = -20 in +tlrc space).

 @auto_tlrc -base TT_N27+tlrc -no_ss -input {$ec}anatavgSS+orig.HEAD
 adwarp -apar {$ec}anatavgSS_at+tlrc -dpar  {$ec}anatavg+orig 
 3dfractionize -template {$ec}EPIanat+orig -input /Applications/AFNI/TT_N27_CA_EZ_MPM+tlrc -warp {$ec}anatavgSS_at+tlrc -vote -prefix {$ec}_CA_MPM
 3dROIstats -quiet -mask '3dcalc(-a AT_CA_MPM+orig -expr equals(a,105) )' ATv1decirfpcnt+orig

Alternatively, we can use 3dresample. For example, if we create a mask from the parcellation atlas, we can resample it to the lower EPI resolution as follows:

 3dresample -master stats.MX+orig -prefix STSparc_resample -inset STSparc+orig  -rmode NN