File I/O

Python module to read and write the following file formats:

Current Release: 0.4, February 24, 2011

The dicom module has been rewritten to use the pydicom package for low-level reads from dicom files. This version also includes a number of additonal tools useful for fmri analysis. These include:

  • dump_header: curses based program to dump header contents to a terminal
  • dump_hdrkey: Dumps specific header items to stdout.
  • convert_file: Converts among nifti, brik, and dicom files (doesn't write dicoms yet.)
  • jump_censor: Creates censor files for afni based on the amount of motion in single frames.
  • plotlib: Wrappers that create specific matplotlib plots.
  • wbl_util: A few useful wrappers, mostly for ssh using paramiko.

Prior release: 0.3, October 15, 2008

There was a significant bug in version 0.1 that resulted in the frame dimension of multi-volume images on GE scanners being randomly sorted. The slice dimension was sorted correctly, but the frame number was assigned randomly (or as random as position in a hash table gets). This bug does not affect Siemens data. Siemens stores the acquisition time of each frame, so this is used to unambiguously assign the frame number.

Supported Formats:

  • Dicom: Read only.
  • NIFTI: Native Python.
  • AFNI: Read in native python, write requires the AFNI program to3d.
  • Analyze: Native python.
  • GE data files: Requires proprietary C header files. Uses a C library.

Usage:

The primary class is Wimage. If a Wimage is create by the call w = Wimage(filename)

the header is read from filename and stored in the attribute w.hdr. The method w.readfile() can then be used to read the entire image or individual frames.

Installation

Unpack the code, cd to the top directory, and run python setup.py install The code should install itself and two applications, dump_header.py and convert_file.py in your path.

Dependencies

Python-only installations require NumPy and SciPy. The distribution was tested with NumPy 1.0.3.1 and SciPy version 0.5.2 but should work with earlier revisions. The dump_header script uses the curses module to write to the screen.

Tests

It can be tested by running "test.py" in the test directory. Ten tests are run, most of which are read/write tests. There is no dicom write function, so files representing three dicom variants are included. The medical images have been replaced by a picture of a dog and a cat. Two loop tests are performed by writing in nifti format, converting to brik with 3dcalc, and then reading and checking the result. The same test is repeated in the reverse direction.

Reading GE data files

A shareable object is built but is not used for the default (no GE) package. If the appropriate GE include files are found, the library will be built but it will only contain a 3d reslicing function that is not used by this module.

Notes

The AFNI program "to3d" is used to write images in AFNI format. This program must be in your path if you try to write this format. AFNI's "3dcalc" and "3dAFNItoNIFTI" programs are used by the tests, so these should also be in your path.

Useful Classes and Functions

Functions:
  • get_dict()
    • Purpose: Return the entire dicom dictionary.
  • get_exam_list(exam)
    • Purpose: Search for dicom files in GE's database and find out what is in them.
  • isdicom(fname)
    • Determine if a file is in dicom format.
    • Return: True or False

Module: file_io

Provide simple interface to common neuroimaging image formats such as brik, nifti, dicom, and GE proprietary formats.

Class: Wimage(Header)

    Purpose: Front end for I/O functions in file_io.py

    Attributes
    • header
    • Image header: Dictionary containing the image header.
    • image: Last image read with readfile method

    Method resolution order
    • Wimage
    • Header
    • SubHeader
    • NativeHeader
    Methods defined here
    • __init__(self, filename=None, scan=False, force_scan=False, native_header=None, ignore_yaml=False)
      • filename: filename to be read.
      • scan: only has meaning for the dicom format. If true, every file in the directory is examined.
      • force_scan*: Scan even if yaml file is present.
      • ignore_yaml*: Read the header, not the yaml file.

        * Only applies to dicom files.

    • readfile(self, frame=-1, mtype=-1, filename=None, dtype=, hdr=None)

      Purpose: Read one or more frames from disk.

      Keywords:

      • frame: If specified, only a single frame will be read.
      • mtype: If specified only a single image type (i.e., magnitude, phase etc.) will be read.
      • dtype: Specifies the data type to be returned. It can be any valid ndarray dtype, i.e., float, float32, short, double etc. Images will be rescaled to prevent overflows and excessive truncation errors.
      • hdr: Previously read header. This will eliminate the overhead incurred by re-reading the header.
    • readheader(self, filename, scan=False)

      scan: True: for dicom each file in directories will be interrogated to determine all header parameters.

      Returns: header: dictionary containing header information.

    Methods inherited from Header
    • ReadYaml(self, fname)

      Read header from yaml file. It has apparently already been read and then rewritten in this format.

    • get_header(self, scan=False)

      Read header and return as dictionary.

    • read_hdr_from_yaml(self, filename)

      Read header from a yaml-encoded file.

    • write_hdr_to_yaml(self, filename)

      Write header to a yaml-encoded file.

Functions
  • abspath_to_relpath(tgtpath, srcpath)

    Purpose: Convert absolute paths to relative paths.

    tgtpath: The path to be converted.

    srcpath: The origin path.

    By Dave Perlman.

  • file_type(file_in)

    Purpose: Determine type of image file.

    Return codes: analyze, nifti, brik, dicom, ge_ifile (I-file), ge_data (P-file), cub, tes

  • isIfile(fname)

    Purpose: Test for GE I.xxx file format fname: Input filename.

    Returns True if filename is a GE I-file (pre ESE rev 10 image file format)

  • ispfile(fname)

    Purpose: Test if file is a GE pfile.

    Argument: file name

    Returns: True if file is a valid P-file

Last modified February 24, 2011