Caret:Operations/Freesurfer to fs LR

From Van Essen Lab

(Difference between revisions)
Jump to: navigation, search
 
(20 intermediate revisions not shown)
Line 1: Line 1:
-
Data that have been processed by standard Freesurfer ‘recon-all’ (v5.1 only? Or 5.0 and 5.1?) can be converted to the 164k_fs_LR mesh using this ‘freesurfer_to_fs_LR’ script.  NB:  This is a BETA version, so please be patient, and let us (donna@brainvis.wustl.edu??) know if technical problems arise.
+
Data that have been processed by standard Freesurfer ‘recon-all’ (tested with v5.1, but may work on older versions) can be converted to the 164k_fs_LR mesh using this ‘[http://brainvis.wustl.edu/wiki/index.php/Caret:Download#Download_Freesurfer_to_fs_LR_Pipeline_Distribution "freesurfer_to_fs_LR"]’ script.  NB:  This is a BETA version, so please be patient, and email [donna@brainvis.wustl.edu] if technical problems arise.
This script is a streamlined version of Matt Glasser's FreeSurfer2CaretConvertAndRegisterNonlinear.sh script (currently under development for the Human Connectome Project).  Several steps were removed:  nonlinear spatial normalization (replaced with affine talairach.xfm); brain mask; downsampling; and caret workbench stuff.
This script is a streamlined version of Matt Glasser's FreeSurfer2CaretConvertAndRegisterNonlinear.sh script (currently under development for the Human Connectome Project).  Several steps were removed:  nonlinear spatial normalization (replaced with affine talairach.xfm); brain mask; downsampling; and caret workbench stuff.
Line 5: Line 5:
This script is used like so:
This script is used like so:
-
freesurfer_to_fs_LR.sh freesurfer-subject-directory
+
''freesurfer_to_fs_LR.sh freesurfer-subject-directory''
-
You must have both freesurfer (v 5.X or higher?) and Caret (v 5.X or higher?) installed for the script to work, as it calls command line utilities in those distributions (e.g., mri_convert, mri_info, caret_command).
+
You must have both freesurfer (tested on 5.1, but may work on older versions) and Caret v 5.64 or higher installed for the script to work, as it calls command line utilities in those distributions (e.g., mri_convert, mri_info, caret_command). See [http://brainvis.wustl.edu/wiki/index.php/Caret:Download "Caret download page"] for compatibility information.
-
[?what to say about required libraries??]
+
-
It was written to be called from within the same directory where freesurfer-subject-directory is located, but might work with an absolute path.
+
Let SUBJECTS_DIR be the parent directory where multiple freesurfer-subject-directory subdirectories are located.  (The script was written to be called from $SUBJECTS_DIR, but might work with an absolute path.)
-
Before running freesurfer_to_fs_LR.sh, be sure to edit this variable location appropriately:
+
Download freesurfer_to_fs_LR.v1.0.zip into/under $SUBJECTS_DIR. 
-
CaretAtlasSpaceDirectory=/mnt/myelin/donna/ATLAS/fs_LR/standard_mesh_atlases<br>
+
''unzip $SUBJECTS_DIR/freesurfer_to_fs_LR.v1.0.zip''
-
Note:  The standard_mesh_atlases subdirectory is included with this zip file, so point this to where you unpacked it.
+
 
 +
''cp $SUBJECTS_DIR/freesurfer_to_fs_LR/freesurfer_to_fs_LR.sh $SUBJECTS_DIR''
 +
 
 +
Use a text editor to edit $SUBJECTS_DIR/freesurfer_to_fs_LR.sh to reflect your path locations:
 +
 
 +
'' CaretAtlasSpaceDirectory=$SUBJECTS_DIR/freesurfer_to_fs_LR/standard_mesh_atlases''
 +
 +
Note:  Replace $SUBJECTS_DIR with the actual pathname of the parent directory where your freesurfer-subject-directory subdirectories are located.
Check your Freesurfer installation path, too:
Check your Freesurfer installation path, too:
-
FreeSurferInstallationDirectory=/usr/local/freesurfer
+
'' FreeSurferInstallationDirectory=/usr/local/freesurfer''
If you don't like this name for the output subdirectory, change it:
If you don't like this name for the output subdirectory, change it:
-
OutputRootDir=fs_LR_output_directory
+
'' OutputRootDir=fs_LR_output_directory''
 +
 
 +
Save your edits.
-
Save your edits; chmod +x freesurfer_to_fs_LR.sh, if needed; and run the script, e.g.:
+
''chmod +x freesurfer_to_fs_LR.sh''
-
freesurfer_to_fs_LR.sh bert
+
Run the script, e.g.:
-
Note that this command was written to be run in a directory like this:
+
'' freesurfer_to_fs_LR.sh bert''
-
/mnt/myelin/donna/SAIS
+
Example where $SUBJECTS_DIR=/mnt/myelin/donna/SAIS
... which has several Freesurfer subject directories under it, e.g.:
... which has several Freesurfer subject directories under it, e.g.:
Line 41: Line 49:
/mnt/myelin/donna/SAIS/SAIS_009_MR1<br>
/mnt/myelin/donna/SAIS/SAIS_009_MR1<br>
-
In other words, it might be your Freesurfer $SUBJECTS_DIR directory.  One of these is your input to this command; its contents are read, but not modified (e.g., ?h.white, ?h.pial, ?h.sphere, ?h.sphere.reg, ?h.curv, ?h.sulc, ?h.thickness, orig.mgz, talairach.xfm).  Outputs go to $OutputRootDir.
+
The subdirectory contents are read, but not modified (e.g., ?h.white, ?h.pial, ?h.sphere, ?h.sphere.reg, ?h.curv, ?h.sulc, ?h.thickness, orig.mgz, talairach.xfm).  Outputs go to $OutputRootDir.
If OutputRootDir=fs_LR_output_directory and you run this command once for each of subject directory, e.g.:
If OutputRootDir=fs_LR_output_directory and you run this command once for each of subject directory, e.g.:
Line 59: Line 67:
/mnt/myelin/donna/SAIS/fs_LR_output_directory/SAIS_009_MR1<br>
/mnt/myelin/donna/SAIS/fs_LR_output_directory/SAIS_009_MR1<br>
-
Each of these subdirectories in /mnt/myelin/donna/SAIS/fs_LR_output_directory would have output files like those listed below.
+
Each of these subdirectories in /mnt/myelin/donna/SAIS/fs_LR_output_directory would have output files like those listed [http://brainvis.wustl.edu/wiki/index.php/Caret:Operations/Freesurfer_to_fs_LR/Output here].
The real magic of this script is in this command:
The real magic of this script is in this command:
Line 93: Line 101:
Pseudocode for left hemisphere:
Pseudocode for left hemisphere:
-
1.  Project SAIS_001/surf/lh.sphere.reg to $FreeSurferInstallationDirectory/subjects/fsaverage/surf/lh.sphere.reg.  (Because we're using sphere.reg, they should be in good geographic agreement, so this is a more or a resampling from initial mesh to the Freesurfer hemisphere-specific 164k mesh.)
+
1.  Project SAIS_001/surf/lh.sphere.reg to $FreeSurferInstallationDirectory/subjects/fsaverage/surf/lh.sphere.reg.  (Because we're using sphere.reg, they should be in good geographic agreement, so this is a more of a resampling from initial mesh to the Freesurfer hemisphere-specific 164k mesh.)
-
2.  Unproject the hem-specific 164k sphere onto the hemisphere-independent (fs_LR) sphere.  This keeps the nodes the same, so there is no resampling, but the geography gets swapped around, so that node i in both left and right is in decent correspondence.  (In the hem-specific spheres, node i might be in the frontal lobe on the left, occipital on the right.)  [DVE: I'm not sure this is technically correct - see email]
+
2.  Unproject the hem-specific 164k sphere onto the hemisphere-independent (fs_LR) sphere using a point projector to transform the vertices.
-
Repeat for the right.
+
Repeat for the right.  Vertex i on the left fs_LR 164k mesh should be in decent correspondence with vertex i on its right counterpart.

Latest revision as of 14:44, 19 June 2012

Data that have been processed by standard Freesurfer ‘recon-all’ (tested with v5.1, but may work on older versions) can be converted to the 164k_fs_LR mesh using this ‘"freesurfer_to_fs_LR"’ script. NB: This is a BETA version, so please be patient, and email [donna@brainvis.wustl.edu] if technical problems arise.

This script is a streamlined version of Matt Glasser's FreeSurfer2CaretConvertAndRegisterNonlinear.sh script (currently under development for the Human Connectome Project). Several steps were removed: nonlinear spatial normalization (replaced with affine talairach.xfm); brain mask; downsampling; and caret workbench stuff.

This script is used like so:

freesurfer_to_fs_LR.sh freesurfer-subject-directory

You must have both freesurfer (tested on 5.1, but may work on older versions) and Caret v 5.64 or higher installed for the script to work, as it calls command line utilities in those distributions (e.g., mri_convert, mri_info, caret_command). See "Caret download page" for compatibility information.

Let SUBJECTS_DIR be the parent directory where multiple freesurfer-subject-directory subdirectories are located. (The script was written to be called from $SUBJECTS_DIR, but might work with an absolute path.)

Download freesurfer_to_fs_LR.v1.0.zip into/under $SUBJECTS_DIR.

unzip $SUBJECTS_DIR/freesurfer_to_fs_LR.v1.0.zip

cp $SUBJECTS_DIR/freesurfer_to_fs_LR/freesurfer_to_fs_LR.sh $SUBJECTS_DIR

Use a text editor to edit $SUBJECTS_DIR/freesurfer_to_fs_LR.sh to reflect your path locations:

CaretAtlasSpaceDirectory=$SUBJECTS_DIR/freesurfer_to_fs_LR/standard_mesh_atlases

Note: Replace $SUBJECTS_DIR with the actual pathname of the parent directory where your freesurfer-subject-directory subdirectories are located.

Check your Freesurfer installation path, too:

FreeSurferInstallationDirectory=/usr/local/freesurfer

If you don't like this name for the output subdirectory, change it:

OutputRootDir=fs_LR_output_directory

Save your edits.

chmod +x freesurfer_to_fs_LR.sh

Run the script, e.g.:

freesurfer_to_fs_LR.sh bert

Example where $SUBJECTS_DIR=/mnt/myelin/donna/SAIS

... which has several Freesurfer subject directories under it, e.g.:

/mnt/myelin/donna/SAIS/SAIS_001
/mnt/myelin/donna/SAIS/SAIS_002_MR1
/mnt/myelin/donna/SAIS/SAIS_003
/mnt/myelin/donna/SAIS/SAIS_004_MR1
/mnt/myelin/donna/SAIS/SAIS_009_MR1

The subdirectory contents are read, but not modified (e.g., ?h.white, ?h.pial, ?h.sphere, ?h.sphere.reg, ?h.curv, ?h.sulc, ?h.thickness, orig.mgz, talairach.xfm). Outputs go to $OutputRootDir.

If OutputRootDir=fs_LR_output_directory and you run this command once for each of subject directory, e.g.:

freesurfer_to_fs_LR.sh SAIS_001
freesurfer_to_fs_LR.sh SAIS_002_MR1
freesurfer_to_fs_LR.sh SAIS_003
freesurfer_to_fs_LR.sh SAIS_004_MR1
freesurfer_to_fs_LR.sh SAIS_009_MR1

... then you would get output subdirectories like this:

/mnt/myelin/donna/SAIS/fs_LR_output_directory/SAIS_001
/mnt/myelin/donna/SAIS/fs_LR_output_directory/SAIS_002_MR1
/mnt/myelin/donna/SAIS/fs_LR_output_directory/SAIS_003
/mnt/myelin/donna/SAIS/fs_LR_output_directory/SAIS_004_MR1
/mnt/myelin/donna/SAIS/fs_LR_output_directory/SAIS_009_MR1

Each of these subdirectories in /mnt/myelin/donna/SAIS/fs_LR_output_directory would have output files like those listed here.

The real magic of this script is in this command:

 caret_command -surface-sphere-project-unproject \
$OutputRootDir/$Subject/$InitialMeshDirectory/$Subject.$Hemisphere.sphere.reg.initial_mesh.coord.gii \
$OutputRootDir/$Subject/$InitialMeshDirectory/$Subject.$Hemisphere.initial_mesh.topo.gii \
$OutputRootDir/$Subject/$InitialMeshDirectory/$Subject.$Hemisphere.sphere.reg.reg_LR.initial_mesh.coord.gii \
$OutputRootDir/$Subject/fsaverage/$Subject.$Hemisphere.sphere.164k_fs_"$Hemisphere".coord.gii\
$OutputRootDir/$Subject/fsaverage/$Subject.$Hemisphere.def_sphere.164k_fs_"$Hemisphere".coord.gii \
$OutputRootDir/$Subject/fsaverage/$Subject.$Hemisphere.164k_fs_"$Hemisphere".topo.gii

Its usage is like so:

     caret_command -surface-sphere-project-unproject  
        1<input-spherical-coordinate-file-name>
        2<input-spherical-topology-file-name>
        3<output-spherical-coordinate-file-name>
        4<project-to-spherical-coordinate-file-name>
        5<unproject-to-spherical-coordinate-file-name>
        6<project-unproject-spherical-topology-file-name>
        
        Transform a spherical surface.
        
        The input spherical surface is projected to the 
        "project-to" surface using barycentric projections
        and then unprojected using the "unproject-to" 
        spherical surface.  Typically the "unproject-to"
        surface is created during surface-based registration
        of the "project-to" spherical surface to some
        target.

Pseudocode for left hemisphere:

1. Project SAIS_001/surf/lh.sphere.reg to $FreeSurferInstallationDirectory/subjects/fsaverage/surf/lh.sphere.reg. (Because we're using sphere.reg, they should be in good geographic agreement, so this is a more of a resampling from initial mesh to the Freesurfer hemisphere-specific 164k mesh.)

2. Unproject the hem-specific 164k sphere onto the hemisphere-independent (fs_LR) sphere using a point projector to transform the vertices.

Repeat for the right. Vertex i on the left fs_LR 164k mesh should be in decent correspondence with vertex i on its right counterpart.

Personal tools
Sums Database