FMRI Data Management

From Poldracklab Wiki

We have developed a lightweight system for fMRI data management based on the MediaWiki software.

The goal of this project was the development and deployment of a system that provides the necessary means for data and project management with a minimum of overhead. There are a number of ongoing projects that are developing data management systems for fMRI laboratories, such as the XNAT project and BIRN. However, these systems generally involve substantial effort to configure and implement the software. Our goal was to implement a system that had a low barrier to entry for laboratories without a staff of dedicated programmers and system administrators. In addition, it is important to implement a system that requires relatively little training for users, since obtaining buy-in from lab personnel is an important aspect of any project management system.

With these concerns in mind, we developed a wiki-based system for data management with the following capabiilties:

1. Databasing of metadata from the original MRI images. After transfer of the data in DICOM format from the MRI scanner, the metadata from each DICOM file is placed into a database. This database is viewable from the web via a set of PHP scripts, but this database is not editable by users, in order that the original metadata remain unadulterated.

2. Wiki-based front end. The web site that serves as a front end to the database is based on the MediaWiki collaborative editing software platform. This open-source software project has been developed to support the Wikipedia online encyclopedia, and is built on top of the PHP programming language for creation of dynamic web pages and the MySQL open-source database platform. Several features of this software drove its adoption for the present project. First, the server software is relatively simple to configure and does not require substantial resources to administer. Once configured, users are able to edit pages in the system using a rich-text format (called “wikitext”) which is easily learned, though the system also allows use of a subset of HTML tags for greater control of page layout if desired. Third, because it is built on a cross-platform scripting language (PHP), the system runs on a broad range of software platforms including Windows 2000/XP, Mac OS X, Linux, and other UNIX platforms.

The python scripts for this project are distributed under the terms of the GNU General Public License.

System Configuration and Requirements

Although it is relatively easy to configure, using this system will still require some knowledge about how to use MySQL and a rudimentary knowledge of Python scripting (for the automatic wiki page creation) and PHP scripting (if you wish to use the PHP scripts to access the database directly). This software has only been tested on a Linux system but should work on any UNIX-based system for which the necessary software is available.

The following prerequisites must be installed:

• http://www.mysql.org MySQL] (tested using version 5.0.26)
• Mediawiki (tested using version 1.10)
  • Note: if you name the database as "projectwikidb" when you create the wiki, then it will save you one step below.
• python (tested using version 2.4.2)
• MySQLdb python module
• DCMTK (dicom toolbox, tested using version 3.5.2

Once those are installed and your mediawiki site is created and working, you should set up a namespace called "Subjects" in the wiki. This will be where all of the subject pages are placed, to separate them from regular pages. To do this, add the following to your LocalSettings.php file to create the namespace and to ensure that the Subjects namespace is properly searched:

$wgNamespacesToBeSearchedDefault = 
array(NS_MAIN           => true,
100               => true
);

$wgExtraNamespaces =
array(100 => "Subjects",
101 => "Subjects_Discussion",
);

Setting up the database

In order for the data to be placed into the database you first need to set up the proper tables. First, create a database called mri:

mysqladmin -u root create mri

You then need to create the tables for the database. Download create_mri_tables.txt and then use the following to create these tables in your database:

cat create_mri_tables.txt | mysql -u root -p -D mri

Once this is done you should be able to see the tables in mysql using show tables;.

Getting the data into the database

I have written a script that converts the DICOM header to XML (using the DCMTK program dcm2xml) and then creates SQL commands to insert this information into a database: dicom_to_xml.txt. You should rename it as dicom_to_xml.py and make sure that it is executable (chmod +x dicom_to_xml.py).

This script will need to be adapted to your local environment:

1. You may need to change the location of the python executable in the first line if it is not in /usr/bin/python on your system (type which python to find your local python executable).
2. The script is currently written to use the localhost as the mysql database server, and is missing the username and password information. You will need to set these to match your local database setup.
3. The script was written to accommodate data from a Siemens Allegra MRI scanner. It is possible that scanners from other vendors will require changes to the DICOM tags, which are defined in the session_tags variable.

Once the script is set up, you can try running it to see if it properly creates the database entry:

dicom_to_xml.py dicomdir

replacing dicomdir with the name of the directory containing the dicom files that you want to add to the database. The script will drill into the directory and find all DICOM files and add them to the database. It will probably take some tweaking and you may need to reinitialize the database while doing so, so I would do it on a test machine until you are sure that it is running properly with your datasets.

Creating the wiki pages

Once the data are in the database you can create a wiki page using the script: create_wiki_page.txt. As with the previous script, you should rename it as create_wiki_page.py and change the permissions to execute. You may need to make a number of changes for your local environment:

1. You may need to change the location of the python executable in the first line if it is not in /usr/bin/python on your system (type which python to find your local python executable).
2. The script is currently written to use the localhost as the mysql database server and the wiki server, and is missing the username and password information. You will need to set these to match your local database and wiki setup.
3. The script currently assumes that your wiki database is called "projectwikidb" - if you called it something different when setting up the wiki, then replace this with the name.

Once this is set up you should be able to use the command:

create_wiki_page.py subjcode

where subcode is replaced with the code for that particular subject (which by default is the subject name).

A note about privacy and confidentiality

Putting your subjects' data into a database means that they are potentially accessible to the entire world. I STRONGLY RECOMMEND that you do not include any identifying information in the records other than the code that you use to link names with data records, and that this linking information is not kept in the same database. This will ensure that even if there is a security breach, there will be no release of identifiable information.

It is also important that you ensure that your systems are secure (i.e. keep up to date on security patches) and that access to your wiki is password-protected. As befits its collaborative nature, the MediaWiki software is by default open to the world for reading and editing. To help secure the system, I would recommend adding the following to your LocalSettings.php file for the wiki:

$wgGroupPermissions['*']['read']            = false; 
$wgGroupPermissions['*']['edit']            = false;
$wgGroupPermissions['*']['createpage']      = false;
$wgGroupPermissions['*']['createtalk']      = false;
$wgGroupPermissions['*']['upload']            = false;
$wgGroupPermissions['*']['reupload']            = false;
$wgGroupPermissions['*']['reupload-shared']            = false;
$wgGroupPermissions['*']['minoredit']            = false;

$wgGroupPermissions['*']['createaccount']   = false;

$wgGroupPermissions['sysop']['createaccount']   = true;
$wgGroupPermissions['sysop']['read']            = true;
$wgGroupPermissions['sysop']['edit']            = true;

$wgGroupPermissions['approvedUser']['edit']            = true;
$wgGroupPermissions['approvedUser']['read']            = true;
$wgGroupPermissions['approvedUser']['createapage']            = true;
$wgGroupPermissions['approvedUser']['createtalk']            = true;
$wgGroupPermissions['approvedUser']['upload']            = true;
$wgGroupPermissions['approvedUser']['reupload']            = true;
$wgGroupPermissions['approvedUser']['reupload-shared']            = true;
$wgGroupPermissions['approvedUser']['minoredit']            = true;

$wgWhitelistRead = array( "Main Page", "Special:Userlogin" );

You should then create a group called "approvedUser" and add to that group anyone who you wish to have access to the system. And don't forget to back up your database regularly!