Turbo-BrainVoyager v3.2
Real-Time Protocols
In case that one know already the experimental protocol in advance of functional scanning, the easiest way to specify the protocol is to use (or prepare if not already available) a standard (Turbo-)BrainVoyager protocol (PRT) file. There are, however, interesting and challenging experimental ideas, which would benefit from a dynamic creation of the protocol (and consequently design matrix). The RTP file format has been specified to allow the incremental build-up of the protocol during an ongoing measurement.
The real-time protocol (RTP) file format expects a short header specifying important general information including the time resolution used to specify events/blocks, number of experimental conditions, contrasts (optionally) as well as entries specifying colors for plotting time courses in TBV. After the header, a RTP file provides incrementally information about the experimental protocol, i.e. moments in time when conditions introduced in the header are turned on and off. While obtaining the image data, Turbo-BrainVoyager (TBV) reads the incrementally supplied information and builds a design matrix on the fly for statistical analysis.
At the begin of a scanning, the RTP file must be available containing the header information. The header is read only once when real-time analysis is started and must not change during the analysis. The lines following the header contain the main information specifyng the on/off state of experimental conditions. Note that the RTP file may not be rewritten each time when new protocol information is made available, but the new information must be appended to the RTP file as time progresses. At each time point (TR, volume), TBV checks whether there is new information appended to the file and updates the protocol and design matrix (including HRF application) accordingly. TBV keeps a pointer at the current position of the opened file to avoid rereading and parsing of the whole file repeatedly. This is the reason why the incremental protocol information must be appended to the real-time protocol file. More specifically, for each new piece of information, software writing the RTP file should open the file in "append" mode, then write the new piece of information (e.g. one line of the protocol), and then close the file.
After the header, condition state lines (CSLs) specify the state of the experimental protocol. Each CSL characterizes a change in the protocol state at a certain time point; as long as the current condition state does not change, it is not necessary to provide condition state lines. It is nonetheless possible to specify more lines than necessary, e.g. it might be convenient for custom software to write a CSL at every TR (volume time point) even if the condition state does not change.
Each condition state line begins with a time marker in units defined in the "ResolutionOfTime" parameter in the header (volumes or milliseconds). The entries in a CSL following the time marker code the state (1 = on / 0 = off) of each condition included in the design matrix. Note: Since entries are interpreted as float values, you may also code condition state values such as 0.7, e.g. for parametric designs. A baseline condition (e.g. "rest", "fixation") may be specified but should not be included in the design matrix. You can use the "Modelled" entry (values "yes" or "no") in the header to exclude a condition from the design matrix. If the "ResolutionOfTime" parameter is specified as "Volumes", counting starts with value "1", i.e. the first volume is "1" (not "0"). Specifying time in volumes (time points) has the advantage that the protocol header needs not be changed for subsequent scans if the TR value changes (in TBV settings file). If "ResolutionOfTime" is specified as "ms", time starts at "0". TBV uses the following equation to convert a volume specification into a millisecond specification:
ms = (volume - 1) * TR
or vice versa:
volume = ms/TR + 1
Note that protocol time starts not necessarily with the first data available from the scanner. If the "SkipVolumes" entry in the TBV settings file is larger than "0", the respective number of initial volumes (time points) are skipped from analysis. If a run consists, for example, of 100 time points (volumes) and 2 volumes are skipped, the first two volumes would not be used in TBV for data analysis and the third scanned volume would correspond to the first volume of the protocol. Why would one skip volumes for analysis? Skipping a few initial volumes is useful in order to exclude the first functional volumes possessing high intensity values due to T1-saturation; if these volumes would be included, high signal values would detoriate the analysis and display of time courses. Note that TBV still reads the very first available volume and uses it for display of the functional data (if not set to use the currently processed volume) because the first T1 saturated volume provides good anatomical detail as opposed to the functional images in later volumes. Note that some scanners perform a few "implicit" ("prep" or preparatory) scans before saving data to disk; in that case skipping of volumes is not necessary. While this situation does not require skipping of volumes (making specification of protocols easier), the "real" first T1 saturated volume will not be available for visualization in this case.
RTP Header
FileVersion: [(int)] ' value "1" at present ResolutionOfTime: [volumes | ms] ApplyHRF: [yes | no] ' apply HRF function, "yes" recommended NrOfConditions: [(int)] ' number of conditions ' For each condition, one line: [Condition name: "name"] [ColorRGB: (int) (int) (int)] [Modelled: yes | no] ' The condition name must be enclosed in " symbols allowing strings containing blanks ' The RGB values must be in range 0 - 255 ' The "Modelled" entry allows to drop conditions from the design matrix. ' It is recommended to only drop the baseline condition (if specified) ' If no condition is dropped, baseline is assumed to be those intervals ' during which no condition is "on" NrOfContrasts: [TBV | Auto1 | Auto2 | (int)] ' If "TBV" is specified, the contrast specification in TBV settings file is used. ' if "Auto1" is specified, contrasts are created automatically testing ' each main condition with respect to baseline ' if "Auto2" is specified, contrasts are created as with "Auto1". In addititon, ' contrasts are generated comparing all possible comparisons between pairs of main conditions ' If a number is provided, lines must be specified to code each desired contrast. ' First the "ContrastNames:" field must contain one row per contrast specifying ' the contrast name enclosed in quote signs. ' Then the "ContrastVectors:" field must follow with one line per contrast. A contrast ' weight value must be specified for each condition including non-modelled conditions. ' Then the "InitialSelections:" field contains one value per line indicating whether ' the respective contrast should be turned on as default in TBV. A value of "0" ' turns off the contrast, a vlaue of "1" turns it on in the direction "greater than", ' a value of "2" turns the contrast on in the direction "smaller than", and a value ' of "3" turns both directions on (resulting in positive and negative colors) for ' the respective contrast. ' Finally the "ContrastColors:" entry contains per line the color of the respective ' contrast with three values coding the red, green and blue channel in a range ' from 0 - 255. ' The next 4 entries are not relevnt for analysis but are ' only used for time course display purposes BackgroundColor: [ColorRGB: (int) (int) (int)] TextColor: [ColorRGB: (int) (int) (int)] TimeCourseColor: [ColorRGB: (int) (int) (int)] TimeCourseThick: [(int)]
RTP Data
SCAN BEGIN ' this entry marks the begin of the incremental protocol time data ' condition state lines - CSLs (for explanations, see above) [Time-1: (int)] [StateOfCondition-1: 0 | 1] [StateOfCondition-2: 0 | 1] ... [Time-2: (int)] [StateOfCondition-1: 0 | 1] [StateOfCondition-2: 0 | 1] ... : : SCAN END ' TBV will stop processing if this symbol encountered or if "time" > "expected time" (NrOfVolumes x TR)
Sample RTP File 1
Assuming short measurement with 32 volumes
FileVersion: 1 ResolutionOfTime: volumes ApplyHRF: yes NrOfConditions: 3 "Baseline" 128 128 128 No ' baseline not modelled in DM, thus two conditions specified in CSLs "Faces" 255 0 0 Yes "Houses" 0 255 0 Yes NrofContrasts: 3 ' The same contrasts specified in "ContrastVectors" would be generated if "Auto2" would be used ContrastNames: "[-1 +1 0] Faces vs. Baseline" "[-1 0 +1] Houses vs. Baseline" "[ 0 -1 +1] Houses vs. Faces" ContrastVectors: -1 +1 0 -1 0 +1 0 -1 +1 InitialSelectionState: 1 1 3 ContrastColors: 255 0 0 0 255 0 0 200 255 BackgroundColor: 0 0 0 TextColor: 255 255 255 TimeCourseColor: 255 255 255 TimeCourseThick: 2 SCAN BEGIN 1 0 0 ' column 1: time marker, column 2: "Neutral Faces", column 3: "Emotional Faces" 9 1 0 15 0 0 21 0 1 27 0 0 SCAN END
Sample RTP File 2
The same protocol information could be also provided by specifying a CSL at each volume
FileVersion: 1 ResolutionOfTime: volumes ApplyHRF: yes NrOfConditions: 3 "Baseline" 128 128 128 No "Faces" 255 0 0 Yes "Houses" 0 255 0 Yes NrofContrasts: 3 ContrastNames: "[-1 +1 0] Faces vs. Baseline" "[-1 0 +1] Houses vs. Baseline" "[ 0 -1 +1] Houses vs. Faces" ContrastVectors: -1 +1 0 -1 0 +1 0 -1 +1 InitialSelectionState: 1 1 3 ContrastColors: 255 0 0 0 255 0 0 200 255 BackgroundColor: 0 0 0 TextColor: 255 255 255 TimeCourseColor: 255 255 30 TimeCourseThick: 2 SCAN BEGIN 1 0 0 2 0 0 3 0 0 4 0 0 5 0 0 6 0 0 7 0 0 8 0 0 9 1 0 10 1 0 11 1 0 12 1 0 13 1 0 14 1 0 15 0 0 16 0 0 17 0 0 18 0 0 19 0 0 20 0 0 21 0 1 22 0 1 23 0 1 24 0 1 25 0 1 26 0 1 27 0 0 28 0 0 29 0 0 30 0 0 31 0 0 32 0 0 SCAN END
Sample RTP File 3
Assuming a TR of 2000 ms, the same information could be also provided in millisecond resolution (ResolutionOfTime: ms)
FileVersion: 1 ResolutionOfTime: ms ApplyHRF: yes NrOfConditions: 3 "Baseline" 128 128 128 No "Faces" 255 0 0 Yes "Houses" 0 255 0 Yes NrofContrasts: 3 ContrastNames: "[-1 +1 0] Faces vs. Baseline" "[-1 0 +1] Houses vs. Baseline" "[ 0 -1 +1] Houses vs. Faces" ContrastVectors: -1 +1 0 -1 0 +1 0 -1 +1 InitialSelectionState: 1 1 3 ContrastColors: 255 0 0 0 255 0 0 200 255 BackgroundColor: 0 0 0 TextColor: 255 255 255 TimeCourseColor: 255 255 30 TimeCourseThick: 2 SCAN BEGIN 0 0 0 16000 1 0 28000 0 0 40000 0 1 52000 0 0 SCAN END
The same information could be also specified by providing a CSL at each volume (or even at arbitrary time points)
Copyright © 2014 Rainer Goebel. All rights reserved.