Turbo-BrainVoyager v3.2

TBV Settings File

A ".tbv" settings file contains all relevant information to analyze incoming functional data, including information about the scanner, number of data points (volumes), number of slices and matrix size. If coupled to the IFIS system, a settings file is provided automatically, otherwise you have to fill in the necessary values. You can enter values for a TBV file directly in the file using any text editor. A more convenient and save way is to use the TBV Sttings dialog.

When processing of a run is started, the program reads the specifications in the current ".tbv" file and processes the incoming information accordingly. The following parameters have to be defined in the correct order within a TBV file. Note that strings referring to files and/or folders have to be enclosed within > " < signs, which allows specification of file names containing blanks. It is recommended to store referenced files in the same folder or in sub-folders with respect to the location of the .tbv file. This allows to specify locations of referenced files with relative paths (i.e. file locations should begin with "./", see example below) allowing to copy a prepared folder to a new location without breaking file references.

FileVersion: 4

The file version information is important to keep future versions of the program with potentially new entries in the file compatible with earlier versions. The current file version is "4".

MergeType: 0

This flag specifies whether the TBV file specifies a single-run (value "0") or a multi-run (value "1") analysis. Multi-run analyses are not yet fully supported.

Title: "NK_FFA_PPA"

Specifies a title for this run, which is shown in the top part of the Turbo-BrainVoyager program window.

ParadigmHelpFile: ""

Not used anymore, but this line must be present in the file. Refers to a help file specific for a paradigm/protocol, e.g."C:/Program Files/IFIS/Help/my_paradigm_help.html". If there is no specific help file, provide an empty string ("").

IFISFMRIAnalysisTests: tdat

Not used anymore, but this line must be present in the file.

IFISFMRIAnalysisOptions: tdat

Not used anymore, but this line must be present in the file.

RawDataBigEndian: 0

This describes the byte ordering of the data which can be either "1" or "0". A value of "1" specifies a "Big Endian" byte order and a value of "0" a "Little Endian" byte order. This information is important for determining whether the incoming data has to be "byte swapped" or not. Since Turbo-BrainVoyager can run on multiple platforms, it needs to compare the byte ordering of the data with the byte ordering used on the workstation running the program. If the byte ordering of the machine running Turbo-BrainVoyager is different from the byte ordering specified in the "RawDataBigEndian" variable, byte swapping is performed.

ShowGODlgAfterPreparation: 0

When this entry is set to "1" a "GO" dialog appears when real-time preprocessing has been prepared after pressing the Record button. This allows to better synchronize TBV processing with the scanner if necessary.

WatchFolder: "./Ser0004" [relative or absolute path]

The "WatchFolder:" entry specifies where the incoming data can be accessed for real-time analysis. Note that the folder must be enclosed by '" signs in order to allow path names containing blanks (see remark above). Access to the scanner data has to be established for each site with respect to the local network architecture (i.e. NSF mount, Samba or ftp). It is also possible to specify more than one watch folder by using the following command instead of the "WatchFolder:" setting:

WatchFolderList: "C:/TurboBrainVoyager/WatchFoldersList.txt"

Not used in current version. The "WatchFolderList:" entry specifies a text file containing a list of folders to be checked for incoming data. The specified text file must begin with the number of the subsequently listed watch folders. An example of a correct watch folder list file is shown next:

-------- WatchFoldersList.txt-----------

S:/realtime/data1/

S:/realtime/data2/

----------------------------------------

The next entry specifies the target folder which has to be enclosed in quotes, too, in order to allow for names containing blanks:

TargetFolder: "./Output_TAL/" [relative or absolute path]

The target folder sets the default directory in which the program saves the processed data (output directory). If this folder does not exist, it will be created (if possible) when starting processing.

DataType: ANALYZE_NW

