Metadata-Version: 1.2
Name: rawdatarinator
Version: 0.1.3
Summary: Read raw data from Siemens MRI scanners with IDEA VB15.
Home-page: https://github.com/mckib2/rawdatarinator
Author: Nicholas McKibben
Author-email: mri@byu.edu
License: GPL
Description-Content-Type: UNKNOWN
Description: ==================
        The RawDatarInator
        ==================
        
        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 <http://phineasandferb.wikia.com/wiki/List_of_Doofenshmirtz%27s_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 ]
        
        
        Example - Executable
        ^^^^^^^^^^^^^^^^^^^^^
        From the terminal::
        
            ./readMeasDataVB15.py raw.dat -w
        
        Example - Specify Python
        ^^^^^^^^^^^^^^^^^^^^^^^^
        Specify python from the terminal::
        
            python readMeasData15.py raw.dat -w
        
        Example - Import
        ^^^^^^^^^^^^^^^^
        Import into python script::
        
            from readMeasDataVB15 import readMeasDataVB15
            
            class DataLoader:
                def __init__(self):
                    data = readMeasDataVB15('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)
        
        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.
                
            -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 `.npz` file.  No arguments displays the IFFT of the k-space 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::
        
            python quickview.py processed_data.npz
        
        To view log magnitude and phase plots of k-space data::
            
            python quickview.py processed_data.npz -nifft
        
        ****************
        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.
        
Platform: UNKNOWN
Requires-Python: >=2.7
