Brain Innovation

Usage of NeuroElf for BrainVoyager file formats

Creating files

With most file types, this feature is available by using the following syntax to create a new file in memory, e.g.:

vmr = BVQXfile('new:vmr');

or

[FileName, PathName] = uigetfile('*.voi', 'Please select the BrainVoyager VOI file');
voi = xff(fullfile(PathName, FileName));

Many files (e.g. VMRs) are created with standard dimension, while others (e.g. VTCs) will be completely empty for not to allocate memory uselessly.

Reading files

To read files into MATLAB, a simple syntax can be used:

objvar = BVQXfile(filename);
% OR for more lazy file selection
objvar = BVQXfile('*.vmr');

The class itself uses so-called binary format files and text format files stored in the folder BVQXtools/@BVQXfile/formats 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 same files are 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. Excluded from this logic are DICOM and FIF files, which use their own IO function, mostly for speed issues.

Due to the fact that MATLAB requires all objects of a class (in fact, objects are specifically treated structures) to contain the same, common fields, the content variable internally only stores some basic fields that allow the class methods to lookup the actually stored variables.

However, due to the overloading of the struct notation, access to object data is virtually easy. So, let's say you want to read and access the contents of a GLM file:

glm = BVQXfile('C:\FMRIDATA\MSP_STUDY\P03\P03_RUN2.glm');

Then the following fields will be available in the variable glm:

ans =
 FileVersion: 3
 ProjectType: 1
 ProjectTypeRFX: 0
 NrOfTimePoints: 250
 NrOfPredictors: 4
 NrOfStudies: 1
 SeparatePredictors: 0
 TransformationType: 0
 Resolution: 3
 SerialCorrelation: 0
 MeanAR1Pre: 0
 MeanAR1Post: 0
 XStart: 57
 XEnd: 231
 YStart: 52
 YEnd: 172
 ZStart: 59
 ZEnd: 197
 CortexBasedStatistics: 0
 NrOfVoxelsForBonfCorrection: 54127
 CortexBasedStatisticsMaskFile: ''
 Study: [1x1 struct]
 Predictor: [1x4 struct]
 DesignMatrix: [250x4 double]
 iXX: [4x4 double]
 GLMData: [1x1 struct]

With the sub fields having the following contents:

glm.Study

ans = 
 NrOfTimePoints: 250
 NameOfAnalyzedFile: 'C:/FMRIDATA/MSP_STUDY/P03/P03_3DMC_SCSAI_SD3DSS4.00mm_LTR_THP3c_TAL.vtc'
 NameOfRTCFile: 'Interactive'

Altering objects

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

vmr.VMRData = uint8(225 * rand([256, 256, 256]));

As a convenience, many 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.
Writing files

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

glm.Save;    % save under the currently related filename
glm.SaveAs('file.glm');  % use a new filename

So, in our case above, it might be desirable to mask all maps with a pre-created mask:

% iterate over beta maps
for bmc = 1:size(glm.GLMData.BetaMaps, 4)

 % multiply with mask (0 or 1)
 glm.GLMData.BetaMaps(:, :, :, bmc) = ...
 glm.GLMData.BetaMaps(:, :, :, bmc) .* msk; ...
end

glm.SaveAs('C:\FMRIDATA\MSP_STUDY\P03_MASKED.glm');

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 new features have been introduced. 

Creating an object of type BVQXfile 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:

root = BVQXfile
 Extensions: [1x1 struct]
 Formats: [1x1 struct]
 Magic: [1x53 struct]
 Methods: [1x1 struct]

 List of currently loaded objects:
--------------------------------------------------------------------------------
 # | Type  | Filename
--------------------------------------------------------------------------------
 1 |  vmr  | /Applications/MATLAB_R2007b/toolbox/BVQXtools_v08c/_files/colin/colin.vmr
 2 |  srf  | /Applications/MATLAB_R2007b/toolbox/BVQXtools_v08c/_files/colin/colin_LH_SPH.srf
--------------------------------------------------------------------------------
 Total MB occupied: 42.006

To get a list of objects available for access, this new ROOT object offers the .Documents method:

handles = root.Documents

handles = 

 [1x73 char]
 [1x80 char]

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:

handles{1}

ans =

/Applications/MATLAB_R2007b/toolbox/BVQXtools_v08c/files/colin/colin.vmr

which can be fed into the root.Document(HANDLE) method:

vmr = root.Document(handles{1});

Please be aware that numeric indices possibly change between several calls! For example, if the first handle (colin.vmr) is removed from the class memory (vmr.ClearObject), then the numbered indices for handles 3 and 4 will be 2 and 3 instead!

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

vmrs = root.Documents('vmr');
static = root.Documents('vmr|srf');

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

Storing additional information

In addition to pre-defined fields, it is now possible to store arbitrary information (text, variables, contrast definitions, etc.) with BVQXfile objects by creating new fields in the .RunTimeVars field. Upon calling the .SaveRunTimeVars method, all fields therein will be saved into a file with the same name but the ".mat" extension. If several BrainVoyager files share the same name (e.g. for PRT/SDM/VTC combinations), each object has its own "sub-space" in the .mat-file, so information will not be overwritten!

vmr = BVQXfile('subject_01.vmr');
vmr.RunTimeVars.Comments = 'Subject has seemingly deformed brain.';
vmr.SaveRunTimeVars;

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

• Prev
• Next