NeuroElf wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== xff (class for file IO) ======

===== Motivation =====
Neuroimaging data comes in various formats, among of the more prominent ones are
  * Analyze/NIftI (e.g. used in the [[http://www.fil.ion.ucl.ac.uk/spm/|SPM]] series)
  * DICOM (a format that several scanners use to store/transport imaging data)
  * PAR/REC (a Philips proprietary, text and binary compound file format)
  * BRIK/HEAD ([[http://afni.nimh.nih.gov/afni|AFNI]]'s main format)
  * the plethora of [[http://www.brainvoyager.com/|BrainVoyager QX]]'s formats (VMR, FMR, VTC, GLM, VMP, etc.)

Additionally, several other formats are often required to work with neuroimaging data (e.g. to have the capability to load in physiological measurements).

**xff** is meant to be a central hub to access those files in Matlab.

===== Reference (help xff) =====
<file>  xff (Object Class)
 
  This class allows users to read and write diverse fileformats, as
  well as altering their contents in memory through a struct-like
  access.
 
  vmr = xff('new:hdr');   % create an SPM-compatible Analyze/NIftI header
  vmr = xff('colin.vmr'); % load the bundled 'colin.vmr' VMR object from disk
  vmr = xff('*.head' [, titleornumber]);  % show file selector
 
  The storage is made in one global variable, xffcont, to keep only
  one copy of elements (full call-by-reference implementation), as of
  version v0.7b.
 
  To clear the storage, it is thus required to call one of the clearing
  methods:
 
  object.ClearObject;
  clearxffobjects({object, ...});
 
  Properties in the objects are then accessible like struct fields:
 
  dimx = vmr.DimX;
 
  Methods are equally accessible and, if available, overload properties.
  Some methods work for all (several) object / file types:
 
  bbox = vmr.BoundingBox;
  unused.ClearObject;
  copied = vmr.CopyObject;
  filename = vmr.FilenameOnDisk;
  filetype = vmr.Filetype;
  firstvolume = vtc.GetVolume(1);
  vmr.ReloadFromDisk;
  vmr.Save;
  vmr.SaveAs(newfilename);
  vmr.SaveAs('*.vmr' [, title]);
 
  Alternatively, you can use the functional form:
 
  Call(vmr, 'MethodName' [, arguments]);
 
  To obtain help on object methods issue the call
 
  object.Help    - or -
  object.Help('Method')
 
  Additionally, certain commands / functions can be executed via
 
  xff(0, command [, arguments]);
 
  where the following commands are supported
 
  xff(0, 'clearallobjects')
      clear the object storage (like clear in Matlab for objects WS)
 
  xff(0, 'clearobj', h)
      clear the objects with internal handle(s) h
 
  xff(0, 'config', globalsettingname [, globalsettingvalue]]);
  xff(0, 'config' [, type [, settingname [, settingvalue]]]);
      e.g.
  xff(0, 'config', 'vmr', 'autov16', false|true);
      make global class configuration (on types)
 
  xff(0, 'copyobject', h)
      make a copy of object with internal handle h
 
  xff(0, 'extensions')
      return supported extensions (struct with cell array fields)
 
  xff(0, 'formats')
      return file formats (struct with fields bff, tff, extensions, magic)
 
  xff(0, 'isobject', var)
      implementation of isxff function
 
  xff(0, 'magic')
      return just the file magic array (1xN struct)
 
  xff(0, 'makeobject', obj_struct)
      return the classified object (struct -> class constructor)
 
  xff(0, 'methods')
      return a struct with 1x1 struct field for each file type and
      sub fields for each method supported by this type
 
  xff(0, 'newcont', type)
      return the resulting struct of NewFileCode of Xff files
 
  xff(0, 'object', h)
      return the occording object with handle h (implements a check)
 
  xff(0, 'transiosize');
      retrieve current transio size setting for all BFF (struct)
  xff(0, 'transiosize', tiostruct);
      sets transiosize (see last transiosize command below)
  xff(0, 'transiosize', 'vtc');
      retrieve current transio size setting for one BFF (see next command)
  xff(0, 'transiosize', 'vtc', 1048576 [, boolean:updatecache]);
      this sets the minimum number of bytes before , instead of loading
      the data in a property field, creating a @transio object
 
  xff(0, 'unwindstack');
      perform garbage collection (remove objects with unmatching dbstack)
 
  xff(0, 'updatecache');
      updates the cache.mat file (with current transiosize settings)
 
  xff(0, 'updatedisable' [, type]);
  xff(0, 'updateenable' [, type]);
  xff(0, 'updatestate' [, type [, truefalse]]);
  xff(0, 'updatestate' [, truefalsestruct]]);
      disable/enable automatic object updating (on type field)
      for "undatestate" call can work on a 1x1 struct with type fields
 
  Note: the default constructor (xff without arguments) produces
        the so-called ROOT xff object with content fields
        Extensions, Formats, Magic, Methods
        containing the supported features of the class</file>

===== Usage =====

==== Loading files from disk ====
To load a file from disk, it is often convenient to use the system's default file locator:

<code matlab>object = xff('*.hdr');</code>

will open a file selector and expect the user to pick the desired file. Naturally, if known, a relative or absolute filename can be provided as well to load an object (e.g. within a script).

The class itself uses so-called binary and text format specification files which are stored in the folder NeuroElf_vXY/_core/formats folder as information about the file formats. These specification files are human readable, so they can also be used to code a specific reader in virtually any other programming language. The information from the same specification files is also used to write the files, which makes this a much more flexible and easier to maintain library of parsing information than using distinct reading and writing functions. Most notably excluded from this logic are DICOM and FIF files, which use their own IO function, mostly for speed issues.

==== Accessing object properties ====
The access to properties is using the syntax as for structs -- the underlying data is, in fact, stored as a struct, and in principle all syntax valid for a struct is also valid for xff objects **with one notable exception**: if the field contents of several structs is accessed, Matlab does not (and cannot) say at runtime how many outputs this will produce; hence this will not work, and instead the field must first be accessed and then the subfield. Here are some examples:

To access the VoxelData associated with an Analyze/NIftI header object you can either access the entire field:

<code matlab>braindata = hdr.VoxelData;</code>

or also just access part of the data:

<code matlab>brainslice = hdr.VoxelData(:, 30, :);</code>

The exception kicks in when the field in question is a non-singleton struct, as is the case for BrainVoyager's VMP objects. If the object were a regular struct, the following syntax would work:

<code matlab>mapnames = {vmp.Map(:).Name};</code>

**This is the exception, for which a work-around is required!** Instead use:

<code matlab>maps = vmp.Map;
mapnames = {maps(:).Name};</code>

(The object indexing operator, (:), is not required, but usually improves readability of the code, as the user then is aware that the accessed variable or field is not a singleton struct!)

==== Creating new files ====
With all file types, new objects can be created with default settings in place by using the following syntax:

<code matlab>vmr = BVQXfile('new:vmr');</code>

Many files (e.g. especially BrainVoyager formats) are created with standard dimensions (e.g. TAL box for VTCs), and some will have data allocated already (e.g. VMRs) whereas others will be completely empty for not to allocate memory uselessly (e.g. VTCs).

==== Altering objects ====
For the VMR example above, it would be easy to create a random VMR:

<code matlab>vmr = xff('new:vmr');
vmr.VMRData = uint8(225 * rand([256, 256, 256]));</code>

As a convenience, some fields (such as number of volumes for VTCs) are checked/replaced immediately before writing the file to disk, so as to make sure that the file content is valid.

==== Methods ====
In many (more object-oriented) programming languages, the concept of methods is used. That means that each "type" of object has a list of associated functions that can be called on that particular type. While Matlab (by now) fully supports deriving classes from super-classes and defining unique methods for each type, the syntax is still that of a regular function call.

xff instead uses the same overloading principle to read/write access object properties for calling functions. If, for example, a specific object type (say, the surface format of BrainVoyager, SRF) supports a method called **''Smooth''**, the syntax is not ''Smooth(srf, ...);'' but instead **''srf.Smooth(...);''**.

While this is, at first, rather unusual, it allows a more transparent access to the resulting variable. In case the return value of a method is struct, as in:

<code matlab>bb = vmr.BoundingBox;</code>

with the struct overloading, it is perfectly valid to say:

<code matlab>res = vmr.BoundingBox.QuatT2B;</code>

which otherwise would not work:

<code matlab>res = BoundingBox(vmr).QuatT2B;
??? some error message...</code>

==== Writing files ====
To write an object back to file, the common Save and SaveAs methods can be used:

<code matlab>vmr.Save;                        % save under the currently related filename
vmr.SaveAs('colin_masked.glm');  % use a new filename</code>

==== Auxiliary functionality ====
=== Accessing list of loaded objects ===
As a convenience function (and mostly useful to access files for which handles have been lost, i.e. in case of a memory leak) but also to get a list of objects of a given type, two additional features are available.

Creating an object of type xff without any argument will result in the so-called ROOT object. Using Matlab's internal display function on this object will show some stats about the class itself:

<file>>> x = xff
    Extensions: [1x1 struct]
       Formats: [1x1 struct]
         Magic: [1x55 struct]
       Methods: [1x1 struct]

  List of currently loaded objects:
--------------------------------------------------------------------------------
   # | Type  | Filename
--------------------------------------------------------------------------------
   1 |  ntt  | /Volumes/Immersion/Analysis/Physio/10_4137.txt
   2 |  vmr  | 
   3 |  srf  | /Applications/NeuroElf/NeuroElf_v09a/_files/colin/colin_RH_SPH.srf
--------------------------------------------------------------------------------
  Total MB occupied: 165.793</file>

To access one of these objects, this ROOT object offers the ''.Documents'' method:

<code matlab>handles = x.Documents</code>

<file>handles = 

    '/Volumes/Immersion/Analysis/Physio/10_4137.txt'
    [        2]
    '/Applications/NeuroElf/NeuroElf_v09a/_files/colin/colin_RH_SPH.srf'</file>

whereas character handles in this cell array represent unique (first occurrence) filenames, and numeric values will allow access to unnamed or not-by-name specifiable objects. Access to one of these objects is then given via the .Document method:

<code matlab>srf = x.Document(handles{3});</code>

Please be aware that numeric indices possibly change between several calls! For example, if the first object (NTT object) is removed from the class memory (using the ''ClearObject'' on its object variable), then the numbered indices for handle 2 and 4 will be 1 afterwards!

Furthermore, to access only objects of a specific (list of) type(s), you can add a type specification to the root.Documents call:

<code matlab>vmrs = root.Documents('vmr');
static = root.Documents('vmr|srf');</code>

A list of types can be created by chaining several types with the OR (pipe) character.

=== Default property ===
A concept that I took up from the Visual Basic family of languages is the **Default property**. If an object (e.g. a VTC = voxel-based time course) has one main property (in this case VTCData), and the object variable is singleton (almost always the case), the property name can be dropped. So, these two lines of code produce the same result:

<code matlab>sliceddata = vtc.VTCData(:, :, :, 20);
% is the same as
sliceddata = vtc(:, :, :, 20);</code>

Matlab automatically refuses this syntax for objects without a default property or in case the variable (vtc) is, in itself, not of size 1x1.

=== Storing additional information ===
In addition to pre-defined fields, it is also possible to store arbitrary information (text, variables, contrast definitions, etc.) with xff objects by creating new fields in the .RunTimeVars field. This data is **not** automatically saved when the object is written to disk, but only so upon calling the **''.SaveRunTimeVars''** method. Then, all fields therein will be saved into a file with the same name but the ".rtv" extension (in fact a MAT-file). If several xff-accessible files share the same name (e.g. for PRT/SDM/VTC combinations of BrainVoyager projects), each object has its own "sub-space" in the .rtv-file, so information will not be overwritten by using the .RunTimeVars concept in more than one of these objects! Here is an example:

<code matlab>vmr = BVQXfile('subject_01.vmr');
vmr.RunTimeVars.Comments = 'Subject has seemingly deformed brain.';
vmr.SaveRunTimeVars;</code>

The next time this VMR will be opened, the comments are available again.

=== Per-object help / Documentation ===
To access information about available methods for any given type, use the **''.Help''** method. This produces a list of methods and their syntax, e.g.:

<file>>> vmr.Help

ans =

VMR::ApplyTRF               - apply transformation to VMR                  / Syntax: newvmr = vmr.ApplyTRF(trf [, opts])
VMR::BoundingBox            - get bounding box                             / Syntax: bbox = vmr.BoundingBox;
VMR::Browse                 - add variable to GUI                          / Syntax: vmr.Browse;
VMR::CleanVMR               - try automatic cleaning (experimental !)      / Syntax: cleaned = vmr.CleanVMR([opts])
VMR::ConvertToNLF           - convert an object to NLF (if appropriate)    / Syntax: vmr.ConvertToNLF([opts]);
VMR::CoordinateFrame        - generate coordinate matrices of VMR          / Syntax: vmrc = vmr.CoordinateFrame([opts]);
VMR::CreateVTC              - mimick BV's VTC creation                     / Syntax: [vtc] = vmr.CreateVTC(fmr, afs, vtcfile, res, meth, bbox, dt);
VMR::DBReco                 - direct border reconstruction                 / Syntax: srf = vmr.DBReco([bcol, scol])
VMR::GetVolume              - get one volume from a (multi-volume) dataset / Syntax: y = vmr.GetVolume([volnum])
VMR::GetVolumeSize          - get volume size from a (multi-volume) object / Syntax: ys = vmr.GetVolumeSize;
VMR::GradientVMR            - compute gradient VMR(s)                      / Syntax: [gvmr, gvmrx, gvmry, gvmrz] = vmr.GradientVMR([gdir]);
VMR::HiResRescale           - upsample ISO-Voxel VMR to higher resolution  / Syntax: hresvmr = vmr.HiResRescale([res, imeth])
VMR::InhomogeneityCorrect   - attempt automatic inhomogeneity correction   / Syntax: [vmr = ] vmr.InhomogeneityCorrect([opts])
VMR::IntensityMask          - mask a data object based on intensity values / Syntax: [nvox = ] vmr.IntensityMask(minvalue [, maxvalue [, opts]])
VMR::Layout                 - get layout signature                         / Syntax: layout = vmr.Layout;
VMR::LimitVMR               - apply intensity limits to V16 of VMR         / Syntax: [vmr = ] vmr.LimitVMR([opts])
VMR::LoadV16                - load matching V16 file into VMRData16        / Syntax: [vmr] = vmr.LoadV16([v16fname])
VMR::LoResRescale           - bring 0.5mm hires back to VMR space          / Syntax: lores = vmr.LoResRescale([cutoff])
VMR::MarkWhiteMatter        - mark white matter (e.g. for IC)              / Syntax: wmvmr = vmr.MarkWhiteMatter([opts])
VMR::MaskWithVMR            - zero values where VMR value beyond threshold / Syntax: [obj = ] vmr.MaskWithVMR(maskvmr [, threshold])
VMR::OverlaySRF             - overlay an SRF into the VMR (data changed!)  / Syntax: [vmr] = vmr.OverlaySRF(srf [, ocolor])
VMR::OverlayVMP             - overlay a VMP into the VMR (data changed!)   / Syntax: [vmr] = vmr.OverlayVMP(vmp [, vmpnum, vmpi])
VMR::PeelBrain              - cheap try to peel the brain                  / Syntax: peeled = vmr.PeelBrain([thresh, nre, nrd])
VMR::PrepareForReco         - prepare border for reconstruction            / Syntax: [vmr] = vmr.PrepareForReco([sval, bval])
VMR::Reframe                - reframe the VMR                              / Syntax: vmr.Reframe(bbox)
VMR::SampleData3D           - sample spatial data                          / Syntax: data = vmr.SampleData3D(crd [, opts]);
VMR::SaveV16                - save matching V16 file into 16-bit VMR file  / Syntax: [vmr] = vmr.SaveV16([v16fname])
VMR::SetConvention          - set radiological/neurological convention     / Syntax: [vmr = ] vmr.SetConvention(cnv)
VMR::SetOrientation         - set orientation/origin of file               / Syntax: [mat44 = ] vmr.SetOrientation([opts])
VMR::SliceData3D            - slice spatial data                           / Syntax: [sag, cor, tra, sc, data] = vmr.SliceData3D(crd [, opts]);
VMR::SliceToTransimg        - slice spatial data into transimg object(s)   / Syntax: [sval, scrd = ] vmr.SliceToTransimg(crd, ti [, opts]);
VMR::Talairach              - Un/Talairachize VMR                          / Syntax: talvmr = vmr.Talairach(imeth, tal [, acpc, inverse]);
VMR::Update                 - called after subsasgn for VMRs               / Syntax: vmr.Update.m(...);
VMR::WriteAnalyzeVol        - write an Analyze image from the VMR volume   / Syntax: [success = ] vmr.WriteAnalyzeVol(filename)</file>

And, naturally, there are more details available. To get those, add the name of the method to the .Help call:

<file>>> vmr.Help('GradientVMR')

ans =

 VMR::GradientVMR  - compute gradient VMR(s)
 
 FORMAT:       [gvmr, gvmrx, gvmry, gvmrz] = vmr.GradientVMR([gdir]);
 
 Input fields:
 
       gdir        flag whether to create directional VMRs too
 
 Output fields:
 
       gvmr        gradient VMR (intensity of gradient)
       gvmrx       X-gradient VMR (TAL X axis!)
       gvmry       Y-gradient VMR (TAL Y axis!)
       gvmrz       Z-gradient VMR (TAL Z axis!)</file>

A complete list of all available methods (on all object types) can be produced by a call to Help using the root object:

<code matlab>x = xff;
x.Help</code>

=== Transparent file access ===
The xff class interoperates with the [[transio]] class (see there for more information). To configure the thresholds for which data fields will not be read but rather a transio access point is created, use the syntax described in the help:

<code matlab>xff(0, 'transiosize', 'vtc', 65536);</code>

With this command, every VTC that is opened afterwards will contain transio objects instead of large data arrays for fields that surpass the 64kB threshold. To set this threshold for all (binary) files, leave out the filetype:

<code matlab>xff(0, 'transiosize', 5e5);</code>

This would set the threshold to roughly 500kb for all filetypes.