====== Checking xff files for problems ======

===== Motivation =====
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.

===== Requirements =====
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!

===== Procedure =====
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 [[xff - VTC format|VTC files]]) and the models that will be used for the regression (either a list of [[xff - SDM format|SDM files]] or, as an extension to BrainVoyager's capabilities, a list of [[xff - PRT format|protocol files]] can be given).

As part of the initial checks in the [[mdm.ComputeGLM|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.

==== Header-only file access ====
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!)

==== Comparing header fields ====
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:

<code matlab 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</code>

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