Python library description

• coreg_wrappers: Coregistration using FSL, AIR with typical default settings.
• image_manip: Basic 3D image volumetric processing and filtering.
• utils_tro: Miscellaneous utility programs.
• fmri_tools: fMRI processing, especially for Software Tools comparisons.

If you are interested in using this software, contact Terry Oakes at: troakes - at - wisc.edu

--- Library Description for coreg_wrappers.py ---

Library Functions:

1. air_affine AIR coregistration using an affine body (12 parameter) fit.
   
2. air_dir_define Define directory where AIR executables are located.
   
3. air_rigid_body AIR coregistration using a rigid body (6 parameter) fit.
   
4. air_warp AIR coregistration using a warp (many parameter) fit.
   
5. flirt_coreg Use FSL's FLIRT to coregister 3D image files with standard parameters.
   
6. mri2mni Skull-strip, segment, bias-correct, and coregister a T1-MRI brain scan into MNI space. T2 and mask images are optional.
   

air_affine in coreg_wrappers.py

air_dir_define in coreg_wrappers.py

air_rigid_body in coreg_wrappers.py

air_warp in coreg_wrappers.py

flirt_coreg in coreg_wrappers.py

• a rigid body (6 parameter) fit, or
• an affine (12 parameter) fit.
  

Calling sequence:
flirt_coreg fn_obj fn_tgt [dof 6|12 omat 0|1 clean 0|1 verbose 0|1]
Parameters:

• fn_obj The file to coregister.
• fn_tgt The target file to coregister to.
• dof Degrees of freedom: 6 (rigid body) or 12 (affine).
• clean Set to 1 to delete matrix transform file.
  

Returns:
array with coregistered filename and matrix filename if succesful, 0 if unsuccesful
History:
@ Terry Oakes 2006
Written 2006-01-26 by Terry Oakes.

mri2mni in coreg_wrappers.py

• fn_obj The file to coregister.
• fn_mask (Optional) A filename of a mask-file which specifies a whole-brain mask. Either a binary mask or an image may be used: all non-zero valued pixels are assumed to indicate the whole brain. If a mask is used, the initial BET skull-stripping will be skipped.
• clean Set to 1 to delete matrix transform file, intermediate files.
• loptop loptop of T1 MRI image
• test Set to 1 to test that all the filenames needed are present, then quit. When using test, returns a 1 if all needed files found, 0 otherwise.
• verbose print nonessential informational messages.
  

Example:
fn_bet = coreg_wrappers.mri2mni(fn_mri, fn_mask, verbose=1)
Returns:
array with coregistered filename and matrix filename if succesful.
0 if unsuccesful.
History:
@ Terry Oakes 2006
Written 2006-02-09 by Terry Oakes.

--- Library Description for image_manip.py ---

Library functions:

1. convert_to_analyze Converts a 3D or 4D image file to ANALYZE.
   
2. fn_add_suffix Add a suffix to a filename before the extension
   
3. fsl_name_pbmaps for FSL probability maps, determine which tissue class each represents.
   
4. idl_command Process commands for IDL from individual python functions.
   
5. is_analyze Returns a 1 if image file is ANALYZE format, 0 otherwise.
   
6. is_voi Returns a 1 if image file is Spamalize-VOI format, 0 otherwise.
   
7. loptop Sets top 0.5% pixels to value of 99.5% percentile's value for better dynamic range.
8. rename_anlz Rename an ANALYZE-7.5 file (both .hdr and .img).
   
9. spam_dir_define Define base directory where Spamalize IDL program files are located.
   
10. sum_3d_files Sum 2 or more same-size 3D image files, write out sum-image.
    
11. sum_frames Makes a 3D sum-image by summing a 4D file framewise.
    

convert_to_analyze in image_manip.py

• fn: Filename of a file in a format supported by EZ_WRITER.
• voi_name: Set to the name of a VOI in a VOI file to extract. Only relevant if the image being converted (input) is a VOI file.
• flip: Tells the file conversion program if the data should be flipped (reversed) about one or more axis. An array can be used to indicatethe order of multiple flips.
  • 0 = no action taken
  • 1 = reverse x-axis columns
  • 2 = reverse y-axis rows
  • 3 = reverse z-axis planes.
