Mr object

From VISTA LAB WIKI

Jump to: navigation, search

A key goal of the mrVista2 project is to have a more uniform method of loading different neuroimaging data into a common format. The format should have a number of traits, including maintaining as much information about the data as possible, being readily human-readable, and being clear about the mapping from the data into real-world coordinates.

These concerns have been shared by a number of people working in the neuorimaging community. Perhaps the most comprehensive generalized framework for dealing with neuroimaging data is the set of standards developed for the NIFTI format:

NIFTI header file, with a detailed description of the data structure.

Based largely on these concerns, I describe here the 'mr data' object, which is a format for dealing with structural/functional MRI data (and potentially other neuroimaging data, like DTI/EEG) in matlab. The concerns here are similar, except the mr format is intended to be a little more high-level: it loads data into a MATLAB struct variable, with human-readable fields, and containing slightly more information. Particularly, the mr structure is intended to remember multiple coordinate transformations, so that data can be specified according to a range of conventions. This is in contrast to the NIFTI format, in which there are three possible coordinate conventions, but depending on the state of a few flag fields, each data file is specified relative to a single convention.

The idea is also that data loaded in the 'mr' format can be saved in a range of formats. Down the line, we hope to lock in to using compressed NIFTI for most all data (with a small matlab file containing extra information); but the code also allows saving data as straight-up matlab-format .mat files.


Contents

[edit] mr Format Description

mr structs have the following fields:

 data: numeric matrix of data, (2/3/4D)
 path: the input file path.
 format: string describing the format of the loaded file.
 hdr: header-file info for the file(s), in the native format. 
 e.g., for NIFTI files the header would have the NIFTI-type
 fields, for DICOM files the header would have DICOM-type fields.
 info: info about the scanning conditions for the file. Has the
       following sub-fields:
         scanner: Name of scanner used
         subject: Name of subject
         date:    Date scan was run. Format is the same as
                  the matlab DATE command, e.g. 22-Jul-2005.
         startTime: Time of the day the scan was run. [format]
         If any of this information can't be determined from
         the file, the field will be left blank.
 spaces: sub-struct describing how to xform the data to
         different coordinate systems. Has the following
         sub-fields:
         name: name of the space, e.g. 'R|A|S', 'AC/PC', 'Talairach'.
               A description of some sample spaces:
               'R|A|S': (rows, cols, slices) map to increasing
                        (right, anterior, superior) locations.
                        This is the default format for ANALYZE
                        and NIFTI files, and what is refered to
                        as the 'canonical' space. In addition,
                        I (ras) believe GE scanners deal in R|A|S
                        coords. 
                        However, matrices stored in this format
                        don't display very intuitively: the first
                        slice of a 3-D matrix in R|A|S format
                        is the lowest axial slice, with the front
                        of the brain pointing to the left and the 
                        right hemisphere on the bottom. With this format,
                        often the 'interesting' areas are buried, and
                        you need to do some permuting to get a nice
                        manual view in MATLAB. For this reason, I've
                        come up with a more display-friendly I|P|R
                        space below.
                'I|P|R': (rows, cols, slices) map to increasing
                        (inferior, posterior, right) locations. 
                        This is the convention used in mrLoadRet /
                        mrVista 1.0 / mrGray. It's not standard, but
                        it displays nicer, and means I don't have
                        to build ungainly assumptions into a viewer
                        (e.g., check for R|A|S and automatically do
                        a bunch of rotations and flips -- just switch
                        to I|P|R for a nicer display).
                       In the mr read/write functions, when it's possible
                       to find a transformation into R|A|S space, I try
                       to also add the flips/rotations into I|P|R. When
                       choosing a format to save as, R|A|S would be 
                       preferred for consistency's sake. (Though really,
                       the best format is the one the data were collected
                       in, as xforming introduces distortions; better just
                       to save the transformation info and do stuff on the
                       fly.)
               'Scanner': coords as collected in the scanner. For GE
                       scanners, this would be a form of R|A|S system,
                       but is probably not a good reference space, since
                       the subject's head may be positioned differently
                       in the scanner. But for e.g., comparing different
                       data files from the same session, this would be
                       good.
               'AC/PC': coordinates relative to the line connecting
                       the anterior commisure and the posterior 
                       commisure, using only rigid-body rotations
                       and translations. [add more info]. I try
                       to set this to be an I|P|R system, so 
                       it displays nicely.


         xform: 4x4 affine transform to convert between points
                 in the untransformed (pixel) space to the given space.
                 xform can be empty or omitted if coords and indices are
                 entered below.
         dirLabels: 1x3 cell-of-strings containing labels
                 for which direction is which in the space, e.g.
                 {'L <--> R' 'P <--> A' 'I <--> S'}.  % R|A|S space
                 The first label is for increasing rows, the second for 
                 columns, the third for slices.
                 MINOR NOTE: In displaying the dirLabels in MATLAB,
                 you can take advantage of the TeX interpreter built
                 in to the renderer (for most text objects), by replacing
                 the '<-->' string with '\leftrightarrow'. This renders
                 a nice graphical two-way arrow. (I'll have to remember
                 to do this in mrViewer.)
         units: label for the units: e.g. 'mm', 'pixels'.
         bounds: expected extent of the space, in the space's units.
         coords: N x 3 or N x 4 matrix directly mapping from indices
                 in the data to coords in the new space. Usually empty,
                 but can be non-empty if a highly non-linear mapping
                 has been computed, e.g., flattening gray matter.
         indices: indices into the data matrix corresponding to columns
                 in the coords sub-field. Usually empty,
                 but can be non-empty if a highly non-linear mapping
                 has been computed, e.g., flattening gray matter.
 voxelSize: size of each voxel in the data matrix. Format is
     [x y z] or [x y z t] for 4D data. x, y, and z correspond to
     spatial dimensions in milimeters; t is frame period in seconds.
     Note that x corresponds to different COLUMNS of a matrix while
     y corresponds to different ROWS.
 dims: size of the data in voxels.
 extent: voxelSize * dims, the total extent in spacetime of the MR
         data.
 dimUnits: units for each dimension, e.g. {'mm' 'mm' 'mm' 'sec'}.
 dataUnits: units for the data. [tbd]
 dataRange: [min max] values of the data.
 settings: optional field specifying preferred view settings, 
           such as grayscale levels and labels (used in mrViewer
           and maybe other UIs)
 params: parameters of any analyses associated with the data, either
         used to produce the data, or intended to be applied to the
         data.

[edit] MATLAB accessor code

[edit] mrLoad

Load data into an mr struct. Usage: mr = mrLoad(path, format); . If the path is omitted, a dialog will appear asking the user to select a file. If the format is omitted, it can usually be inferred from the file name; but if not, a dialog will ask for clarification. Can load: NIFTI, ANALZYE, DICOM, matlab (save mr struct), GE I-files, Lucas Center P-mag files, mrGray .dat, mrVista tSeries, mrVista inplane anatomy, mrVista corAnal, mrVista parameter map, FS-FAST Bshort, FS-FAST Bfloat.

[edit] mrSave

Save mr data. Usage: mrSave(mr, format); Will save the file to the path described in the mr.path field. Can save to a smaller number of formats than mrLoad: NIFTI, matlab, mrVista inplane anatomy, mrVista tSeries.

[edit] mrGet

Get a property of an mr object. Usage: val = mrGet(mr, property); . Type help mrGet to see a list of properties.

[edit] Coordinate Spaces

[edit] Affine transforms

[edit] Non-affine transforms

Personal tools