====== Attaching a protocol to a VTC ======

===== Motivation =====
BrainVoyager QX uses the name of a "linked protocol file" from the [[xff - VTC format|VTC]] header for quite a few built-in functions (e.g. when visualizing the conditions as colored background patches from the protocol information when displaying time courses).

For several reasons, it can be desirable to use different versions of the protocol (e.g. with conditions split or collapsed across one within-subjects factor of the study design, or using slightly shifted onsets in a deconvolution design to capture potential anticipation effects), and linking those protocol files in BrainVoyager can be relatively cumbersome.

===== Requirements =====
To fully use the scriptability of this feature, your data files must be arranged in a specific way:

  * [[xff - VTC format|VTC]] filenames must adhere to a (user definable) standard pattern, such as ''SUBJECT_RUN+NUMBER_TEXT.vtc''
  * [[xff - PRT format|PRT]] filenames must adhere to a similar standard pattern
  * VTC and PRT files must be stored in the same (subject) sub-folders (or at least, with a relaxed standard, the same number of PRTs must be found using a search pattern)

===== Script =====
Here is a **template** script that will look for VTC and PRT files in subject folders according to a pattern. The script will then load each VTC file in turn, link the corresponding found PRT file and then store the VTC back to disk.

<code matlab vtc_link_protocols.m>
% pre-set variables
% - studyfolder: folder where the (subject) sub-folders are located
% - vtcfpattern: VTC filename pattern
% - prtfpattern: PRT filename pattern (this needs to be altered to link
%   different protocols!)
studyfolder = '/Volumes/hms_study/Imaging';
vtcfpattern = '*_run*MNI.vtc';
prtfpattern = '*_run*_hmcollapsed.prt';

% find folders in the study folder
subfolders = findfiles(studyfolder, '*', 'dirs=1', 'depth=1');
nsf = numel(subfolders);

% create a cell array for VTC and PRT filenames
vtcfiles = cell(nsf, 1);
prtfiles = cell(nsf, 1);

% first pass: lookup files
for fc = 1:nsf

    % look for VTC and PRT files
    vtcfiles{fc} = findfiles(subfolders{fc}, vtcfpattern);
    prtfiles{fc} = findfiles(subfolders{fc}, prtfpattern);
    
    % ensure that the number is the same
    if numel(vtcfiles{fc}) ~= numel(prtfiles{fc})
        error('Number of found files mismatch.');
    end
end

% as we are sure that the number of files is correct for each subject
% we can simply create two large arrays with filenames
vtcfiles = cat(1, vtcfiles{:});
prtfiles = cat(1, prtfiles{:});

% NOTE: AT THIS PLACE, IT IS POSSIBLE TO ADD CODE TO EITHER
% - CHECK THE INTEGRITY OF FILES
% - PERFORM SOME PROCESS WITH THE PRT CONTENT AND RE-SAVE
% - ALTER THE VTC DATA AND RE-SAVE
% - etc...

% iterate over found files
for fc = 1:numel(vtcfiles)

    % load VTC file
    vtc = xff(vtcfiles{fc});
    
    % link protocol
    vtc.NrOfLinkedPRTs = 1;
    vtc.NameOfLinkedPRT = prtfiles{fc};
    
    % save and clear VTC
    vtc.Save;
    vtc.ClearObject;
end</code>

===== Notes =====
The code makes some additional assumptions:

  * all files found with the VTC pattern are, in fact, valid VTC files (high likelihood)
  * all files found with the PRT pattern are, in fact, valid PRT files (likelihood mostly depends on how those PRT files were created!)
  * the VTC folders and files don't are not read-only (privileges, type of medium, etc.)

Naturally, it would be possible to ascertain these assumptions, but it might be more efficient (in particular with the second condition) to use a separate script that creates and/or validates the protocol files.