fBIRN Image Processing Stream

fBIRN Image Processing Stream (FIPS)

This web page describes the fBIRN Image Processing Stream (FIPS). FIPS is currently a set of scripts that wrap around FSL
and interact with the fBIRN data hierarchy.

Workflow Overview

1. Download and install Local Upload scripts
2. Download and install FIPS
3. Upload dataset to local hierarchy
4. Build local FIPS database
5. Import stimulus schedule files (if needed)
6. Create FLAC
7. Perform First Level Analysis
8. Rebuild local FIPS database
9. Visualize

When uploading/analyzing more data, repeat steps 3-9 (excluding 6).

Submitting Bug Reports

If you do not want your bug report ignored, it is important to provide enough information in your report. This includes:
1. The command you ran exactly as you ran it with ALL the command-line arguments.
2. ALL the screen output (including the error)
3. The operating system you are using.
4. Submit bug reports to birn-func-image-AT-nbirn.net (where "-AT-" is replaced with "@")
remember: nothing will get your bug report deleted faster than being vague!

Local fBIRN Upload Script

Before you can use FIPS, you must import your MRI data into the fBIRN hierarchy using the Local fBIRN Upload script written by Dave Keator. This can be obtained from the SRB at /home/dkeator.uci-bic/LocalHumanUploadScripts/LocalHumanUpload_v1.XX.tar.gz, where XX is the version number. Download, untar, and follow the instructions.
You will be required to create an XML upload configuration file. (example). It is VERY important that you configure this XML file correctly. This file contains tags that identify where your data will be found in the hierarchy. If you do not specify these parameters correctly, you may have trouble finding your data.

The fBIRN Hierarchy

The fBIRN hierarchy is a convention which specifies a the structure and naming of directories and files such that each data set is assured to be stored in a unique location which can be found later on. This structure will exist on your local network. At some point, it will also exist on the SRB. The directory structure itself consists of 9 directory levels at the bottom of which are SPM-style ANALYZE_7.5 files that take the name f0001.img, f0002.img, etc (one for each frame). In each image directory, there is a file called ImageWrapper.xml. This is the descendant of the BXH file and has all kinds of information about the image. There is also a file called fips-process.xml which has information about the location of the data in the hierarchy (eg, project, paradigm, series, etc).

The hierarchy will reside on your local network under a directory pointed to by the LOCAL_SRB_HOME_BIRN environment variable (see The FIPS Environment below). Though this is the root of the hierarchy, the image data itself does not necessarily have to be physically located on the same disk as the root (such an arrangement would cause this disk to fill up very quickly). The upload script has the ability to store the actual data in any directory on any disk and then symbolically link to the hierarchy. The script to import the data to your local hierarchy is called LocalHumanUpload.sh. This is not part of FIPS and must be downloaded and installed separately (see Local fBIRN Upload Script above). Run the upload script as follows:

LocalHumanUpload.sh DataSrcDir XMLConfigFile TargetDir LocalRootDir

where DataSrcDir is the directory where your source images in your native format are located, XMLConfigFile is the XML configure file that specifies where in the hierarchy your data will go, TargetDir is the directory where the actual data will be stored, and LocalRootDir is the root of your hierarchy (ie, LOCAL_SRB_HOME_BIRN). If you look in TargetDir, you will see a complete hierarchy with the actual image data files at the bottom. If you look in LOCAL_SRB_HOME_BIRN, you will see the same hiearchy, but there will be symbolic links at the series level pointing to the actual data in the TargetDir.

FIPS Download and Installation

Download FIPS. This is a (very small) tarfile. To install:
cd somedirectory
tar xvfz fips.tar.gz
add somedirectory/fips/bin to your path.

The FIPS Environment

The FIPS Environment is defined by three environment variables which must be present in your ~/.fipsrc ( example):
LOCAL_SRB_HOME_BIRN -- root of the local copy of the SRB
MY_FIPS_DIR -- location to store the local database
FIPS_FLAC_DIR -- location to store your FLACs

All the image data are stored under LOCAL_SRB_HOME_BIRN, either directly on the disk or symbolically linked to other disks. The data must exist in a certain hierarchy. This hierarchy is created by the Local Human Upload script written by Dave Keator.

The files in the FIPS_FLAC_DIR are important and hard to replace (eg, after a disk failure). Since they will not require very much space, it is a good idea to put your FIPS_FLAC_DIR in a place where it will be backed up regularly. Also note that it is not necessary for each user to have his/her own FIPS_FLAC_DIR. In fact, many users may want to share a single FIPS_FLAC_DIR in order to have access to each other's FLACs.

The FIPS Database

After you have performed a local upload of (at least) one data set, you can create the local FIPS database. This is done by running fips-build-db (no arguments needed). This will create two files in MY_FIPS_DIR: fips.database.dat and fips.database.html. Point your browser to fips.database.html to see a summary of the data in your database. ( example ) The summary will consist of a table with 11 columns. Each row represents a run/series, either raw or analyzed. Most of the columns uniquely indicate where the data set falls in the fBIRN hiearchy. The source of this information is the XML configuration file used when uploading/importing the data (so it is important that this information is correct!). Where applicable, the relevant XML tag is indicated. Each column has the following interpretation:

