Checking xff files for problems

While the xff class and methods provide a convenient interface, the code is somewhat hidden behind the subsref and subsasgn overloading mechanism in Matlab. This can make it more difficult to find out why any given file might produce an error message.

This page tries to give some ideas of how to approach such a situation.

Most of all: patience. It is true that NeuroElf by now also contains several GUI based functions and that the access to large amounts of data is simplified, but when this layer breaks, it usually gets very messy…

Also, some knowledge of how to inspect variables and how to navigate your filesystem from within Matlab is very helpful!

In the example, I will explain how to check the files that are used in a call to mdm.ComputeGLM.

The MDM object contains the filenames of the functional files to regress (in most cases these will be VTC files) and the models that will be used for the regression (either a list of SDM files or, as an extension to BrainVoyager's capabilities, a list of protocol files can be given).

As part of the initial checks in the ComputeGLM method, all VTC files are inspected and if the spatial dimensions mismatch, an error is raised.

To locate the file that causes the error, one can either debug the function (which is potentially difficult) or, alternatively, load the header of each object in turn and then compare the crucial header fields.

One of the syntax extensions of the call to xff that loads a file is to pass a single-letter, lower-case 'h' into the function as second argument:

<matlab code xff_read_header.m>% read only the header of a VTC vtc_header = xff('subj4124_run3_MNI.vtc', 'h');</code>

This also does not actually create a valid xff object but only returns the struct of the header content (which still contains all fields of a valid object!)

Following our example, this snippet of code could be used to compare the important header fields of a list of VTC files given in an MDM object:

mdm_compare_vtc_props.m

% create array that is able to hold the information
vtc_sizes = zeros(size(mdm.XTC_RTC, 1), 7);
 
% loop over the VTC files
for vtc_count = 1:size(vtc_sizes, 1)
 
    % read header
    h = xff(mdm.XTC_RTC{vtc_count, 1}, 'h');
 
    % copy header fields
    vtc_sizes(vtc_count, :) = ...
        [h.XStart, h.YStart, h.ZStart, h.XEnd, h.YEnd, h.ZEnd, h.Resolution];
end
 
% any size mismatch?
if any(any(diff(vtc_sizes)))
 
    % find out which one, taking the first as the norm
    for vtc_count = 2:size(vtc_sizes, 1)
        if any(vtc_sizes(vtc_count, :) ~= vtc_sizes(1, :))
            disp(sprintf('VTC file %s mismatches first file!', ...
                mdm.XTC_RTC{vtc_count, 1}));
        end
    end
end

The same is then also possible with possibly offending SDM and/or realignment parameter files, etc.