froi: fs-fast roi

perl modules

technical documentation

NAME

FSFAST::ROI -- Perform slice- and surface-based ROI analysis on data analysed by FS-FAST and Freesurfer

SYNOPSIS

        use FSFAST::Parse;
        my $ROIdata = new FSFAST::Parse;
        ## populate $ROIdata hash
        use FSFAST::ROI;
        my $ROI = new FSFAST::ROI;
        $ROI->set_roi_path($ROIdata);
        $ROI->make_roi_path($ROIdata);
        $ROI->check_roi($ROIdata, 1);
        $ROIdata->set_roi_stems($ROIdata);
        $ROI->run_*($ROIdata);
        ## ad nauseum

DESCRIPTION

FS-FAST and Freesurfer (http://surfer.nmr.mgh.harvard.edu) are software suites for the analysis of fMRI data, both within slices and on reconstructed 2-D surfaces. While the region-of-interest (ROI) capabilities on the surface are many, there are no slice-based ROI tools. This is an important deficit, as slice-based ROI analyses are not fraught with the concerns over registration and mapping that occur when you transfer data from the slices to the surface. Slice-based ROI analyses have a long history in fMRI analysis for a good reason: you are certain that the voxels contained in your ROI are the ones that you choose, and are not being mapped in some complex fashion to another space. With that said, there are a number of times when one is interested in ROI analyses on the surface, thus surface- and volumed-based methods do have a place in modern fMRI analysis.

There are also some deficits in ROI analysis on the surface within Freesurfer, however, such as the ability to look at overlap between two or three labels, the ability to easily select all active vertices and save that as a label, performing an intersection between a statistical map (commonly from a *.w file) and an anatomical label, and so on.

the FSFAST::ROI manpage aims to recitfy this situation by creating a reusable framework of functions for ROI analysis of FS-FAST and Freesurfer analysed data. There are a number of computations that can be carried out in perl, but many must be done using matlab or programs from the FS-FAST and Freesurfer distribution. Thus those two software packages are required in addition to this module.

ROI METHODS

ROI methods deal with creating ROI paths, checking to make sure ROIs exist, and so on. These methods should be run before any of the MATLAB HOOKS are run.

new()

Constructor for the FSFAST::ROI manpage. No hash variables are created; rather, all key-value pairs come from the $ROIdata hash in the FSFAST::Parse manpage. This constructor only is used to create a variable for running the module functions; this was an early design decision and will probably be changed in future updates to the program to run as FSFAST::ROI::check_roi syntax.

set_roi_path($ROIdata)

Forms the path to the ROIs. If there is a mask_path key in $ROIdata, the roi_path key becomes func_path/mask_path; otherwise, the default path of func_path}/analysis_ROI is the roi_path. The path is then saved in the roi_path key.

make_roi_path($ROIdata)

Makes a ROI directory from the value in the roi_path key. Also creates symbolic links in the ROI directory to the analysis.cfg and analysis.info files of the underlying analysis.

check_roi($ROIdata, $method)

Checks to see if the ROI in the roi key exists in the roi_path. Two arguments as input: first is the $ROIdata hash, the second is the type of check to be done: 1 for simply checking to see if the ROI exists, 2 for warning the user the ROI already exists in the roi_path If it is the later, the program quits with an error unless the command line paramter -force is given.

set_roi_stems($ROIdata)

Sets the path to the contrast directory and stores it in the contrast_path key. As well, sets the stem of the statistical map to use and stores it in the map_path key.

check_roi_info($ROIdata)

Checks to see if a roi.info file exists; this must exist before we can display the results of an ROI overlap computation from combine_roi.

check_roi_results($ROIdata)

Checks to see if results for the ROI have already been computed by compute_roi; if they have, quit with an error unless the command-line paramter -force is set.

check_label_path($ROIdata)

Checks to make sure that a label directory exists under the ROI directory; if it doesn't exist, create it, and if a label path hasn't been set, assign the default label path and create the label directory.

MATLAB HOOKS

Most of the computation involved in fMRI analysis using FS-FAST and Freesurfer takes place within matlab; thus creating temporary matlab scripts at runtime is a necessity. The following methods use use-defined paramters to create matlab scripts which are then passed to the internal function _run_matlab which takes care of matlab-specific arguments. If you need to change the arguments to matlab, do so in the _run_matlab method.

_run_matlab($ROIdata, $tmpfile)

Private function to run matlab with appropriate parameters. Logs all matlab output to the logfile.

run_list_roi($ROIdata)

An exeption to the rule; this method does not require matlab; rather, given an roi_path key, it lists the ROIs in that directory. This is useful when you have run many ROI analyses and cannot remember the names of your ROIs!

run_make_roi($ROIdata)

Thresholds a statistical map and creates an ROI; by default, also allows the user to immediately edit the ROI.

run_edit_roi($ROIdata, <$use_overlay>)

Separate script to allow a user to edit an ROI.

run_compute_roi($ROIdata)

Takes a previously created ROI and a dataset (with the same dimensions as the ROI) and computes ROI averages. This script works for both event-related and blocked designs, as well as gammafit and FIR analyses.

run_combine_roi($ROIdata)

Combines two or three ROIs by set intersection or union; also creates a map of ROI overlap to be viewed using display_overlap.

run_display_overlay($ROIdata)

Using an ROI created by combine_roi with the -method overlap paramter, show the overlap of the two or three ROIs.

run_roi2label($ROIdata)

Takes a slice-based ROI and converts it to a surface-based label, run_roi2label requires that the subject in question has undergone surface reconstruction.

run_label2roi($ROIdata)

Converts a surface- or volume-based label to a slice-based ROI.

run_make_label($ROIdata)

Convert a FS-FAST contrast to a label, saving a *.w paint file along the way.

run_view_roi_results($ROIdata)

Calls a matlab script to view the results of an ROI computation (from compute_roi) through a matlab GUI.

run_view_sm($ROIdata)

Creates and views a selectivty map for two conditions.

run_view_mesh($ROIdata)

Creates and views a surface mesh for all conditions in your analysis.

LABEL METHODS

In addition to slice-based ROI methods, the FSFAST::ROI manpage can also do some surface- and volume-based ROI computations. The following methods are used for that purpose.

open_labels($ROIdata, $label_reference)

Given a reference to a list of labels, open_labels opens the labels, reads them into lists, and return references to the lists. As of this version, only two labels can be opened at any one time.

write_label($ROIdata, $reference_to_label_data)

Writes a label to file. First argument is the $ROIdata hash with the name of the output label in the output_label key, the second argument is the data to be written, given as an array reference.

label_number($ROIdata, $reference_to_label_data)

Prints the number of vertices in each label, as well as the amount of overlap. Quits if there are no elements in the combination. Assumes that the method is ``intersection''.

check_method($ROIdata)

Ensure that the given method is one of the allowed methods as defined in the global variable @allowed_methods.

label_intersect($ROIdata, $array1_reference, $array2_reference)

Computes the intersection of the two labels using the built-in grep function. Requires a $ROIdata hash with key subjectname; output the total number of elements in the combination to the hash key num_elements. Second and third arguments are array references to array 1 and 2, respectively. Takes somewhat long with large labels.

label_union

Not implimented for this release.

AUTHOR

Nicholas Knouf, <nknouf@mit.edu>, <nknouf@mimeme.net>

COPYRIGHT

Copyright (c) 2003, Nicholas Knouf, MIT

LICENSE

All rights reserved. This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

REVISION

$Id: ROI.pm,v 1.21 2003/10/15 19:45:27 nknouf Exp $

SEE ALSO

the FSFAST::Parse manpage, the FSFAST::Misc manpage