Cerebral Blood Flow Database and Analysis Pipeline (CBFDAP)


Introduction

The Cerebral Blood Flow Database and Analysis Pipeline (CBFDAP) is a web enabled data and workflow management system extended from the HID codebase on NITRC specialized for Arterial Spin Labeling data management and analysis (including group analysis) in a centralized manner.

Prerequisites

  1. JDK 1.6+ is necessary for HID web application which uses Java generics is a major Java language enhancement only available Java 5 (JDK 1.5) or later. The latest JDK available is recommended. (http://java.sun.com/j2se/downloads/)
  2. Apache Ant for build (1.6.x or later) (http://ant.apache.org/)
  3. Jakarta Tomcat servlet/JSP container (http://jakarta.apache.org/tomcat/ )
  4. Make sure your database is setup for CBFDAP web application
  5. The ASL processing requires MATLAB. The encrypted code for processing is provided in SVN.
  6. AFNI (tested on AFNI version AFNI_2010_10_19_1028)
  7. FSL (tested on FSL version 4)
  8. FreeSurfer

Preliminary Database Setup

Postgres Support
Postgres is the only supported RDBMS for CBFDAP. Use the latest Postgres db generation scripts available via; The instructions are in $SCHEMA_HOME/Postgres/db_objects/README file.

Quick Start Guide

Getting the source code from stratch

svn --username anonymous --password anonymous checkout https://www.nitrc.org/svn/cbfdap
Assuming, you have run svn checkout command in your home directory ($HOME), you will have a directory $HOME/cbfdap/clinical, which will be called $CBFDAP_HOME in the rest of this document.

Updating existing CBFDAP code base

in your $CBFDAP_HOME$ directory 
svn status
svn update

Build and Deployment

Copy $CBFDAP_HOME/build.properties.template to $CBFDAP_HOME/build.properties and edit the Tomcat installation directory information to point to your tomcat installation. In the example below Tomcat version 4.1.24 is installed in directory /data1/opt/tomcat-4.1.24. 
# The directory where your Tomcat application server is installed
tomcat.home=/data1/opt/tomcat-4.1.24
# servlet jar filename 
# In Tomcat v 5.x the servlet jar file is for some reason renamed
# from servlet.jar to servlet-api.jar. If you are using Tomcat 
# version 5.x use servlet-api.jar or servlet.jar for earlier
# Tomcat versions
servlet.jar.name=servlet-api.jar

# The web application name for your HID web app installation.
# For most cases the default will work fine.
webapp.name=cbfdap
In $CBFDAP_HOME, run for the first time build and deployment 
$ ant clean-all
$ ant bootstrap
$ ant
Check static data integrity
ant db-integrity-check
For subsequent code updates 
$ ant clean
$ ant

Post-built configuration

CDFDAP configuration data is persisted in the database. To bootstrap, first edit the provided sample $CBFDAP_HOME/config_params.xml to reflect your system. Set the environment variable CLINICAL_HOME to $CBFDAP_HOME. Then, cd to $CBFDAP_HOME/bin directory and run; 
./config_param_admin.sh ../config_params.xml
Next you need setup the protocols. The supported protocols are provided in the file $CBFDAP_HOME/protocols.xml. Then, cd to $CBFDAP_HOME/bin directory and run; 
    ./protocol_admin.sh ../protocols.xml
As the last step, you need to setup your scanners. First, please edit the provided sample $CBFDAP_HOME/scanners.xml to declare your scanner(s). Then, cd to $CBFDAP_HOME/bin directory and run; 
./scanner_admin.sh ../scanners.xml

Running Application

Startup your tomcat server 
$ ./$TOMCAT_HOME/bin/startup.sh
Point your browser to http://localhost:8080/cbfdap/

Once you logged in as admin user setup during the ant bootstrap step above, you need to setup experiment(s), upload and process ASL data. The usage of the system is documented at CBFBIRN main site.

There are also video tutorials available.

Detailed Configuration

Getting the code

svn --username anonymous --password anonymous checkout https://www.nitrc.org/svn/cbfdap
Assuming, you have run svn checkout command in your home directory ($HOME), you will have a directory $HOME/cbfdap/clinical, which will be called $CBFDAP_HOME in the rest of this document.

Build process

Copy $CBFDAP_HOME/build.properties.template to $CBFDAP_HOME/build.properties and edit using for Tomcat installation directory information 
# The directory where your Tomcat application server is installed
tomcat.home=/data1/opt/tomcat-4.1.24
# servlet jar filename 
# In Tomcat v 5.x the servlet jar file is for some reason renamed
# from servlet.jar to servlet-api.jar. If you are using Tomcat 
# version 5.x use servlet-api.jar or servlet.jar for earlier
# Tomcat versions
servlet.jar.name=servlet-api.jar

# The web application name for your HID web app installation.
# For most cases the default will work fine.
webapp.name=cbfdap

Build and Deploy

In $CBFDAP_HOME, run for the first time build and deployment 
       $ ant clean-all 
       $ ant bootstrap
       $ ant
One-time per CBFDAP web app release with database schema change bootstrapping, asks for site/user specific information to build a minimal users.xml file to connect to your database and configure your web based user/database/application configuration with sensible default values.
For later updates 
       $ ant clean 
       $ ant
ant clean-all removes everthing deployed under $TOMCAT_HOME/webapps/cbfdap and also deletes every generated configuration file to start from scratch ant clean removes the compiled java classes, properties files and the struts-config.xml file.

Post-built configuration

CDFDAP configuration data is persisted in the database. To bootstrap, first edit the provided sample $CBFDAP_HOME/config_params.xml to reflect your system. Set the environment variable CLINICAL_HOME to $CBFDAP_HOME. Then, cd to $CBFDAP_HOME/bin directory and run; 
./config_param_admin.sh ../config_params.xml
Next you need setup the protocols. The supported protocols are provided in the file $CBFDAP_HOME/protocols.xml. Then, cd to $CBFDAP_HOME/bin directory and run; 
    ./protocol_admin.sh ../protocols.xml
As the last step, you need to setup your scanners. First, please edit the provided sample $CBFDAP_HOME/scanners.xml to declare your scanner(s). Then, cd to $CBFDAP_HOME/bin directory and run; 
./scanner_admin.sh ../scanners.xml

Running web user interface

  1. Start Tomcat 
    $ $TOMCAT_HOME/bin/startup.sh
  2. open a browser (Netscape (4.7 and higher/Mozilla 1.0.2 or higher or Internet Explorer 5 and higher ) and type http://localhost:8080/cbfdap/
  3. Stop Tomcat 
    $ $TOMCAT_HOME/bin/shutdown.sh

Setting up dependencies for the CBF workflows

The core of the individual and group CBF processing workflows are implemented in MATLAB. The encrypted MATLAB code is under the $HOME/cbfdap/matlab directory and needs to be put under /data directory on your system. 

cp -r $HOME/cbfdap/matlab /data

Besides AFNI, FSL and Freesurfer, the other dependencies are located under the CBFDAP_HOME/dependencies directory. You need to copy them to the /usr/local/bin directory and make the scripts executable.

  1. gr (for GE P-files) executables
  2. rdgehdr executable
  3. dicomrx (You can get it from http://cfmriweb.ucsd.edu/fmap) executable
  4. imseq (Perl script)
  5. d2afni_hid (C-shell script)

The paths in the perl scripts (asl_prep_cbfbirn.pl, do_B0_mosaic_cbfbirn.pl and gr_wrapper.pl and C-shell script d2afni_hid need to be modified based on your AFNI, FSL and Freesurfer installation directories.

Building the Javadoc documentation

Run 
$ ant javadoc
After that, point your browser to $CBFDAP_HOME/doc/api/index.html

Downloadable data object types setup (Advanced)

If you want to change and/or add new downloadable object types for CBFDAP web app download functionality, the types of data objects that will be downloadable can be configured by 
           ant data-object-type-config
This custom ant task allows the addition/deletion and listing of dataobject types supported by the application. For most usage scenarios, this needs to be done only once. After this, tomcat server needs to be restarted.

Securing your Web Server

HTTPS setup for Tomcat(Necessary to avoid eavesdropping, man in the middle attacks)

SSL Configuration for Tomcat Servlet/JSP Container as as standalone web server

Create a self-signed certificate valid (say ) for 400 days with a password value of "changeit" for both the certificate and the keystore itself. The following command using Sun JDK tool keytool will both create a keystore in $HOME/.keystore file and add a self-signed certificate with alias tomcat to it. 
  keytool -genkey -alias tomcat -validity 400 -keyalg RSA
Edit your $TOMCAT_HOME/conf/server.xml file for HTTPS support as indicated in SSL Configuration for Tomcat 5.0/6.0.

Important: Also comment out the Connector for port 8080 in your server.xml file so that your tomcat only serves via HTTPS protocol.

After that start your tomcat and point your browser to https://localhost:8443/ for test.

Adding server certificate to truststore (on the client side)

Prepare a truststore for secure remote clients (like web services clients (currently onl XCEDE export client) and security admin client
  1. export the RSA certificate with alias tomcat from the keystore of the server machine 
          keytool -export -alias tomcat -file tomcat.cer
  2. import the RSA certificate into your security client's truststore. Every security client needs to access to a local truststore containing trusted server's certificate. The truststore is only needed if you self sign your certificate. The default truststore for your Java installation where the client program will run is named cacerts and usually located under $JAVA_HOME/jre/lib/security/cacerts You need to add the exported certificate tomcat.cer into the default truststore for encrypted access to Apache Axis web service engine running inside the deployed HID web app. 
          keytool -import -alias tomcat -keystore $JAVA_HOME/jre/lib/security/cacerts -file tomcat.cer
    When asked `Trust this certificate?`, enter Yes. You may need temporarily give write permissions to the truststore file.

Contact Information

For any questions, comments, bug reports contact I. Burak Ozyurt (iozyurt@ucsd.edu)