• verbose: 0 or 1.
• clean: Flag to delete intermediate files.
  • 1 = clean up (delete) intermediate image and command files (default)
  • 0 = don't clean up intermediate files.

Returns:
list of filename(s) of new ANALYZE file if succesful
0 if unsuccesful
History:
@ Terry Oakes 2006. Written 2006-01-31 by Terry Oakes.

fn_add_suffix in image_manip.py

• fn: the full filename to change.
• suffix: the string you want to add in before the extension.
• analyze: 0|1 (default=1): strip off the existing extension if it is a known image file extension, substiture ".img".
  

fsl_name_pbmaps in image_manip.py

Purpose:
Deterimnes which tissue type (CSF, GM, WM) the tissue probability maps from FSL's MFAST refer to. The naming scheme is not always consistent, so some extra smarts need to be thrown at the problem.

!!!! This program is not fully implemented yet !!!!

idl_command in image_manip.py

Parameters:

• commands An string array of commands to issue to the IDL command-line. There should be one complete command per array element.
• fn_markers An array of strings which will be used to search the output of the IDL program to find the filename of the output file. Each string should specify the complete line printed immediately before the name of the output file. This will depend on the IDL program being called. It is important that each program print a unique message, which usually means the program's name should appear in the message. This program assumes the subsequent line will contain the name of the output file. You may search for multiple filenames, e.g. to check if mutliple processes each created an output file. The filenames are returned by this program as a string array in the same order as the search-strings. It is the responsibility of the caller to examine this array and note any problems.
• check_dir Set to the name of a directory to check for existence and write-permision.
• verbose: 0 or 1.
• clean: Flag to delete intermediate files.
  • 1 = clean up (delete) intermediate image and command files (default)
  • 0 = don't clean up intermediate files.

Returns:
list of filenames produced (corresponding to "fn_markers")
1 if there are no fn_markers.
0 if an error.
Example:
res = image_manip.idl_command(commands, fn_markers)
History:
Written 2006-02-06 by Terry Oakes.

is_analyze in image_manip.py

is_voi in image_manip.py

Returns:

• 1 if image file is Spamalize-VOI format
• 0 otherwise.

Example:
res = image_manip.is_voi(fn)
History:
Written 2006-03-10 by Terry Oakes.

loptop in image_manip.py

• fn: MRI filename in a format supported by EZ_WRITER (with full path).
• verbose: 0 or 1.

Returns:
filename of new ANALYZE lopped image file if succesful.
0 if unsuccesful.
History:
@ Terry Oakes 2006
Written 2006-03-10 by Terry Oakes.

rename_anlz in image_manip.py

• fn_old: Name of file to rename. Can be any of:
  • /fullpath/fn_old.img
  • /fullpath/fn_old.hdr
  • /fullpath/fn_old
• fn_new: String containing desired new filename. Can be any of:
  • /fullpath_new/fn_new
  • fn_new (assumes same directory as input file). The "fn_new" string can contain ".img" or ".hdr" at the end but not needed.
• overwrite: Set to 1 to enable the desired new file to overwrite an existing file with the same name. Set to 0 to explicitly forbid overwriting. Default = 0. If overwrite=0 and the desired new filename already exists, no action is taken and a value of 0 is returned.

Returns:
New filename "/fullpath/fn_new.img" if all went as planned,
a string containing zero "0" otherwise.
History:
@ Terry Oakes 2006
Written 2006-03-24 by Terry Oakes.

spam_dir_define in image_manip.py

sum_3d_files in image_manip.py

• fn_arr: Array of filenames in a format supported by EZ_WRITER.
• verbose: 0 or 1.
• clean: Flag to delete intermediate files.
  • 1 = clean up (delete) intermediate image and command files (default)
  • 0 = don't clean up intermediate files.

Returns:
filename of new ANALYZE sum-image file if succesful (based on first input filename)
0 if unsuccesful
History:
@ Terry Oakes 2006
Written 2006-01-31 by Terry Oakes.