The "DataType:" field specifies the type of the data produced by a particular manufacturer's scanner. Currently supported values are: SIEMENS_IMA (OLD Siemens format, Numaris 3.x), ANALYZE_NW (new Siemens format, Numaris 4.x; in order to work, this format requires a specific real-time export software module, contact Brain Innovation for details), ANALYZE_DRIN (for Philips scanners, for details contact Phhilips), PHILIPS_REC/PAR (for Philips post-run analysis), GE_I (standard GE format), GE_STANFORD (special file version used at Stanford University) and DICOM. Since most scanners are able to save their data now also in DICOM format during a scan (online image reconstruction), this format is supported and increasingly relevant for real-time processing. Note, however, that due to complex naming patterns of DICOM files, we support this format for online analysis only for some manufacturers. DICOM can always be used after a functional run is complete (post-run, near real-time analysis); in this case you may use the "Rename DICOM" tool in the "File" menu to produce file names, which can be read by Turbo-BrainVoyager. The program also supports SIEMENS_DICOM_MOSAIC files for real-time and offline analysis in case that each mosaic file contains one functional volume.

BEGIN: DATA TYPE SPECIFIC ENTRIES

The next entries specifies the necessary information to look for the first file of the current functional run. With this information, the program can predict also subsequent file names containing further scans. The respective entries depend on the value of the "DataType:" entry.

For the SIEMENS_IMA data type (not used on modern Siemens scanners anymore since they use DICOM export), the following three entries have to be specified as shown next:

SiemensPatientID: 513

SiemensFirstStudyNr: 2

SiemensFirstImageNr: 4

From this information, a Siemens ".IMA" file can be constructed as "513-2-4.ima" which would be the first file, Turbo-BrainVoyager would look for.

For the GE_I data type, the following two entries have to be specified:

GESeriesNr: 3

GEFirstImageNr: 26

With the series number ("GESeriesNr") and the first image number ("GEFirstImageNr") together with the value of the "WatchFolder"), the program can predict the exact file name and location of the expected data. As soon as that data arrives, it starts processing.

For the GE_STANFORD data type, the following two entries have to be specified:

PFileHeader: "E06027S003P14848.7"

SliceTimeLooping: 1

The "PFileHeader:" refers to a header file containing all the information necessary to locate and read this data type. This format works only post-run, near real-time, since the whole data of run resides in a single file. The ordering of the data in the file can be "slices -> time points" or "time points ->slices". This can be controlled with the "SliceTimeLooping" parameter.

For the ANALYZE_NW data type (not necessary anymore on modern Siemens scanners since they use DICOM export), the following entry has to be specified:

FirstFileName: "Analyze00001.img"

For the ANALYZE_DRIN data type, the following entry has to be specified:

FirstFileName: "1.00001.img"

This entry specifies the full name of the first file to process. The software splits the number (in the example "1") from the file name and then incrementally predicts the names of the succeeding files (i.e. "1.00002.img", "1.00003.img" etc.). Each Analyze file contains one volume (once all slices) of the time series. The left part of the file name (here "1.") must be constant during one functional run and normally reflects the number of a run within a session (series number). This allows to place multiple runs within the same directory.

For the PHILIPS_REC data type, the following entry has to be specified:

FirstFileName: "data.rec"

This entry specifies the full name of the REC file containing all the data of a run.

For the DICOM and SIEMENS_DICOM_MOSAIC data types, the following entries have to be specified:

FirstFileName: "subj-0014-0001-0001.dcm"

DicomNameDelimiter: "-"

DicomNameExtension: "dcm"

DicomFirstVolumeNr: 1

DicomFirstImageNr: 1

The first file name specifies the first file from which to read the data, which can be a single slice (DICOM format) or a mosaic file (SIEMENS_DICOM_MOSAIC). In the latter case, the mosaic file contains all slices of the first volume arranged in a "mosaic picture". The "DicomNameDelimiter:" and "DicomNameExtension:" fields describe the naming scheme of the Dicom files. When using the "Rename Dicom" tool of Turbo-BrainVoyager, the files will be labelled as "<fixed_name>-<series_nr>-<volume_nr>-<image_nr>.dcm". If you do not use the "Rename Dicom" tool, describe the delimiter and extension. Note that the program can only read files, which have a fixed left string and follow the logic "<fixed_name><delimiter><volume_nr><delimiter><image_nr>.<extension>". Although the program can extract the volume and image number from the provided first file name, you must provide these values in the "DicomFirstVolumeNr:" and "DicomFirstImageNr:" entries.

For most data formats (PHILIPS_REC, ANALYZE_DRIN, ANALYZE_NW, DICOM, SIEMENS_DICOM_MOSAIC), the following fields must be specified next:

InplaneFoVX: 224

InplaneFoVY: 224

