PEATE - Perl Event-related Average Timecourse Extraction
TK Version
This page contains information about using Peate with the Perl/TK user interface, or as a command line tool with no GUI. If you are using Mac OS X, you may want to visit this page about running Peate as an OS X application.
Current version 3.01, October, 2013. (Full version history).
Peate can now be run as a command line tool without invoking the GUI. To do this, you save your settings in a text file called a Peate Configuration File (ending in .pcf) and run pass that file to peate as a command line argument. For example, if you type:
peate myconfigfile.pcf
then Peate will not launch the GUI, and instead will use the settings from that file to run. An example configuration file can be found here.
Table of Contents
Screenshots
Main GUI
Download
Click here to download the plain script (separate Perl/Tk installation needed)
Installation
You will need to have a few perl modules installed for Peate to work. They are all available from CPAN, which is built into most perl distributions and allows for easy installation.
The first module you need is Perl/Tk. This allows perl to interface with the Tk graphical user interface libraries. You can install with the following command:
sudo perl -MCPAN -e 'install Tk'
If this doesn't work, you may have to download the package from CPAN and install it yourself. You can find the Perl/Tk package here.
As of version 1.65, you will also need the Math::Spline and Math::Derivative modules so that Peate can do spline interpolation. To install them, use
sudo perl -MCPAN -e 'install Math::Derivative' sudo perl -MCPAN -e 'install Math::Spline'
Once again, if this doesn't work, try downloading them directly from CPAN and follow the install instructions there. The math packages are located here.
Also, make sure the first line of Peate points to your version of perl. This is usually /usr/bin/perl. Make sure Peate is executable (chmod +x peate) and located within your path.
Click here for tips on installing Peate on SuSE Linux 9.2.
Usage
Peate works on data that has already been analyzed and registered using FSL. It will look inside the design.fsf file for each specified feat directory and retrieve useful information, including the stimulus timings. Peate now works when you have specified your stimulus timings in "custom 3-column format", "custom 1-column format" or as a square wave. It is necessary that you have run registration for each feat directory, as Peate will warp your mask into the individual run's space by using registration matrices inside the "reg" folder inside each feat directory.The following instructions tell you how to run Peate from the Perl/Tk graphical user interface, which is the default way to use Peate. If you want to bypass the GUI (sometimes this is useful when running peate remotely, for example) you can instead run Peate in command line mode.
Input filenames. The first thing Peate wants is a list of all the lower-level feat directories to be analyzed. You can enter this in three ways: 1) use the file browser icon to select a text file that contains a list of directories one on each line, 2) click the text icon and type in a list of directories, one on each line, or 3) if you only want to analyze one feat directory, just type in the name of the directory, making sure it ends in .feat. The path to the directories should either be a full path from the root level of your system, or a path relative to the directory that Peate was started from.
Mask image(s). This is a mask or list of mask files which defines your region(s) of interest. Peate now supports multiple mask files if you want to get timecourses from more than one region of interest. The mask files can be either Analyze or Nifti files (if you are using FSL 3.2). If you have only one mask you can either type it in the box or select it with the file browser. If you want Peate to work on more than one mask, either select or type in the name of a text file which contains a list of the mask files, or type in this list using the text editor.
The mask can be in the standard space, the highres space, the initial_highres space, or the example_func space but you must select the appropriate space from the pull-down menu (st=standard, hr=highres, ih=initial_highres, ef=example_func). This mask will be warped into the space of each functional run using the registration files within each feat directory. This means that registration must have been performed on each lower level feat directory. If you select the example_func option, the mask will be warped with an identity matrix which will leave the data untransformed.
Single voxel mode. Single voxel mode is currently only available in command-line mode or in the Mac OSX Cocoa GUI. If you wish to extract the timecourse from a single voxel instead of a masked region, that option may be specified in the pcf file with the "Use coordinates" option. Voxel location should be specified in mm coordinates. Makes sure to specify the "Coordinate space" in which voxel is specified in, as Peate will convert voxels to the example_func space. Use the demo pcf file as a guide.
Output prefix. This is the name of the output file that will be created by Peate. Peate will create a file with the name outputprefix-timeseries.txt. This file contains one column of numbers for each lower level feat directory, and one row for each timepoint. This data is produced for each EV specified in the design.fsf file for each lower-level feat directory. A full report for each mask file is produced in one final output file.
Time window. Specifies the epoch surrounding each event that you want to look at. The times "before" and "after" are relative to the onset of the event. For various reasons, Peate does not take into account event durations from your stimulus files. For example, if you want to look from 10 seconds before each event onset to 30 seconds after event onset, enter 10 and 30. These times are always specified in seconds.
Interpolation. By default, Peate will interpolate your data to 1 second resolution. This helps if your events are not synchronized to the TR. As of version 1.65 Peate uses cubic spline interpolation by default, but you can choose to use the old-fashioned linear interpolation as well. Enter the final temporal resolution that your data should be interpolated to. Just make sure that it is evenly divisible into the TR. For exampe, if your TR is 2, your final temporal resolution cannot be .75 seconds. With spline interpolation, your data will look better at finer temporal resolutions as a smooth curve is fitted through the points. With linear interpolation a straight line is drawn from one point to the next so finer grained resolution will still look blocky.
If you choose not to interpolate, stimuli will be treated as if they start at the nearest TR.
OPTIONS
Baseline. Data output will be represented as a percent change from baseline. By default, Peate treats the average value during the window before each event as the baseline. So if you choose to look from 4 seconds before each event, the period from -4 to 0 seconds will count as the baseline. You may alternatively use the average value across an entire run as baseline, or to have the raw data output without scaling by a baseline.
Verbose. If this is checked, the program will output more information about what it is doing in the terminal window.
Plot. If this option is checked, Peate will generate a plot of your data using fsl_tsplot. One plot is generated for each mask file, with the average across feat directories for each EV plotted. The plot will open in a new window and will also be saved as a gif file.
Peaks. If this option is checked, the output file will also report which timepoint has the highest value for each lower level feat directory. Summary statistics show the average peak timepoint (not the peak of the average waveform).
Bypass design.fsf. If you do not want to use the stimulus timings that are specified in each run's design.fsf file, you can specify a text file that contains a list of alternate EV files. These alternate EV files should be in three column format.
Ignore blank EV files. When this option is checked, any EV files which are empty will be ignored. These will be given the value "NULL" in your output file and will not contribute to the grand mean. When this option is not checked, Peate will report an error when a blank EV file is encountered. If you are not intentionally using empty EV files, you should leave this option unchecked.
Runnning in Command Line mode
As of version 2.0, Peate can run off a configuration file instead of from the GUI. Advantages of this are that it may make Peate easier to invoke remotely with some configurations, and also you can rerun the same analysis or a similar analysis without having to set up all the options repeatedly. To do this, you first have to make a text file that contains all the information Peate will need to run. It should be in the format contained in this demo file. You may want to just copy the demo file and change the settings in that file. Make sure to name the file with the .pcf extension. Then to invoke peate in command line mode, pass the .pcf file to peate as a command line argument:
peate myconfigfile.pcf
Help
Questions, comments, etc.: email me at .