NAME
roi2label -- takes a text-based ROI (created using make_roi and/or edit_roi) and transforms that to a volume- or surface-based label. An intermediate step creates a *.w paint file that can be displayed in either the volume or on the surface.
SYNOPSIS
roi2label -roianalysis roi_analysis_name -roi roi_name -hemi <rh|lh> -sf sessid_file -df sessdir_file [-labeldir roianalysis_ROI/label -bolddir bold -maskdir roianalysis_ROI -funcstem fmc -outputstem roi-hemi -force -help -man -debug]
DESCRIPTION
Slice-based ROIs (which are made by make_roi and/or edit_roi) are useful when you want to look at ROIs within a particular subject within a particular session; they eliminate the distortions caused by transformation into another space, such as Talairach or spherical. However, there are times when you might want to look at ROIs over multiple sessions, or wants to compare ROIs across subjects in another space. To that end, roi2label exists to transform a slice-based ROI into a surface-based label.
To use roi2label you must have a reconstructed brain for the subject in question, a ``subjectname'' file under their session directory with the name of the reconstructed subject's name inside, and a ``register.dat'' file under their bold directory. This thus assumes that you have run either autoreg-sess or tkregister-sess on this subject to create the register.dat file. Registering and reconstructing a brain takes a fair amount of time on the part of the researcher and thus should probably only be done with long-term or repeat subjects.
Labels are saved under the roi directory of the subject, within a directory called ``label''. Note that if you then want to compare labels across different sessions or subjects (for example, with the combine_label program), you will need to move the label(s) into a common location.
roi2label uses the Freesurfer program ``mri_vol2surf'' for the mapping of slice-based data to a surface-based representation.
Note that the program will fail with an error if there are no vertices in the resulting mapping. If this occurs, ensure that you are mapping to the correct hemisphere, as this is an easy place to make a mistake.
ARGUMENTS
REQUIRED ARGUMENTS
- -roianalysis roi_analysis_name
- Name of the analysis under which you created the ROI.
- -roi roi_name
- Name of the ROI.
- -hemi <rh|lh>
- Hemisphere on which to map the ROI. Note that if you try and map an ROI from a hemisphere for which there are no voxels, the program will fail with an error.
- -sf sessid_file
- Name of the session ID file.
- -df sessdir_file
- Name of the session directory file.
OPTIONAL ARGUMENTS
- -projfrac 0
- Fraction [0, 1] of the cortical thickness at each vertex to project along the surface normal. The default is 0. Change this to project more of your data onto the cortical surface, as the default is to sample only at the grey-white boundary.
- -labeldir roi_analysis_ROI/label
- Directory where you want the output label to be stored. Defaults to a directory called ``label/'' underneath your ROI analysis directory.
- -bolddir bold
- Name of the functional directory. Defaults to ``bold''.
- -maskdir roianalysis_ROI
- Name of the directory that holds the ROIs. Defaults to <roianalysis_ROI>; set this argument if you save your data in a non-standard location. Do not use in conjunction with -roianalysis.
- -funcstem fmc
- Name of the functional stem. Defaults to ``fmc''. Change this if, for example, you have separate functional volumes for smoothing and want to create ROIs from that data.
- -outputstem roi-hemi
- Name of the stem for the output label. Defaults to roi-hemi, making the output file <roi-hemi.label>.
- -force
- If you attempt to run roi2label for a label that has previously been created, the program will quit with an error, telling you of this situation. Use this parameter to override that behavior.
- -help
- Terse usage information.
- -man
- Complete usage information (this file).
- -debug
- Displays debugging information. Use this option to help debug unexpected behavior and when submitting a bug report.
=cut
## use strict checking use strict;
## use Getopt module for checking command line options use Getopt::Long;
## use Pod module for automatic help info use Pod::Usage;
## use roi functions use FSFAST::Parse;
## make new instance of ROI object my $ROIdata = new FSFAST::Parse;
$ROIdata->get_prog_name($ROIdata, $0);
## use roi functions use FSFAST::ROI;
## make new instance of ROI object my $ROI = new FSFAST::ROI;
## use misc functions use FSFAST::Misc qw/:log/;
## set default values my $force = 0; my $help = 0; my $man = 0;
## save argument list my @arglist = @ARGV;
## command-line parsing using GetOpt::Long GetOptions('roianalysis=s' => \$ROIdata->{analysis}, 'roi=s' => \$ROIdata->{roi}, 'hemi=s' => \$ROIdata->{hemi}, 'sf=s' => \$ROIdata->{sessid_file}, 'df=s' => \$ROIdata->{sessdir_file}, 'projfrac:f' => \$ROIdata->{projfrac}, 'labeldir:s' => \$ROIdata->{labeldir}, 'bolddir:s' => \$ROIdata->{bold_dir}, 'maskdir:s' => \$ROIdata->{mask_path}, 'funcstem:s' => \$ROIdata->{func_stem}, 'outputstem:s' => \$ROIdata->{output_stem}, 'force' => \$ROIdata->{force}, 'help' => \$help, 'man' => \$man, 'debug' => \$ROIdata->{debug}) or pod2usage(2);
## help messages if missing required paramters pod2usage(-verbose => 1) if $help; pod2usage(-verbose => 2) if $man; pod2usage(-message => ``\nERROR 123: Need to enter a roi analysis\n'', -verbose => 0) if !$ROIdata->{analysis}; pod2usage(-message => ``\nERROR: Need to use either -roianalysis or -roidir\n'', -verbose => 1) if (!$ROIdata->{analysis} and !$ROIdata->{mask_path}); pod2usage(``\nERROR 124: Need to enter a ROI name\n'') if !$ROIdata->{roi}; pod2usage(``\nERROR 125: Need to enter a hemisphere (either rh or lh)\n'') if !$ROIdata->{hemi}; pod2usage(``\nERROR 121: Need to enter a session id file name\n'') if !$ROIdata->{sessid_file}; pod2usage(``\nERROR 122: Need to enter a session directory file name\n'') if !$ROIdata->{sessdir_file};
## Initialize ROI with given values
## Normally we would use $ROIdata->init() here, but we have some special cases
## and don't need (and don't have) all of the information that init
## would require.
$ROIdata->getsessid(); $ROIdata->getsessdir(); $ROIdata->getsubjectname(); $ROIdata->set_func_path();
logfile_start($ROIdata); logfile(``command line: $ROIdata->{prog_name} @arglist''); logfile(``starting roi2label...'',1);
$ROIdata->getseqinfo();
$ROIdata->set_analysis_path();
$ROIdata->getanalysisinfo();
$ROI->set_roi_path($ROIdata);
$ROI->check_roi($ROIdata, 1);
$ROI->check_label_path($ROIdata);
$ROI->run_roi2label($ROIdata);
logfile(``\n''.'$Id: roi2label,v 1.7 2003/10/06 16:03:47 nknouf Exp $',1);
if (-f (``$ROIdata->{cwd}/log/$ROIdata->{prog_name}.oops'')) { unlink ``$ROIdata->{cwd}/log/$ROIdata->{prog_name}.oops''; logfile(``$ROIdata->{prog_name} FAILED\n'',1); } else { logfile(``$ROIdata->{prog_name} SUCCESSFULLY COMPLETED\n'',1); }
BUGS
None known at the moment. ``mri_vol2surf'' sometimes gives a warning of the form ``voxel size not the same''; I have not tested to see if this causes problems or not. Send bug reports to <froi-bugs@sourceforge.net>.
AUTHOR
Nicholas Knouf, <nknouf@mit.edu>, <nknouf@mimeme.net>
COPYRIGHT & LICENSE
Copyright (c) 2003, Nicholas Knouf, MIT.
This program is free software and is governed by the terms of the Artistic License.
REVISION
$Id: roi2label,v 1.7 2003/10/06 16:03:47 nknouf Exp $
SEE ALSO
makeROI, editROI