froi: fs-fast roi

manual pages

technical documentation

SYNOPSIS

compute_roi -analysis analysisName -roianalysis roiAnalysisName -roi roiName -sf sessidfile -df sessdirfile [-funcstem fmc -funcdir bold -outputstem roiName -maskdir analysisName_ROI -force -help -man]

Type ``compute_roi -man'' for complete documentation

DESCRIPTION

compute_roi takes a previously created ROI (commonly from make_roi and/or edit_roi) and, with a FS_FAST analysis, computes the average time-course over the ROI for each run in the analysis. This time course is saved as a Matlab structure in the ROI directory. Text file output (for importing into other programs) can be done using the -text argument.

To view the results, use view_roi_results.

compute_roi warns the user if there already exist computed and saved time-courses for this ROI; using the -force option will allow the user to overwrite those time courses.

NOTE: You must have the correct number of conditions for analysis analysisName, otherwise compute_roi will not work. The fsfast processing stream will work without the correct number of conditions being specified, but compute_roi will not, as it uses that value for some of its processing.

ARGUMENTS

REQUIRED ARGUMENTS

-analysis analysisName
Name of a FS-FAST analysis

-roianalysis roiAnalysisName
Name of the analysis from which you created the ROI. Do not use in conjunction with -maskdir.

-roi roiName
Name of the ROI to use in the computations.

-sf sessidfile
Name of the session ID file. Note that only one session ID in the file will be used (the last one)

-df sessdirfile
Name of the session directory file.

OPTIONAL ARGUMENTS

-funcdir bold
Name of the directory holding the functional runs. Usually ``bold'', defaults to ``bold''.

-funcstem fmc
Name of the functional stem from which to create the base. Defaults to fmc.

-outputstem roiName
Name of the output stem of the computed ROI data. Defaults to the name of the ROI.

-maskdir masks
Name of the directory where the ROI is saved. Only use if you saved data to a non-standard location when running makeROI. The default is to use the -roianalysis option to get the directory roiAnalysis_ROI. Do not use in conjunction with -roianalysis.

-text
If you give the -text paramter, compute_roi will output text files containing the computed time courses and estimated ROI responses in addition to Matlab structure. This is useful for direct importing into other programs, such as Excel or SPSS. Defaults to text files not being saved.

-force
If ROI time courses with names of the type analysis_roi_typetxt already exists (for example, if you have previously ran compute_roi on these data), compute_roi will quit. Use this option to override this behavior, but be warned that it will overwrite the existing time courses.

-help
Provides complete argument information.

-man
Provides verbose usage information.

-debug
Provides complete debugging information.

DETAILS OF RESULTS

The Matlab structure will be called ``ROIs'' and will have a number of fields, some with information about the analysis and ROI computation, some with the results of compute_roi. The contents of the resulting structure (and thus, the results of the computation) depend on the analysis. For analyses with the gammafit parameter, you can expect the following:

Blocked
ROIs.ROImean: mean time course for each run. Note that this is the raw time-course before detrending (because FS-FAST does not save detrended data currently).

ROIs.ROIhavg, ROIs.ROIhstd, ROIs.ROIhstderr: Mean, standard deviation, and standard error, respectively, of the estimated deviation from baseline for each condition within the ROI.

ROIs.ROIpct, ROIs.pctstd, ROIs.pctstderr: Percent signal change, standard deviation, and standard error, respectively, for each condition.

Event-related
ROIs.ROIhavg, ROIs.ROIhstd, ROIs.ROIhstderr: Mean, standard deviation, and standard error, respectively, of the estimated deviation from baseline for each condition within the ROI.

ROIs.ROIpct, ROIs.ROIpctstd, ROIs.ROIpctstderr: Percent signal change, standard deviation, and standard error, respectively, for each condition.

For FIR analyses, the computations create the same data for both blocked and event-related analyses:

Blocked & Event-related
ROIs.ROImean, ROIs.ROIstd, ROIs.ROIstderr: Mean, standard deviation, and standard error, respectively, of the estimated hemodynamic response function for each condition.

ROIs.ROIpct, ROIs.ROIpctstd, ROIs.ROIpctstderr: Percent signal change, standard deviation, and standard error, respectively, of the estimated hemodynamic response function for each condition.

Note that for all of these results (with the exception of the average time-courses for the runs), fixation is the first condition.

A note on the directory structure: compute_roi expects either the -roianalysis or the -maskdir command line options. The first is used if using the default storage location for the ROIs (i.e., under the functional directory). If you give the option as -roianalysis hfso, compute_roi will expect to find the roi roiName under bold/hfso_ROI. Use the option -maskdir when your ROI is not saved in this format.

TEXT OUTPUT

The contents of the saved text files are as follows (stem: contents): mean: mean time course; std: standard deviation of ``mean''; stderr: standard error of ``mean''; pct: percent signal change; pctstd: standard deviation of ``pct''; pctstderr: standard error of ``pct''; havg: estimated max responses (only for blocked); hstd: estimated standard deviation (only for blocked); hstderr: estimated standard error (only for blocked).

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: compute_roi,v 1.14 2003/10/06 16:03:46 nknouf Exp $

SEE ALSO

view_roi_results, make_roi, edit_roi, roi2label