SliceThickness: 3.0

GapThickness: 1.0

These values are important for defining the resolution (voxel size) of the data. Knowing the voxel size is important for proper visualization in the orthographic view and for correct computation during motion correction. The "InplaneFoVX:" and "InplaneFoVY:" values describe the size of the imaged rectangular region (slice), measured in millimeter. If these values are divided by the dimensions of an image (see "MatrixSizeX:" and "MatrixSizeY:" below), the size of a voxel is determined for two (inplane) dimensions. The "SliceThickness:" value directly defines the size of a voxel in the third dimension (in mm). The "GapThickness:" value completes the information by specifying whether a gap has been left between the slices.

END: DATA TYPE SPECIFIC ENTRIES

After the format specific entries, the following entries must follow for all formats.

TimeOutSeconds: 10

This entry specifies how long the program maximally waits for an expected file name. If the expected file does not arrive in the watch folder(s) within the specified number of seconds, the program stops reporting a "TIME OUT ERROR".

MatrixSizeX: 64

MatrixSizeY: 64

These two values specify the dimensions of an individual slice. EPI images typically contain 64 x 64 pixels.

Only for the SIEMENS_DICOM_MOSAIC format, the following two entries have to follow:

MosaicResolutionX: 384

MosaicResolutionY: 384

In this data format, the individual slices comprising one volume are packed in a "mosaic" image. The ordering of pixel data within a mosaic image has to be sorted out by the program to get individual slices. The two values "MosaicResolutionX:" and " MosaicResolutionY:" specify the resolution of one mosaic image. With the example values "384" x "384", a maximum of 6 x 6 = 36 images with a resolution of 64 x 64 are located in one file.

Only for the SIEMENS_IMA format, the following two entries have to follow:

SiemensMosaicSequence: 1

SiemensMosaicResolution: 256

SiemensFixedRunNumber: 0

If the "SiemensMosaicSequence:" entry is set to "1", the individual slices comprising one volume are packed in a "mosaic" image. The ordering of pixel data within a mosaic image has to be sorted out by the program. The resolution of one mosaic image is specified in the "SiemensMosaicResolution:" entry, which is "256"in our example. In one such file (256 x 256) 16 slices of a resolution of 64 x 64 are stored. If more than 16 slices comprise one functional volume, the remaining slices are typically stored in a second mosaic file. Thie "SiemensFixedRunNumber:" entry specifies a particular version of the Siemens file naming scheme (for more information, see section "Technical details"). Typically, Siemens uses the scheme <pat_id>-<study_nr>-<image_nr>.ima where <pat_id> is constant throughout a scanning session and <image_nr> runs continously from the first image scanned up to the last image of a session. The <study_nr> changes for each study, which can be a scout, a structural measurement etc. During a functional run, each volume is normally treated as a "study" with respect to the file naming scheme and is, thus, incremented.. There is now also the possibility that new Siemens scanners/sequences keep the study number constant throughout a functional run resembling a "series" number in the GE folder/file naming scheme. The entry "SiemensFixedRunNumber:" is used to select between these two file naming possibilities.

NrOfVolumes: 110

This entry specifies the number of volumes which are expected to be recorded during the functional run. In case the sequence is aborted, less volumes might be actually processed.

NrOfVolumesToSkip: 2

This entry specifies the number of volumes which will be skipped at the beginning and, thus, not included in the statistical analysis. Skipping a few volumes at the beginning is usually performed to exclude the T1-saturated initial scans leading to very high signal values. T1 weighting drops quickly and reaches a steady-state after a few volumes. Although TBV does not include the specified number of to-be-skipped EPI volumes in the statistical analysis, it is reading the very first volume for display in the Multi-Slice, Single Slice and Volume View. While high T1 weighting is a problem for statistical time series analysis, it is useful for visualization because it shows structural information (gyri/sulci).

NrOfSlices: 30

This entry specifies the number of slices comprising one functional volume, in this example "30".

SlicePrefix: "NK_FFA_PPA-"

ProjectName: "NK_FFA_PPA"

