no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.

@@ Line 1: / Line 1: @@
+====== 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.