rawdatarinator 0.1.6

Read raw data from Siemens MRI scanners with IDEA VB15.

Python implementation based on MATLAB version written by Eugene G. Kholmovski, PhD (UCAIR, Department of Radiology, University of Utah).

The name of the project pays homage to the naming convention of the main antagonist in Disney’s hit cartoon “Phineas and Ferb” (see List of Doofenshmirtz’s schemes and inventions).

Installation

This package is known to work with Python 2.7.14 and Python 3.6.3 using Ubuntu 17.10 and Windows 10. requirements.txt contains package dependencies. You can clone the repo and get everything up and running like this:

git clone https://github.com/mckib2/rawdatarinator.git
cd rawdatarinator
pip install -r requirements.txt

or, slightly more easily, you can use pip:

pip install rawdatarinator

readMeasDataVB15

Read raw data from Siemens MRI scanners with IDEA VB15.

Will return an array of measured k-space data from raw data from Siemens MRI scanners using IDEA VB15 (single value). If the option -I is used, then image space data will be returned instead.

Usage:

Call with arguments:

readMeasDataVB15 filename [ -t ] [ -rfft ] [ -r1 ] [ -rp ] [ -rn ]
                          [ -skipts ] [ -nnavek ] [ -ros ]
                          [ -rosa ] [ -I ] [ -w ] [ -npz ]

Example - Executable

From the terminal:

python3 -m rawdatarinator.readMeasDataVB15 raw.dat -w

Example - Import

Import into python script:

from rawdatarinator.readMeasDataVB15 import readMeasDataVB15 as rmd

class DataLoader:
    def __init__(self):
        data = rmd('raw.dat')

if __name__ == "__main__":
    DataLoader()

Function Arguments

Function definition:

def readMeasDataVB15(filename,
                     resetFFTscale=False,
                     readOneCoil=False,
                     readPhaseCorInfo=False,
                     readNavigator=False,
                     readTimeStamp=True,
                     nNavEK=False,
                     removeOS=False,
                     removeOSafter=False,
                     transformToImageSpace=False,
                     writeToFile=False,
                     npz=False)

See Command-line Options for more details.

Command-line Options:

Terminal options:

filename
  Filename of file containing raw measurements.

-rfft (resetFFTscale)
  Resets FFTscale and DataCorrection for each coil
  to 1.

-r1 (readOneCoil)
  Read measurement data from from individual coil.

-rp (readPhaseCorInfo)
  _

-rn (readNavigator)
  _

-skipts (skip readTimeStamp)
  _

-nnavek (nNavEK)
  _

-ros (removeOS)
  Flag to remove oversampling (OS) in the x
  direction. removeOS=True is more efficient as it
  processes each readout line independently,
  reducing the required memory space to keep all
  measured data.

-rosa (removeOSafter)
  Flag to remove oversampling (OS) in the x
  direction. This works in image space, cutting FOV.
  Not likely a good idea for radial.

-I (transformToImageSpace)
  Produce image space representation. Note that
  there is no correction for partial Fourier or
  parallel imaging k-space undersampling.  The given
  version of code only uses numpy's FFT operation.

-w (writeToFile)
  Save k-space or image space volume. Currently the
  output filename is auto generated.

-npz (npz)
  Save k-space or image space volume using the .npz
  file extension.  Default is to use hdf5 file
  standard.

-h (help)
  Displays this documentation.

Testing

testsuite.py compares the values generated in the Python implementation to the workspace variables of the MATLAB implementation to ensure correct output.

Quick View

Display processed MRI data from .hdf5, .npz, or .dat files. No arguments displays the IFFT of the k-space data. The type of file is guessed by the file extension (i.e., if extension is .dat then readMeasData15 will be run to get the data).

Command-line Options

Options for QuickView:

-nifft (no IFFT)
  Display k-space data, log magnitude and phase plots.

Examples

To view image domain data:

python3 -m rawdatarinator.quickview processed_data.hdf5

To view log magnitude and phase plots of k-space data:

python3 -m rawdatarinator.quickview processed_data.hdf5 -nifft

To view image domain data of raw data file:

python3 -m rawdatarinator.quickview raw.dat

Lexer and Parser

Siemens raw MRI data comes packaged all in a .dat file. The structure does not follow Siemens’ PLM XML format, but is quasi-XML followed by a dump of the binary data. It is described in the IDEA Documentation.

The game plan I used was to extract the quasi-XML portion of the file, obtain the structure of the document by parsing it, and then reconstructing an equivalent XML document that is easy to traverse using standard libraries. Python Lex-Yacc (PLY) is used to create a lexer (infolex.py) identifying each unique token and a parser (infoparser.py) that builds an XML string as grammar productions are matched. The actual grammar is unknown to me, so the tokens and grammar may not be comprehensive. This functionality is captured in the raw2xml function in infoparser.py.

cleanraw.py sanitizes the raw data by removing illegal characters (such as carriage returns or null characters in the quasi-XML portion of the document) or data not needing to be parsed.

The resultant XML document mirrors the original quasio-XML document and is split into roughly six subtrees/section::

1. <XProtocol> … </XProtocol>

2. <XProtocol name=”Dicom”> … </XProtocol>

3. <XProtocol name=”Meas”> … </XProtocol>

4. The MeasYaps portion, looks like:

   <value>Key</value>

   <value>Value</value>

   …

5. <XProtocol name=”Phoenix”> … </XProtocol>

6. <XProtocol name=”Spice”> … </XProtocol>

MeasYaps is a collection of keys and values whereas each <XProtocol> has a standard tree structure. Every XML document must have a root and is called <doc_root>.

Many measurements come from MeasYaps. A utility function called get_val_by_text() is used to find a value given a key.