These two settings are used for saving (processed) data to the specified "TargetFolder" in BrainVoyager format. The names of all written files are based on the name specified in the "ProjectName" entry. Most data structures are saved at the end of a functional run but ROI time course data is saved incrementally and can be used for custom real-time analysis. The program saves the following files: a FMR project file (e.g. "NK_FFA_PPA.fmr"), as many slice time course (STC) files as there are slices (e.t. "NK_FFA_PPA-1.stc" ... "NK_FFA_PPA-30.stc"), a stimulation protocol (PRT) file (e.g. "NK_FFA_PPA.prt") containing also behavioral data if present, a AMR file (e.g. "NK_FFA_PPA.amr") and VMR file (e.g. "NK_FFA_PPA_EPI.vmr") containing the image information from the first volume, which is used for display as described above. If 3D motion correction is enabled, a motion correction log file (i.e. "NK_FFA_PPA_3DMC.log") is saved as well as a motion correction design matrix file (e.g. "NK_FFA_PPA_3DMC.rtc"). There will be also a file written containing statistical maps (i.e. "NK_FFA_PPA.mps") and a file containing results from the performed General LInear Model (e.g. "NK_FFA_PPA.glm"), a contrast file (e.g. "NK_FFA_PPA.ctr") and a file containing any selected ROIs (e.g. "NK_FFA_PPA.roi") .

TR: 2000

This entry specifies the time between two consecutive measurements of the same slice. It determines the resolution of the x-axis in the time course, motion correction and behavioral data plots; in this example, each data point represents 2 seconds of elapsed time.

InterSliceTime: 66

This entry specifies the time gap from one slice to the next within a functional volume. It will be used in the future for inter-slice timing correction, which is not performed in the current version of the program.

ROIColorsFile: "./ROISelectionColors.rcd" [relative or absolute path]

This entry specifies a file defining colors to be used for ROIs. If you want the program to use default colors, set this entry to an empty string ("").

MultiSliceROISelection: 3

The value of this entry specifies how many slices should be used to define ROIs. If the value is "1", only voxels of the current slice are used when dragging a ROI or when CTRL-clicking on a voxel. If the value is larger than "1", slices above and below the current slice are used in addition to define a ROI.

Threshold: 3

This value specifies the statistical threshold used to "clip" the incrementally computed contrast maps. It is a t value, which must be equal to or larger than 1.0. The threshold can be changed during (or after) a functional run, for details see section Keyboard and Mouse functions.

ClusterSizePixels: 3

This value specifies the cluster threshold used to "clip" the statistical maps. A color-coded voxel is shown, if the map value at this point exceeds 1) the statistical threshold and 2) belongs to a cluster with at least the number of connected pixels also exceeding the statistical threshold. If a statistical map value does not reach these two criteria, the "background" value (EPI, inplane, VMR, SRF) is shown at that location.

NrOfColumns: 6

NrOfRows: 5

These entries specify the layout of the display, i.e. how the slices are arranged in rows and columns. Since the Brain Window is a square (Windows version), these two values should be the same in order to get a display with square pixels (assuming that the slice images are also square, i.e. 64x64). Make sure that the product "NrOfColumns:" x "NrOfRows:" is equal or larger than the number of scanned slices per volume, otherwise some images will not be shown in Multi-Slice View.

ForceTRDelay: 0

TBV is normally faster in processing then the time specified in the TR value. Since the data arrives incrementally during real-time recording, the program tries to read the data until it is available for processing. If the "ForceTRDelay" entry is set to "1" instead of "0", TBV will wait until the time of a TR has passed before it attempts to read the data. This might be useful to avoid reading of data before it is completely written, which seems relevant for some scanners. This option is also useful if one wants to reprocess data on disk at a later time point at the same speed as used during online scanning.

StimulationProtocol: "./FFA_PPA.prt" [relative or absolute path]

This is a standard BrainVoyager protocol file defining the intervals of conditions used in a experiment. In a Eloquence/IFIS environment, a "TDatFile" entry must be specified instead of a protocol. The TDAT fie is incrementally written during real-time anlaysis with detailed information about the blocks/trials/events occurring within the run, including behavioral data. For details of the TDAT file, see section "The IFIS TDAT file". A protocol or TDAT file is the basis for statistical computations since (part of) the design matrix (predictors of interest) is automatically created from the protocol. Whereas a TDAT file is created automatically by the Eloquence/IFIS system, you can create a protocol file using the "Stimulation Protocol" dialog.

ContrastFile: "./FFA_PPA.ctr" [relative or absolute path]