sum_frames in image_manip.py

• fn: Filename of a file in a format supported by EZ_WRITER.
• beg_frame: the beginning (first) frame you want to sum (1-based). Default value is 1 (the first frame). Set to 0 or ignore to take the default value.
• end_frame: the ending (last frame) to include in the sum (1-based). Default value is the last frame in the file. Set to 0 or ignore to take the default value.
• verbose: 0 or 1.
• clean: Flag to delete intermediate files.
  • 1 = clean up (delete) intermediate image and command files (default)
  • 0 = don't clean up intermediate files.

Returns:
filename of new ANALYZE sum-image file if succesful
0 if unsuccesful
History:
@ Terry Oakes 2006
Written 2006-01-31 by Terry Oakes.

--- Library Description for utils_tro.py ---

Library Functions:

1. timestamp Returns a string timestamp formatted like: yyyymmdd_hhmmss
   
2. describe_local_python Prints description of local python libraries and their subroutines.
   
3. file_list Returns a list of files corresponding to a variety of search criteria. Useful for pipelines.
   
4. is_file Determines if an item is a string refering to a valid file (i.e. the file exists on the disk system).
   

timestamp in utils_tro.py

describe_local_python in utils_tro.py

[Note- this web-page was created using "utils_tro.describe_local_python". About 10 minutes of extra work was needed to clean up the text, insert a few hyperlinks, etc.]

Abstract:
This program introduces a minimal amount of text formatting. Emphasis is more on quick functionality than pretty results. I got it to where it worked, then stopped.

This program contains a list of known local Python libraries. Information about the libraries and constituent functions can be displayed if that information is contained in the files and if coventions for describing the program are followed. There are three levels of detail:

1. verbose = 0: (default) Prints a brief top-level description of the library, followed by a 1-line description of each of the constituent functions;
2. verbose = 1: Prints information for "verbose=0", plus the entire top-level comments for the library.
3. verbose = 2: Prints information for "verbose=1", plus the initial comment block for each subroutine.

The comments for this program (which you are reading now) serve as a template. The following assumptions are made regarding the initial comment blocks:

1. Functions are preceded by a block of comments. The first line contains an obvious section seperator, such as '----' or '====' (but usually ~80 characters wide).
2. The name of each function is listed alone at the beginning of its comment block.
3. A brief description (1-2 lines) for each function is preceded by a line containing the single word, "Purpose:". The "Purpose" section should come immediately after the name of the function.
4. The top-level comments for the entire library should be at the top of the file. The initial library comment block should contain a "Purpose" followed by a list of all subroutines. This list should be immediately preceded by a line containing the single phrase, "Library Functions:". Any initial Python statements (e.g. "import") must come after this comment block.

Additional information can be placed into the comment block for both the top-level library as well as for each function. Suggested headings include:

• Abstract: details about purpose, philosophy, calling, results, etc.
• Parameters
• Calling sequence
• Example of use
• Return value
• Output, side effects
• History

Parameters:

• verbose: [0|1|2] (default=0) Print out more extensive informational messages with increasing number value.
  • 0: print "Library description" only (default).
  • 1: print full top-level comment section for each library.
  • 2: print as for (1), but also print full comment section for every function.
• fn_out: Controls whether and how output gets printed to a text file.
  • 0 = only print output to the screen (default)
  • 1 = only print output to a file. The filename will then be deternmined by this program.
  • string = output will only go to a file, where the name of the file is given by the string. The string must signify a file to be created in a directory where the user has write-permission.
    

Output:
Prints a list of libraries and their constituent functions to the screen.

Returns:
1 if all goes well, 0 otherwise.
Example:
res=utils_tro.describe_local_python(verbose=0, fn_out=1)
History:
Written 2006-03-16 by Terry Oakes.

file_list in utils_tro.py

Purpose:
Returns a list of files corresponding to a variety of search criteria. Facilitates pipeline construction.
Abstract:
This is a general purpose utility to make it easy to find files. It is meant to consolidate frequently used code. It is aimed at batch-processing programs that need to find one or more files in a directory tree based on a few simple criteria. Three features make this program especially handy for use in data processing pipelines:

