FSFAST::Parse -- Parse FSFAST configuration files

NAME
SYNOPSIS
DESCRIPTION
EXPORT
METHODS

new()
getsessid()
getsessdir()
set_func_path()
getseqinfo()
set_analysis_path()
getanalysisinfo()
getanalysiscfg()
getrunlist()
getbase()
getsubjectname()
get_prog_name()
gettmpfile()
gettmpdir()

AUTHOR
COPYRIGHT
LICENSE
REVISION
SEE ALSO

NAME

SYNOPSIS

        use FSFAST::Parse;

        my $ROIdata = new FSFAST::Parse;

        $ROIdata->get_prog_name($ROIdata, $0);

        ## populate hash variables, such as:
        ## analysis, contrast, roi, threshold, map,
        ## fdr, np, sessid_file, sessdir_file, mask
        ## inputroi, outputroi, mask_dir, func_stem, base
        ## signed, debug, noedit, etc.
        ## See the constructor for more details.

        $ROIdata->getsessid();
        $ROIdata->getsessdir();
        $ROIdata->set_func_path();

        $ROIdata->getseqinfo();

        $ROIdata->getanalysisinfo();
        $ROIdata->getanalysiscfg();

        $ROIdata->getrunlist();

        $ROIdata->getbase();

        ## run ROI specific code from FSFAST::ROI

FS-FAST and Freesurfer are fMRI anlaysis suites developed at the Massachusetts General Hospital (http://surfer.nmr.mgh.harvard.edu). While FS-FAST provides easy analysis of functional data in the slices, and Freesurfer maps that data to 2-D surfaces and 3-D volumes, the command-line interface code is written as shell scripts, making re-use of the code difficult to impossible. I wrote the FSFAST::Parse manpage in order to create such a re-usable framework.

the FSFAST::Parse manpage parses all of the standard FS-FAST configuration files, including sessid, sessdir, seq.info, analysis.info, and so on, as well as setting up some basic paths.

EXPORT

No functions are exported by default.

METHODS

the FSFAST::Parse manpage provides numerous functions to parse various FS-FAST files, including your session ID file, session directory file, analysis.info file, and so on. As well, the FSFAST::Parse manpage can check the consistency of what is in these files with what is actually in the filesystem.

In all of the following documentation, $ROIdata is a hash variable created by calling the the FSFAST::Parse manpage constructor.

`new()`

Constructor for the FSFAST::Parse manpage, new() populates a hash with default values. Many of these values will be changed based on user-input (such as from the command line), or they could be set directly in a script (see the test script, test.pl, for details). You may need to change the value of matlab if matlab is not in your path.

Examples of how to populate the hash with values from the command-line are available from any of the command-line scripts in froi (http://froi.sourceforge.net).

Many of the variables are self-explanatory; more information is available in the comments.

`getsessid()`

getsessid() expects to be called as $ROIdata-getsessid()>, where there exists in $ROIdata a key named sessid_file which is the name of your session ID file. getsessid() opens said session ID file to retreive the session ID. Note that if there are multiple session IDs in the file, only the last will be used.

`getsessdir()`

In order to know where the subject's data resides, we look at the session directory file. getsssdir() reads this file (stored in the sessdir_file) and puts the result in $ROIdata-{sessdir}>.

`set_func_path()`

Once we know the session directory, the session ID, and the bold directory (either from the default or from a command-line paramter), we can set the functional directory. set_func_path() does this and stores the result in $ROIdata-{func_path}>.

`getseqinfo()`

A number of important parameters are in the seq.info file that is a standard result of the unpacking process at MGH. getseqinfo() reads the seq.info file (assumed to be located at $ROIdata-{func_path}/seq.info>) and populates the hash with the contents of the file. These values are stored in the corresponding keys: nrows, ncols, nslcs, rowpixelsize, colpixelsize, slcpixelsize, ntrs.

`set_analysis_path()`

set_analysis_path expects the $ROIdata hash to contain keys func_path and analysis; from those values, it forms the analysis_path key. Finally, it checks to make sure such a path exists, and if not, croaks with an error.

`getanalysisinfo()`

Many of the user-defined analysis parameters are stored in the analysis.info file, found under the directory for your analysis and created as a result of mkanalysis-sess.new. getanalysisinfo() expects an analysis_path key which it then uses to open the analysis.info file for parsing. getanalysisinfo() reads the file and sets the appropriate keys in the hash. The analysis.info file is assumed to be located within the analysis path directory as analysis.info. Call set_analysis_path() before running.

The hash keys set are: runlistfile, TR, designtype, nconditions, parname, fsd, funcstem, and tpexclude.

`getanalysiscfg()`

Much like with getanalysisinfo(), getanalysiscfg() parses another file necessary to the FS-FAST analysis, analysis.cfg, created as a result of running mkanalysis-sess.new. <getanalysiscfg()> parses the file and sets the appropriate hash keys. The analysis.cfg file is assumed to be located under the analysis path as analysis.cfg; be sure to run set_analysis_path() previously.

`getrunlist()`

getrunlist() gets a list of the runs for the current analysis. If there is no runlist file set in the analysis.info file, getrunlist() merely gets a list of the functional directories underneath your functional path. If, however, a runlist is set, getrunlist() will open that file and create a list of the functional directories given in the runlist file. Run this before getbase().

`getbase()`

When displaying ROIs, it is necessary to have a base set of functionals over which to display the ROI. In nearly all cases, this is simply the first directory in the string indexed by the runlist key. If, however, you have an average functional set on which to overlay your ROI, and gave such a base using the command-line parameter -base, then getbase() will select that directory as the base. Finally, getbase() checks to make sure said directory actually exists.

`getsubjectname()`

When using scripts that involve surface- or volume-based representations, we need to know the name of the reconstructed subject; this is given in the subjectname file. getsubjectname() will parse this file, assumed to be called subjectname and stored under /sessdir/sessid and will place this subjectname in the key subjectname. Make sure that there is only one line in the subjectname file (no blank lines!), otherwise the scripts will spit out strange errors.

`get_prog_name()`

get_prog_name expects to be given a hash to store a key-value pair, as well as the command line of the program. It then parses the $0 variable to get the name of the program being run, and stores this value in the key prog_name.

`gettmpfile()`

When running analyses, we commonly need to store Matlab commands in a temporary script. gettmpfile() will return a filename to a (hopefully non-existent) temporary file under /tmp. When you have finished using the temporary file be sure to unlink it. At the moment, gettmpfile() does not check to see if the file already exists, which may lead to strange results if files are not unlinked after use.

`gettmpdir()`

Similar to gettmpfile(), we sometimes need a temporary directory (for example, to store a temporary bfloat volume for use by roi2label). gettmpdir() will do that and return a temporary directory under /tmp. As with gettmpfile(), you should remove the directory created after you are done using it. The safest way to do this is to use the the File::Path manpage module and rmtree. See that module's documentation for details.

froi: fs-fast roi

perl modules

technical documentation