This page contains an annotated list of software program files written at the Waisman Brain Imaging Lab for analyzing fMRI data. Many of these programs were written to compare software tools (AFNI, AIR, FSL, SPM, VoxBo) using human and phantom data.
A variety of languages were used, including Matlab, IDL, C, Perl, and Python. In general, each language had a specific use:
- Matlab: control SPM2 and fmristat analyis.
- IDL: Create phantoms and run associated analysis.
- C: Interact with AIR programs.
- Perl: Top-level scripting and batch analysis (early efforts).
- Python: Top-level scripting and batch analysis (later efforts).
The directory names in this document assume an unspecified top-level directory. When the programs were created, the top-level directory was:
/study/fMRI_tools/software/
The unspecified directory should facilitate copying the programs to other locations while maintaining the same organization of the subdirectories.
If you would like to download any of these software programs, please email Terry Oakes at: troakes - at - wisc - dot - edu
Abbreviations:
- mc - Motion Correction
- bch - batch (i.e. batch-processing a number of similar data sets)
- phant - phantom (artificial data set)
- block - block design (also referred to as "N-back")
- event - event-related design (also referred to as "Go/NoGo")
- nbk - N-back design (also called "block)
- gng - Go/NoGo design (also called "event")
- roi - Region of Interest
Descriptions
Text-files with alternative descriptions which may augment what you see on this page.
- kw_perl_and_matlab_script_descriptions.txt
- Kathleen's description of her conventions for naming the various programs needed to call each of the tools. Some of the conventions are specific to older versions (SPM2) or for specific environments which, at the time, only existed on a single computer (e.g. "brazil").
- kw_script_description.txt
- Kathleen's description of the IDL programs she wrote.
Analysis programs
The programs are categorized by language (C, matlab, IDL, Perl, Python).
C programs
The few C programs are for using AIR.
- manual_reslice_noask.c
- Allows user interactive reslicing of a file. Pitch, roll, yaw, x-shift, y-shift, z-shift, x-scale, y-scale, and z-scale can all be specified. The output can be an initialization file, a .air file, or a resliced file.
- This program was modified by Terry Oakes at UW-Madison Lab for Affective Neuroscience to prohibit the program from asking the user a series of questions regarding the parameters. Instead, the user supplies the parameters as part of the command line, and this program performs the indicated tasks without asking any further questions.This modification makes it suitable to call from another program, so you can specify shift, roll, etc. and reslice an image using those parameters.
- flirt2air.c
- Dr. Roger Woods kindly provided this program to aid in comparing results from FSL's FLIRT with Dr. Woods' AIR program. The program converts a transform matrix obtained from FLIRT to an AIR-formatted "*.air" file.
- I have not checked this program lately, and I wouldn't be surprised if it was sensitive to changes in file formats due to new software releases. Additional documentation is provided as comments within the source-file.
IDL programs
Mostly for phantom creation and analysis. See the file, ".../idl/kw_scripts/kw_script_description.txt" for additional details.
- fmri_phant_block.pro
- Wrapper for "fmri_phantom.pro", an object-oriented program that creates a digital fMRI phantom. This program sets up specific inputs and parameters for a vlock design, and calls the program.
- fmri_phant_event.pro
- Wrapper for "fmri_phantom.pro", an object-oriented program that creates a digital fMRI phantom. This program sets up specific inputs and parameters for a vlock design, and calls the program.
- mcII_phant_activations
- Convolve HRF with phantom activation time array.
- tools_get_rois.pro
- Extract ROI values from fMRI phantom(s). Specifies which files are examined.
- Different groups of phantoms (e.g. normal, accurate, or fast motion correction parameters) may be specified by changing the top-level directory. Specific coordinates are specified, corresponding to the center of each of the created activation clusters. The data resulting from MC for each of the tools is analyzed.
- There are several exceptions hard-coded in place, where some data are missing or redundant.
- Results are printed to an Excel-compatible text file.
- tools_get_rois_?.pro
- This is a series of analysis programs, numbered 1-6 (in place of the wildcard "?" symbol), which perform more focused, less comprehensive analysis than the more general "tools_get_rois.pro" described above.
- These programs concentrate on a particular tool or phantom, but they all yield results formatted similarly.
- tools_mc_analyze_rot_phant.pro
- Analyze "spike" data from rotated (resliced) phantom data.
- This is a specialized program to analyze an image volume containign 9 discrete points with value=1000.0 and the remaining points are 0.0.
- Each of several motion- correction tools (AFNI, AIR, FSL, SPM2) were used to reslice the volume using specific parameters (2mm rotation, 2mm translation in each dimension) and to reslice the volume creating a new output volume using each of several interpolation methods (e.g. sinc, trilinear, etc.). The analysis does not assume a particular location for each point, since due to different reslice algorithms the maximal point may be slightly different. A region surrounding the expected point is searched and several descriptors are calculated.
- tools_readmotion.pro
- For fMRI_tools study, given a subject and task, will output a structure containing the motion paramaters produced by each software package
- tools_readmotion_AIR.pro
- Read motion parameters from a series of AIR termination files, write them out to a more understandable text-file.
- This is a lower-level helper program.
- tools_readmotion_phant.pro
- For fMRI_tools study, output a structure and optionally display a plot of the motion paramaters produced by each of 5 software packages for a given fMRI synthetic data series (phantom).
- tools_extract_roi.pro
- extracts data from a statistical map based on a given mask/roi.
- Example: M=tools_extract_roi('mask name', 'image name', THRESH=2.86
- tools_roi_stats.pro
- Given an array of data from tools_extract_roi, prints stats to a text file.
- Returns a structure as follows:
- statsS = structure containing the statistics produced
- statsS.Num = number of subjects in multilevel analysis
- statsS.Clust = string name of mask used to get the cluster
- statsS.Tool = tool of interest
- statsS.Maximum =(absolute) max value of cluster
- statsS.MaxLoc = 3d array of x, y, z location of statsS.Maximum
- statsS.Avg = mean vaulue of cluster
- statsS.AvgTop5 = mean value of top 5% of voxels in cluster
- statsS.Med = median value of cluster
- statsS.NumVox = number of voxels in cluster
- Example: Stats=tools_roi_stats(S, /WRITE)
- bch_mc_gng_roi_stats.pro
- Wrapper for "tools_extract_roi.pro", "tools_roi_stats.pro", for data sets from motion corrections from multiple tools.
- bch_mcIIRevision_gng_roi_stats.pro
- Version of "bch_mc_gng_roi_stats.pro" tailored for Go/NoGo task.
- bch_mcIIRevision_nbk_roi_stats.pro
- Version of "bch_mc_gng_roi_stats.pro" tailored for N-Back task.
- bch_gng_motion.pro
- Wrapper for calling "bch_mc_gng_roi_stats.pro" multiple times- Go/NoGo task.
- bch_gng_motion.pro
- Wrapper for calling "bch_mc_gng_roi_stats.pro" multiple times- N-back task.
- cw_plot_multi.pro
- GUI program to plot and interact with multiple plots of similar data. This program was quite helpful to compare the numerous plots created across tools for each of the different pantom and human data sets.
- Originally written to plot one set of related time-series data from a single subject in the same plot, and additionally to create multiple plots, one for each of a series of subjects, in the same window.
- Tools are provided for sending the results to a printer etc.
- Input: An array containing the data you wish to plot. Can handle multi-dimension array. Here are the rules:
- 1D aray: a simple plot is created.
- 2D array: Multiple arrays are put into the same single plot. Data should be ordered as: [num_pts, num_vars].
- 3D array: Multiple arrays are plotted in each plot-instance using OPLOT, and multiple plots are created. Data ordered as: [num_pts, num_vars, num_subjects]
- idl_init.pro
- Initialization for IDL using UNIX, linux, and Windows. Adds variable and functions used by Spamalize and called by the various fmri-tools programs, and sets up system variables so display works correctly.
Perl programs
During the course of this work we moved from using Perl to Python for most of our scripting needs. Few of the Perl scripts were migrated to Python. The (older) Perl programs worked fine when we last used them, but we haven't checked them since, or updated them at all.
- air_run.pl
- Script to use AIR to coregister a series of image files to a single target file. All of the .img files in the current directory (where you are when you call this program) are coregistered, in series, to a target file.
- You must edit this file to change the name of the target file (line 17). You can also change the AIR thresholds (-t1, -t2) on line 52.
- tools_air_to4d
- Converts air *.img, *.hdr 3d files to a single 4d file.
- tools_motion_correct_fsl_040309.pl
- Performs batch motion correction for the fMRI_tools grant, using the FSL motion correction program mcflirt.
- Motion corrected files are put in the /study/fMRI_tools/analysis/fsl/XXX/TASK/TASK_N/mc directory.
- The script appends a log, including start and end times, in the tools_motion_correct.log in the /study/fMRI_tools/analysis/fsl/ directory. This is an early version of the similarly named programs below.
- tools_fsl_mc_phantom.pl
- This script performs batch motion correction for the fMRI_tools grant, using the FSL motion correction program mcflirt. Motion corrected files are put in the /study/fMRI_tools/analysis/fsl/XXX/TASK/TASK_N/mc directory. The script appends a log, including start and end times, in the tools_motion_correct.log in the /study/fMRI_tools/analysis/fsl/ directory.
- tools_fsl_mc_acc_phantom.pl
- This script performs batch motion correction for the fMRI_tools grant, using the FSL motion correction program mcflirt. Motion corrected files are put in the /study/fMRI_tools/analysis/fsl/XXX/TASK/TASK_N/mc directory. The script appends a log, including start and end times, in the tools_motion_correct.log in the /study/fMRI_tools/analysis/fsl/ directory. This program is tailored for the "acc" or "accurate" mc parameters.
- tools_phant_get_clusters.pl
- Extract ROI information from activation clusters in mc phantom data.
- Prints a summary for each cluster, for each tool, for a variety of phantoms, including: design, noise level, motion level, method, tool, cluster, mean, min, max.
- tools_spm_phant_folders.pl
- Rename SPM folders and files to conform to conventions used by other fMRI-Tools programs.
- tools_voxbo_mc_phantom.pl
- Run the motion correction analysis for VoxBo(1.6).
- Must be run on a computer which has VoxBo and IDL installed, which for the Waisman Lab is BRAZIL.
- tools_voxbo_phant2Tes
- Converts phantom data ANALYZE-7.5 formatted files to VoxBo tes files.
- Must be run on a computer which has VoxBo and IDL installed, which for the Waisman Lab is BRAZIL.
- tools_voxbo_vb2imgs_phant.pl
- Converts realigned *.tes image files back to ANALYZE-7.5 for GLM analysis.
- Must be run on a computer which has VoxBo and IDL installed, which for the Waisman Lab is BRAZIL.
- tools_afni_mc_phant.pl
- Runs afni's 3dvolreg to motion correct the phantom for mc study
- tools_afni_mcII_phant.pl
- Runs afni's 3dvolreg to motion correct the phantom for mcII study
- bch_mc_gng_roi_stats.pl
- bch_mc_nbk_roi_stats.pl
- Wrappers for "avwmaths", "avwstats" to extrat ROI information form predefined activation clusters.
- For each group, tool, method, cluster, the program prints out the number of voxels, and the cluster volume.
- mc_afni_gng_def.pl
- mc_afni_gng_acc.pl
- mc_afni_gng_fast.pl
- mc_afni_nbk_def.pl
- mc_afni_nbk_acc.pl
- mc_afni_nbk_fast.pl
- Performs batch motion correction using the AFNI motion correction program "3dvolreg". There are 6 variations which call AFNI MC with the default, accurate, and fast parameters, for both the gng and nbk data.
- mc_afni_gng_acc_rms.pl
- Check AFNI motion estimate file existence, readability.
- mc_fwhm.pl
- Wrapper for "`3dFWHM", to estimate smoothness for a series of image files.
- mc_voxbo.pl
- Runs the motion correction analysis for VoxBo(1.5).
- tools_voxbo_mc.pl
- Creates the .tes files for voxbo Motion correction analysis. Convert .tes files to a folder of 3d analyze files. then convert to 4d analyze.
- tools_voxbo_mc_tes_convert.pl
- Creates the *.tes files for voxbo Motion correction analysis. Convert AFNI to a folder of 3d Analyze files, then convert to *.tes files and remove the analyze files after using the task_st+orig.BRIK files and 3dAFNItoANALYZE command
Python (higher-level scripts for calling other analysis programs):
AIR wrappers
- invert_air.py
- Invert an AIR transform matrix, apply it to an image to undo a transform.
- Used for transforming a mask made in template space back to the image's native space by inverting the transform used to move the original image into template space.
- params_4_air.py
- A text-file listing the MC parameters used for AIR for default, fast, and accurate settings. This is not a python program.
- tools_mc_phant_air.py
- Perform motion correction on fMRI-Tools phantom data using AIR.
- tools_motion_correct_air.py
- Perform motion correction on fMRI-Tools human data using AIR.
- tools_mc_write_air_params.py
- Write file of AIR mc params for every subject, task in fMRI Tools study.
FSL wrappers
- bet_imgs.py
- Apply BET to extract brain from a series of images. A wrapper for "image_manip.bet_batch".
- coreg_applyFSLmat.py
- Apply coreg transforms generated by FSL's FLIRT to another set of images. This program provides a wrappper to use FAST on a series of images.
- fast_imgs.py
- Batch-script to apply FAST to correct inhomogeneity artifact in a series of brain images.
-
fMRI tools-specific programs:
- bch_mcIIRevision_gng_roi_stats.py
- bch_mcIIRevision_gng_roi_stats_g33.py
- bch_mcIIRevision_nbk_roi_stats.py
- bch_mcIIRevision_nbk_roi_stats_g33.py
- Gets mean t for each processing pathway for each roi for the mcII Revision. Applies threshold only in proper (+ve or -ve) direction and saves t-stats with positive sign for all clusters. Wrapper for "avwmaths", "avwstats". The "g33" indicates a custom path from a subgroup of 33 subjects.
- tools_copy_mc.py
- Copy data from one directory to another, for all subjects in a study.
- Maintains dircotry structure of subdirectories. Checks for existence of each direcoty, sets permissions so tothers can read adta when complete.
- tools_make_tarfile.py
- Make tar-file(s) for fMRI Tools WINTER data set.
- Creates 4-5 seperate tarfiles with approximatel 10 subjects in each one, to make each tarfile a suitable size for distribution.
Utilities for image processing
- cleanup_files.py
- Clean up (delete) files from multiple subject directories.
- You provide an example filename with wildcards in the directory for the subject number, and this program will iterate through all matching directories and delete the matching files.
- It is prudent to call this program with "rollcall=1" to check for the files that will be deleted, without actually deleting them. Used this way, the program can check for the existence of similarly named files in a directory tree.
- convert_32float_16int.py
- Convert ANALYZE file from 32-bit FLOAT image file to 16-bit INT with a scaling factor.
- find_missing_files.py
- Given a list of subject directories, identify the directories which are missing a specific named file (which is expected to be there).
- mask_imgs.py
- Apply mask(s) to series of image files.
- A binary image is used to mask a corresponding image. Zero-valued pixels in the mask images are set to zero in a copy of the desired input image file.
- This program uses FSL's "avwmaths" program. Alternatives include AIR's "binarymask".
- The input parameter may be a single file, a list of files, or a directory.
- rot_img_files.py
- Rotate/flip one or more image files.
- Use this program to rotate or flip an image from how it is currently stored so that it has a better initial alignment with a target image for coregistration.
- Basically a wrapper for "image_manip.rot", and provides a good example of how to interface with the modules in that library.
Coregistration scripts
- convert_MRI_2_anlz.py
- Top-level script to convert data from post-reconstructed format to ANALYZE format.
- This program is designed to interact with an Excel-generated text file describing all of the scans etc. in a study.
- coreg_EPI_2_MRItemplate.py
- Coregister a partial-brain EPI scan to an MRI template. Steps are as follows:
- Coregister coplanar image to subject's MRI image
- Coregister MRI image to MRI template.
- Cumulate transforms, reslice original EPI and coplanar and T1 MRI template.
- Coregistered data will be written to directory containing MRI image.
- coreg_MRI2template.py
- Skull-strip, coregister, bias-correct and segment a MRI T1 image to a MRI template in MNI space.
- coreg_PETs_2_MRItemplate.py
- Coregister a series of PET dynamic scans to an MRI template.
- Steps are as follows:
- Convert all images to ANALYZE, if needed.
- Extract sum-images of first 30 minutes of dynamic PET scans.
- Realign all PET images to first image in list.
- Create mean image of all realigned images
- Realign all PET images to the mean.
- Make a new mean image from fruits of step 3.
- Coregister mean PET (from step 4) to subject's MRI image
- Coregister MRI image to MRI template.
- Cumulate transforms, reslice original PET dynamic files to MRI template.
- Coregistered data will be written to directory containing MRI image.
- coreg_rhesus_2_template.py
- Coregister rhesus MRI images to a template using rigid-body transform.
- This is also known as "AC/PC align". The original brain volume is preserved.
- Previously the data should have been: reconstructed, trimmed, lopped, and oriented axially.
- The axial view should show the nose pointing up, which in turn should match the desired template.
Python Library collections:
- fmri_tools.py
- A library collection of Python programs for fMRI Software Tools comparisons.
- Library Functions:
- air_params
- Reads an AIR .air file, returns translation & rotations.
- air_write_mc_series
- Write motion-correction .air params for a fMRI series.
- batch_seg
- Top-level function to segment anatomic images from all subjects.
- find_anat_4_seg
- Returns a list of study files needed to perform segmentation.
- coreg_n_seg
- Pipeline to coregister and segment a T1 MRI brain scan into MNI space.
- A rough coregistration is first performed, then the brain is skull-stripped and corrected for inhomogeneity artifacts, and a the skull-stripped brain is then coregistered to the template. Finally, the transform is applied to the original brain volume, yielding an unmasked coregistered brain.
- For the pipeline "coreg_n_seg", the following steps are performed:
- Preprocessing:
- loptop of T1 image
- if mask file is a VOI file, convert to ANALYZE.
- Brain Extraction (skull stripping):
- If a mask file was passed, the T1 is masked. If not, BET is called.
- Output: BET brain.
- Bias Correction
- Using FAST.
- Coregister T2 (if present) to the T1 image (in original space).
- Default assumes a T2, but some subjects do not have one.
- Coregistration to MNI space
- 12-parameter affine to skull-stripped T1avg152.
- reslice T1, T2 images into MNI space in 1x1x1, 2x2x2 formats.
- Segmentation
- use MFAST if T2 available
- use FAST if no T2.
- Output results
- coreg_wrappers.py
- Library containing scripts to perform basic coregistration using FSL and AIR.
- The scripts serve as wrappers, choosing standard default options to facilitate incorporation into larger programs.
- This set of library routines is meant to codify the most useful, general, and most commonly used options for each of the coregistration programs. This is especially useful for AIR, where the alignment and reslice operations are quite distinct.
- Some of these functions are duplicated (or based on) similarly named Python programs described elsewhere in the catalogue, but usually the most up-to-date and bug-free version is in this library.
- If you need to change advanced parameters which are not available through these functions, you can use the corresponding function as the basis for either writing your own new function, or simply calling the coregistration program directly from the command line or from another script.
- Library Functions:
- air_affine
- AIR coregistration using an affine body (12 parameter) fit.
- air_dir_define
- Define directory where AIR executables are located.
- air_rigid_body
- AIR coregistration using a rigid body (6 parameter) fit.
- air_warp
- AIR coregistration using a warp (many parameter) fit.
- flirt_coreg
- Use FSL's FLIRT to coregister 3D image files with standard parameters.
- mri2mni
- Skull-strip, segment, bias-correct, and coregister a T1-MRI into MNI space.
- image_manip.py
- Library collection of scripts to perform basic 3D image processing.
- This set of library routines is meant to codify the most useful, general, and most commonly used options for basic 3D and 4D image pre-processing.
- If you need to change advanced parameters which are not available through these functions, you can use the corresponding function as the basis for either writing your own new function, or simply calling the program directly from the command line or from another script.
- Some of these functions are duplicated (or based on) similarly named Python programs described elsewhere in the catalogue, but usually the most up-to-date and bug-free version is in this library.
- Many of these programs call IDL subroutines. You will need to have IDL installed for those routines to work properly.
- Library functions:
- bet_batch
- Use BET to brain-extract for a group of subjects.
- cleanup_files
- Clean up (delete) files from multiple subject directories.
- convert_32_16
- Convert a 32-bit floating-point (or other) file to scaled 16-bit integer.
- convert_to_analyze
- Converts a 3D or 4D image file to ANALYZE.
- fast_batch
- Use FAST to correct inhomogeneity artifact for a group of subjects.
- flip
- Flip (reorient) a 3D data volume.
- fn_add_suffix
- Add a suffix to a filename before the extension.
- fsl_name_pbmaps
- for FSL probability maps, determine which tissue class each represents
- idl_command
- Process commands for IDL from individual python functions
- is_analyze
- Returns a 1 if image file is ANALYZE format, 0 otherwise.
- is_voi
- Returns a 1 if image file is Spamalize-VOI format, 0 otherwise.
- lop_batch
- Loptop for a group of subjects.
- loptop
- Lop an image file: set top 0.5% of values to the 99.5 percentile value.
- rename_anlz
- Rename an ANALYZE-7.5 file (both .hdr and .img).
- rot
- Rotate 2D images within a 3D data volume.
- spam_dir_define
- Define base directory where Spamalize IDL program files are located.
- sum_3d_files
- Sum 2 or more same-size 3D image files, write out sum-image.
- sum_frames
- Makes a 3D sum-image by summing a 4D file framewise.
- utils_tro.py
- Collection of utility programs written in Python.
- Library Functions:
- timestamp
- Returns a string timestamp formatted like: yyyymmdd_hhmmss
- describe_local_python
- Prints description of local python libraries and their subroutines.
- format_local_python
- file_list
- Returns a list of files corresponding to a variety of search criteria.
- find_files
- Returns a list of a specific file type, one per subject, for an entire study.
- is_file
- Crash-proof way to check if a string refers to a valid file on the disk system.
- unique
- Return unique elements in a list, preserving order of list items.