TBV is able to build contrasts automatically (see below) using the condition predictors created from the protocol. Using a contrast file, desired contrasts may be specified explicitly. To use automatic contrast definition, set "ContrastFile" to the empty string ("").

AutoContrastGenerationLevel: 2

If no contrast file is specified, TBV generates contrasts automatically. If "AutoContrastGenerationLevel" is set to "1", one contrast is defined for each main condition predictor. If the value is "2", predictors testing all pairs between main conditions are additionally defined.

DriftConfoundPredictors: 1

This entry may be used to defined confound predictors for the removal of temporal drifts in the data. If the value is "1", a linear trend confound predictor is added to the design matrix (recommended option). If the value is larger than "1", Discrete Cosine Transform (DCT) predictors are added to the design matrix.

MotionCorrection: 1

This entry specifies whether 3D motion detection and correction should be performed ("1") or not ("0").

SpatialGaussianSmoothing: 1

SpatialSmoothingFWHM: 4

If "SpatialGaussianSmoothing" is turned on ("1"), each volume is spatially smoothed prior to incremental statistical analysis using a kernel width in millimeter specified in the "SpatialSmoothingFWHN" entry.

OverlayInplaneData: 0

If this entry is specified to "1", the program will read slices form an extra scan (T1 or T2 weighted), which will be displayed in the Multi-Slice, Single Slice and Volume View. During real-time analysis, the user can toggle between the EPI slices and the slices from the extra scan (normally high-resolution anatomical images). The images of the extra scan have to be coplanar ("inplane"), which means that the extra scan must contain the same number of slices with the same slice positions as the functional scans. Only if this entry is set to "1", the following information has to be provided (most formats are supported, here demonstrated for DICOM format):

OverlayInplaneFolder: "./" [relative or absolute path]

OverlayInplaneDataType: DICOM

OverlayInplaneFirstFileName: "NicKil_Coplanar-00001.dcm"

OverlayInplaneMatrixSizeX: 256

OverlayInplaneMatrixSizeY: 256

The entry "OverlayInplaneDataType:" specifies the format of the (high-resolution) inplane extra scan. This will be in most cases the same or a similar format as used in the "DataType:" field. Supported formats are DICOM, GE_I, GE_MR, ANALYZE_DRIN, ANALYZE_NW and SIEMENS_IMA. The "OverlayInplaneFolder:"specifies the folder where the inplane scan has been stored. Note, that the inplane data must be recorded prior to the functional run. The "OverlayInplaneFirstFileName:" entry specifies the name of the first file (which may be the only file for some formats, e.g. ANALYZE). Together with the specifed folder, this information tells the program where to find the data of the extra scan. The two entries "OverlayInplaneMatrixSizeX:" and "OverlayInplaneMatrixSizeY:" specify the dimensions of the inplane images. Note, that these can be higher than the functional (EPI) images; the program will automatically adjust the different matrix sizes of the functional and inplane scans. Note, however, that the aspect ratio between the dimensions of the functional data and the coplanar data must be identical.

FlipSliceOrderInMultiSliceView: 1

FlipSliceOrderInVolumeView: 1

These entries specify whether the order of the slices should be reversed. If axial slices are recorded from inferior to superior, the 3D visualization in the volume view would show the brain upside down because the first slice encountered is drawn at the top followed by the second slice and so on. To visualize the brain adequately, set this value to "1" (default). Note: At present only the second value is used setting the across-slices axis flip for both the multi-slice and the volume view. Note also that in v2.4 this setting can be set in the TBV Settings file and not in the TBV Settings dialog.

IntraSessionMotionCorrection: 0

As default, motion correction (if enabled) aligns each incoming volume to the first volume of the run. With the "IntraSessionMotionCorrection" entry, it is possible to align images to an earlier run if multiple runs are performed with the same subject in one session using the same slice position parameters in subsequent runs. If this entry is enabled, the following entry has to be provided:

IntraSessionMotionCorrectionFile: "NicKil-Motion.fmr"

This entry specifies the previous functional run to which the current run should be aligned.

OverlayOnVMRMode: 3

