File I/O

Python module to read and write the following file formats:

Current 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

class Dicom(DicomRawHeader)

    Provide high level interface to dicom header and image.

    Methods
    • __init__(self, filename)
      • Purpose: Read header on initialization and save data.
      • Inputs: filename, the name directory to be read or of a single file.
    • get_keyword(self, key)
      • Purpose: Return the keyword corresponding to a Dicom tag.
      • Inputs: key: A Dicom tag.
      • Notes: Assumes that the class was initialized with a filename.
    • get_keyword_value(self, tag)
      • Purpose: Return the keyword and value of a Dicom tag.
      • Inputs: key: A dicom tag in the form "7fe0, 0010"
      • Outputs: The value of the key.
      • Notes: Assumes that the class was initialized with a filename.
    • get_native_header(self, scan=False)
      • Purpose: Parse and format the dicom header.
      • Returns: A dictionary containing the entire header. Not all dicom keys are returned in the interest of efficiency. The header is a dictionary with keywords derived from the dicom dictionary description. The default action is the return the header for a single dicom file. This will be incomplete because a single does not completely describe the data: the slice direction is by the reading program and it is impossible to tell if multiple sets of data are stored in a single directory. For example, on a GE scanner, multiple acquisitions will be stored in the same directory - one for each time the scan button is clicked. These might be acquired with different parameters (such as flip angle, TR, TE etc). The only way to reliably read them is to open every file in the directory and examine the header. If scan=True, this will done. The scan=False must be used carefully and is only supplied because scanning the directory is very inefficient (since EPIs often have > 10000 files per directory.
    • get_series(self, dirname=None, dtype=None, frame=-1, mtype=-1)
      • Returns all images in the current directory. Images in mosaic are unpacked. Images can have up to five dimensions: x, y, z, time, and misc. The miscellaneous dimension will only be used if it can be unambiguously determined. For example, if a series contains real, imaginary, magnitude, and phase components of images acquired at two different echo times, the time dimension will be four and the misc dimension will be 2.
    • get_value(self, tag, default=None)
      • Purpose: Return the value of a Dicom tag.
      • Inputs: key: A dicom tag in the form "7fe0, 0010" filename: filename to be read.
      • Outputs: The value of the tag.
    • read_image(self)
      • Return image from the file specified at init. The image is returned as the native number type. (images stored in 12-bit packed format are returned as short integers.
    • Anonymize(self, output_dir=None)
        Remove patient name from header. If output_dir is provided, the input image will be left unchanged and the anonymized version will be written to output_dir.
    • PatientBirthDateTranslate(self, birthdate)
        Returns year of birth (removes month and day).
    • PatientNameTranslation(self, patname)
        Create anonymized PatientName field. Allowable fields are:
        • <numbers>,
        • [a-z,A-z]<numbers>,
        • <numbers>[a-z,A-z], or
        • sub<numbers>

        where [a-z,A-z] represents any single alphabetic character and <numbers> represents any positive integer.

        Disallowed fields are replaced with blanks.

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 October 18, 2008