1. It can process a variety of possible filenames in different contexts, e.g. single files, wildcards, or directories.
2. It has a uniform output which is always a list, even if it is an empty list.
   
3. It will not crash if an error is encountered (e.g. a filename does not exist).

Wildcards can be either "*" or "?", with standard unix usage. All filenames (including directory names) should include the full path.
The input to this program can be any of the following:

1. A directory: All files within the directory will be returned.
2. A directory+wildcard, e.g. /fullpath/*.img
3. Single file: verifies that file exists and can be read by user.
4. List of files: verifies that all files exist and can be read.
   

If a list is provided, a 0 is inserted in the list for each of the explicitly named files that are not readable files, and the caller should check for this.

Returns:
A list of files that correspond to the criteria, or "0" if none found or the file or directory does not exist. N.B. a list is always returned, even if the input is a single string or invalid.
Example:
files = utils_tro.file_list('/study/mystudy/sub*.img')
History:
Written 2005-09-29 by Terry Oakes.

is_file in utils_tro.py

--- Library Description for fmri_tools.py ---

Library Functions:

1. air_params Reads an AIR .air file, returns translation & rotations.
   
2. air_write_mc_series Write motion-correction .air params for a fMRI series.
   
3. batch_seg Top-level function to segment anatomic images from all subjects.
   
4. coreg_n_seg Pipeline to coregister and segment a T1 MRI brain scan into MNI space.
   
5. find_anat_4_seg Returns a list of study files needed to perform segmentation.
   

air_params in fmri_tools.py

air_write_mc_series in fmri_tools.py

batch_seg in fmri_tools.py

Abstract:
This program calls a subroutine (coreg_n_seg) that performs the segmentation and registration for each subject. Currently the subroutine uses FSL's FLIRT, FAST, and MFAST programs.

Returns:
1 if succesful
0 if there was a problem.
Calling sequence:
import fmri_tools
fmri_tools.batch_seg([verbose])

coreg_n_seg in fmri_tools.py

1. Preprocessing:
   1. loptop of T1 image
   2. if mask file is a VOI file, convert to ANALYZE.
2. Brain Extraction (skull stripping). If a mask file was passed, the T1 is masked. If not, BET is called. Output: BET brain.
3. Bias Correction using FAST.
4. Coregister T2 (if present) to the T1 image (in original space). Default assumes a T2, but some subjects do not have one.
5. Coregistration to MNI space
   1. 12-parameter affine to skull-stripped T1avg152.
   2. reslice T1, T2 images into MNI space in 1x1x1, 2x2x2 formats.
6. Segmentation
   1. use MFAST if T2 available
   2. use FAST if no T2.
   3. Output (see below)

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.

Parameters:

• fn_T1 The file to coregister.
• fn_T2 T2 file from same subject.
• fn_mask (Optional) A filename of a mask-file which specifies a whole-brain mask. Either a binary mask or an image may be used: all non-zero valued pixels are assumed to indicate the whole brain. If a mask is used, the initial skull-stripping will be skipped.
• clean Set to 1 to delete matrix transform file, intermediate files.
• loptop loptop of T1 MRI image
• test Set to 1 to test that all the filenames needed are present, then quit. When using test, returns a 1 if all needed files found, 0 otherwise.
• verbose print nonessential informational messages.

Example:
fn_bet = coreg_wrappers.mri2mni(fn_mri, fn_mask, -v)

Output: The following data in MNI tempalte space are written to files:

• T1 in high-res (~1x1x1 mm pixels)
• T1 in template space in medium-res (2x2x2 mm pixels) to match functional data
• T2 in high-res (~1x1x1 mm pixels), if a T2 was input
• Tissue segment map showing CSF, GM, WM in high-res
• Tissue segment map showing CSF, GM, WM in medium-res
• Tissue probability maps, 1 each for CSF, GM, WM, in 2x2x2 mm pixel size

Returns:
array with coregistered filename and matrix filename if succesful
0 if unsuccesful
History:
@ Terry Oakes 2006. Written 2006-02-09 by Terry Oakes.

find_anat_4_seg in fmri_tools.py