Nth - row number. Changes as you add more data.
Project - Project Name (tag: project), eg, fBIRNPhaseII
BIRNID - BIRN unique subject ID (tag: BIRNID), 00042105
Site - Acquisition Site Id (tag: acquisitionSiteID), eg, 0006
Study - Study Name (tag: study/name),eg, bay4-trio
Visit - Visit Id (tag: visit/ID), eg, L0001
Type - structural or functional (tag: series/type)
Paradigm - experimental paradigm (tag: series/paradigm), eg, breath_hold
Run - run number within the paradigm (tag: series/number), eg, 2
Analysis Level - level of analysis, eg, none, FirstLevel
Analysis Name - name of the analysis, eg, none, SIRP-FWHM5

You will use these parameters to identify the data you want to access, analyze, and visualize inside of FIPS. There are a couple of tags that FIPS will assume to be fixed. These are study/ID (which should always be "L0001") and visit/name (which should always be "Visit"). I assumed this because I could not figure out what these tags do. Also, it is assumed that the Project Name is always redundant with the Project ID (tag: project/ID). If these tags need more flexibility, we'll have to add columns to the database.

Unless the data have been analyzed in some way, the Analysis Level will always be "none" indicating that it is raw data. The Analysis Name will indicate the format of the data (eg, ANALYZE_7.5). Clicking on the Analysis Level link will an XML file describing the data. If the data have been analyzed, then Analysis Level will be FirstLevel indicating a first level functional analysis (see fips-fla). Clicking on the link will bring you to the FSL report. The Analysis Name will be the name First Level Analysis Configuration (FLAC), and clicking on the link will show you the contents of the FLAC file.

You must rebuild the database after each upload to have it reflected in the database. This is done by running fips-build-db (no arguments needed).

Creating a First-Level Analysis Configuration (FLAC)

The FLAC describes how the data will be analyzed, including preprocessing, hemodynamic modeling, stimulus scheduling, nuissance variables, and other general linear model related parameters. In FIPS, all these parameters are gathered together before you actually analyze any data. This parameter set is generally referred to as the "FLAC". Note that the FLAC is defined once for a given paradigm regardless of how many runs, subjects, or visits of data for that paradigm are collected. The FLAC is independent of any given data set. Currently, the FLAC is configured using the FSL Feat GUI. While the FLAC is independent of any particular data set, Feat requires that a template data set be present. Within FIPS, the FLAC is configured with the fips-fla-config script:

USAGE: fips-fla-config

 --flac FLACName : name of the FLAC to be created
 --paradigm    name : must match upload
 --projectname name : must match upload

 fMRI Data Template
 --birnid      id   : BIRN subject ID
 --siteid      id   : acquisition site
 --visitid     id   : eg, L0001
 --studyname   name : eg, bay4-trio

Other arguments

 --visitname   name : default is Visit
 --studyid     id   : default is L0001
 --version        : print version and exit
 --help           : print help and exit
 --debug          : turn on debugging

The FLACName is the name by which the FLAC will be referred to in later stages of processing. This is the name that will appear in the FIPS database. The "fMRI Data Template" is a data set that already exists in your local repository that will be used as a template. The paradigm and projectname are as specified during upload (and as found in the FIPS database).

Note: due to an FSL restriction, it is not allowed to have any dots (ie, ".") in the name. Eg, "breath_hold" is ok, but "breath.hold" is not.

When this script is run, the template data is copied into a temporary directory along with any stimulus schedule files, and the Feat GUI is run. See the Feat Home Page for help on Feat. Under the "Data" tab, hit the button labeled "Select 4D data". When you browse the current directory, you should see one file: "f.hdr". Select this file. Then specify all the processing options, modeling parameters, and contrasts. DO NOT RUN THE ANALYSIS! . Save the configuration in the current directory as "design.fsf", then Exit. The design.fsf will be copied to FIPS_FLAC_DIR/projectname/FLACName. The temporary data will be deleted. Again, remember that the FLAC is defined once for a given paradigm regardless of how many runs, subjects, or visits of data for that paradigm are collected.

Note: the Feat GUI will display the TR as 3 sec. This is unimportant as FIPS (fips-fla) will automatically detect the TR of the source data set and set it appropriately before it runs the analysis.

If you want to analyze the same data in a slightly different way (eg, change the level of spatail smoothing), then create a new FLAC with the net set of analysis parameters.

IMPORTANT: if you are using stimulus schedule files, then you must import them BEFORE configuring the FLAC! See Importing Stimulus Schedule Files below. These files will automatically be copied into the temporary directory. To specify them in the Feat GUI, Stats->FullModelSetup->BasicShape and select "Custom (3 column format)". Then enter the name of the schedule file in the "Filename" entry box (or browse for it in the current directory). This must be done separately for each schedule file (a different EV for each one).

