NAME
label2roi -- takes a surface based label and, with a registration matrix, converts this label into a slice-based ROI suitable for use with the basic ROI tools like edit_roi, combine_roi, and compute_roi.
SYNOPSIS
label2roi -roianalysis roi_analysis_name -label label_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
Surface-based ROI analyses in Freesurfer are performed using labels, which are simply a list of marked vertices. Using the tools in tksurfer, it is quite easy to draw labels that encompass various anatomical regions. With a program like combine_label, you can take two labels and create either the intersection and/or union of the labels. What if, however, you'd like to see where these labels land on the slices?
label2roi exists to transform a surface- or volume-based label into a slice-based ROI. It uses the Freesurfer program mri_surf2vol to do most of its work. Note that this assumes you have done the following:
-
Reconstructed the subject's brain.
Registered the current session to the previous session anatomicals that were used to reconstruct the brain.
Created a subjectname file, as described in the FS-FAST documentation.
One must be careful when using this program; if, for some reason, your slice prescription does not include the region within the label, the program will fail with an error.
The label filename must be in a certain format. The label filename must be of the form: label-hemi.label, where ``label'' is the name given with the -label flag, and ``hemi'' is the hemisphere given with the -hemi flag. For example, if you have a right hemisphere fusiform label, your label file should called ``fusiform-rh.label'', and your command line arguments would be ``-label fusiform -hemi rh''. label2roi will create an roi named ``label.roi'', so in the previous example, it would create ``fusiform.roi''.
ARGUMENTS
REQUIRED ARGUMENTS
- -roianalysis roi_analysis_name
- Name of the analysis under which you created the ROI and subsequently created labels. label2roi will search for labels under roidir/label.
- -label label_name
- Stem name of the label.
- -hemi <rh|lh>
- Hemisphere from which to map the label. Note that if you try and map a label from a hemisphere to a slice prescription that does not contain the label, 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 su rface 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 boundar y.
- -labeldir roi_analysis_ROI/label
- Directory from which to search for the input label. 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 resulting ROI. 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 label2roi for a ROI 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}, 'label=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 an roi analysis\n'') if !$ROIdata->{analysis}; pod2usage(-message => ``\nERROR: Need to use either -roianalysis or -maskdir\n'') if (!$ROIdata->{analysis} and !$ROIdata->{mask_path}); pod2usage(``\nERROR 124: Need to enter an ROI name\n'') if !$ROIdata->{roi}; pod2usage(``\nERROR: 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
$ROIdata->getsessid(); $ROIdata->getsessdir(); $ROIdata->getsubjectname(); $ROIdata->set_func_path();
logfile_start($ROIdata); logfile(``command line: $ROIdata->{prog_name} @arglist''); logfile(``starting $ROIdata->{prog_name}...'',1);
$ROIdata->getseqinfo();
$ROIdata->set_analysis_path();
$ROIdata->getanalysisinfo();
## get the runlist, if it exists $ROIdata->getrunlist();
$ROIdata->getbase();
$ROI->set_roi_path($ROIdata);
$ROI->check_roi($ROIdata, 2);
$ROI->check_label_path($ROIdata);
$ROI->run_label2roi($ROIdata);
logfile(``\n''.'$Id: label2roi,v 1.5 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); }
__END__
BUGS
None known of. 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: label2roi,v 1.5 2003/10/06 16:03:47 nknouf Exp $
SEE ALSO
make_roi, edit_roi, roi2label