This entry allows to specify visualization on high-resolution 3D data sets (if value > "0") With a value of "1', a intra-session 3D data set has to be provided. Slice position information of the intra-session 3D data set must be provided in a "FMRVMRAlignVMRPosFile", which is generateed automatically for the "ANALYZE_NW" format. If the value is "2", an AC-PC normalized file is expected together with a intrasession to AC-PC spatial transformation file. If the value is "3", a Talairach normalized file is expected together with an AC-PC transformation file and a Talairach landmark file as shown in these example entries:

FMRVMRAlignVMRPosFile: "./NicKil_Ser000X/NicKil_anatomy/Ana0002/Analyze00001.pos"

ACPCTransformationFile: "./NicKil_I/NK1_INH_ACPC.trf"

TalairachCerebrumBorderFile: "./NicKil_I/NK1_INH_ACPC.tal"

TalairachVMRFile: "./NicKil_I/NK1_INH_TAL.vmr"

OverlayOnSRFMode: 2

This entry allows to specify visualizations on surface-rendered cortex meshes (if value > "0" and "OverlayOnVMRMode > "0"). With a value of "1", one cortex mesh has to be provided. The mesh must be in the same space as the space used for visualization on a high-resolution 3D data set. With a value of "2", two cortex meshes, e.g. one for the left and one for the right hemisphere, have to be provided as shown in the following example entries:

SRFFileLH: "./NicKil_I/NK_TAL_LH_RECOSM_SPH.srf"

SRFFileRH: "./NicKil_I/NK_TAL_RH_RECOSM_SPH.srf"

FeedbackTargetFolder: "./target_TAL/"

This entry needs only to be filled with a valid folder string if the neurofeedback module is used. If a valid folder is provided, ROI intensity values (graphically) fed back to the subject are sved incrementally in that folder.

As an example, a complete settings file looks like this:

----------------------------------- NK_FFA_PPA_TAL-1.tbv -----------------------------------------

FileVersion: 4

MergeType: 0

Title: "NK_FFA_PPA"

ParadigmHelpFile: ""

IFISfMRIAnalysisTests: tdat

IFISfMRIAnalysisOptions: tdat

RawDataBigEndian: 0

ShowGODlgAfterPreparation: 0

WatchFolder: "./NicKil_Ser000X/NicKil_PPA_FFA/Ser0004/"

TargetFolder: "./target_TAL/"

DataType: ANALYZE_NW

FirstFileName: "Analyze00001.img"

InplaneFoVX: 224

InplaneFoVY: 224

SliceThickness: 3

GapThickness: 0.99

TimeOutSeconds: 10

MatrixSizeX: 64

MatrixSizeY: 64

NrOfVolumes: 110

NrOfVolumesToSkip: 2

NrOfSlices: 30

SlicePrefix: "NK_FFA_PPA-"

ProjectName: "NK_FFA_PPA"

TR: 2000

InterSliceTime: 66

ROIColorsFile: "./ROISelectionColors.rcd"

MultiSliceROISelection: 3

Threshold: 3

ClusterSizePixels: 4

NrOfColumns: 6

NrOfRows: 5

ForceTRDelay: 1

StimulationProtocol: "./FFA_PPA.prt"

ContrastFile: "./FFA_PPA.ctr"

DriftConfoundPredictors: 1

AutoContrastGenerationLevel: 2

MotionCorrection: 1

SpatialGaussianSmoothing: 1

SpatialSmoothingFWHM: 4

OverlayInplaneData: 0

FlipSliceOrderInEPISliceView: 1

FlipSliceOrderInEPIOrthoView: 1

IntraSessionMotionCorrection: 0

OverlayOnVMRMode: 3

FMRVMRAlignVMRPosFile: "./NicKil_Ser000X/NicKil_anatomy/Ana0002/Analyze00001.pos"

ACPCTransformationFile: "./NicKil_I/NK1_INH_ACPC.trf"

TalairachCerebrumBorderFile: "./NicKil_I/NK1_INH_ACPC.tal"

TalairachVMRFile: "./NicKil_I/NK1_INH_TAL.vmr"

OverlayOnSRFMode: 2

SRFFileLH: "./NicKil_I/NK_TAL_LH_RECOSM_SPH.srf"

SRFFileRH: "./NicKil_I/NK_TAL_RH_RECOSM_SPH.srf"

FeedbackTargetFolder: "./target_TAL/"

---------------------------------------------------------------------------------------------------