NOTE: you do not have to rebuild the database after making a FLAC.

First-Level Analysis

Analyze the data using fips-fla:

USAGE: fips-fla

 --birnid      id     : eg, 00042105
 --siteid      id     : eg, 0006
 --projectname name   : eg, fBIRNPhaseII
 --visitid     id     : eg, L0001
 --studyname   name   : eg, bay4-trio
 --paradigm    name   : eg, sensory_motor

 --flac FLACName : name of the FLAC as created with fips-fla-config

Other arguments

 --run         nthrun : default is to do all runs
 --visitname   name   : default is Visit
 --studyid     id     : default is L0001
 --overwrite          : overwrite analysis if it exists
 --version            : print version and exit
 --help               : print help and exit
 --debug              : turn on debugging

Again, the arguments indicate which data set to analyze and which FLAC to use. This script will find FLAC and the input data in the hierarchy, copy them into the same location, then use FSL's Feat to analyze them. This includes motion correction, spatial smoothing, fitting the GLM, performing inference, clustering, and registering to "talairach" space. It will also re-slice the results into talairach space. The resulting directory and naming structure is just that used by Feat. One exception is that a file called fips-process.xml is added. This contains all the fBIRN-related hierarchy information so that it can be idenfified in the database.

IMPORTANT: if you are using stimulus schedule files, then you must import them BEFORE running the first level analysis! See Importing Stimulus Schedule Files below.

IMPORTANT: after running fips-fla, you must rebuild the database before it will the new results will show up in the summary file. To rebuild the database, simply run fips-build-db (no arguments needed).

Importing Stimulus Schedule Files

For some fMRI analyses, you will want to specify a stimulus schedule, ie, when each stimulus is presented and for how long. The schedule is represented with a three-column text file as used by FSL. The first column is the time of stimulus onset. The second column is the duration of the stimulus. The third column is a weight (use 1 unless you know what you are doing). Each event type gets its own file. Here's an example for the SIRP load 3 probe. Note that time=0 is the time of the first image stored in the functional volume. If there are frames that will be discarded, then time=0 INCLUDES these frames. Depending upon the paradigm, you may need to create different schedule files for every subject, visit, run, etc. Once you have created the schedule files, they will need to be imported into the hierarchy. This is done with the fips-import-sched script. When you run it without arguments, you will see:

USAGE: fips-import-sched

 --birnid      id
 --siteid      id
 --projectname name
 --visitid     id
 --studyname   name
 --paradigm    name
 --run         nthnumber

 --sch shedulefile <--sch shedulefile ...>

Other arguments

 --visitname   name : default is Visit
 --studyid     id   : default is L0001
 --overwrite      : overwrite schedule if it exists
 --version        : print version and exit
 --help           : print help and exit
 --debug          : turn on debugging

You will notice that most of the arguments correspond to the columns in the table of the FIPS database. This is how you indicate which data set your schedule files belong to. Here's an example:

fips-import-sched --birnid 00042105 --siteid 0006 
  --projectname fBIRNPhaseII --visitid L0001
  --studyname bay4-trio --paradigm sternberg_item_recognition
  --run 2 --sch encode.stf --sch probe.stf

This will find the given dataset, create a directory in the hierarchy, and copy the schedule files (encode.stf and probe.stf) into that directory.

IMPORTANT: the schedule files should be named in a way that is independent of any particular data set or run. For example, if one were to import the schedule for run 3 above, you would only change "--run 2" to "--run 3". The names of the schedule files would still be "encode.stf" and "probe.stf" (though their content may change). If one uploads the schedules for a different subject, then only "--birnid 00042105" would change.

A Note on the Orientation of the Volumes

FSL requires that the functional volumes be in a "Left-Handed" coordinate system. This is the same as "strict" Radiological convention. Note that "Radiological" here means more than just reversal of left and right. "Strict Radiological" puts strict constraints on all the axes, not just left-right. If the data are not in "strict radiological" convention, then there will be a left-right flip after the volume is resliced into standard space. To prevent this, FIPS automatically detects whether the functional data are Left-Handed or Right-Handed. If Right-Handed, the data are reoriented (flipping A-P). The Handedness is determined from the orientation/direction cosine information in the ImageWrapper.xml file with the original data.

Viewing the First-Level Analysis

There are five ways to view the results from the first level analysis. First, one can click on the "FirstLevel" link in the FIPS database html file. This will take you to the FSL report page.

Alternatively, one can run the fips-view script to view the results using
fslview
AFNI
slicer
tkmedit

fips-view takes the same arguments as fips-fla and, in addition, requires that a run be specified with --run.

For afni and slicer, fips-view simply cds into the directory where the data are and runs the program. The user is required to load the images to be viewed. See here for some basic slicer instructions. For fslview and tkmedit, one can also choose the space. Native refers to the native functional space. mni152 refers to the Montreal Nuerological Institute average of 152 brains (this is what is used by FSL). For fslview, all of the zstat images are loaded. For tkmedit, zstat1 is loaded. A different statistical image can be loaded with --stat.