BrainVoyager File Formats

The informations in this chapter is for advanced users who want to combine custom-made software with BrainVoyager. Using the informations provided here, you are able to use the data produced at various processing stages for your own software, i.e. you can read BrainVoyager data files and do additional postprocessing. You can also do your own preprocessing (i.e. motion correction, statistics) and then save your data as BrainVoyager file types for further processing and visualization.

The following file types are described in this chapter:

  • FMR files - functional slice-based projects

  • STC files - functional slice-based data belonging to an FMR project file

  • PRT files - protocol files describing experimental conditions

  • AMR files - anatomical or functional inplane data often belonging to an FMR project file

  • MAP files - Slice-based files containing result of any statistical test

  • VMR files - 3D anatomical projects

  • VTC files - 3D space x 1D time functional data; typically in Talairach space

  • GLM files - 3D statistical files containing the results of multiple regression analysis

  • VMP files - 3D statistical file containing result of any statistical test

  • SRF files - surface meshes typically of heads and (morphed) cortical hemispheres

  • SMP files - surface-based statistical file containing result of any statistical test


The format of FMR files

FMR project files are simple text files containing the information defining the project. The actual time course data is contained in STC ("slice time course") files which are referenced in the FMR file. The file need not be changed directly, all entries can be conveniently inspected and modified using the "Edit FMR File Specifications" dialog, which can be invoked with the "File -> Edit FMR infos..." menu item. The information below is useful for programmers who want to read or write FMR files.

The current format of FMR project files is version 2, which was introduced with BrainVoyager v4.6. After the description of this format, the previous FMR format will be described below. An FMR file consists of a fixed sequence of 25 entries. Most entries are self explanatory. An example FMR file with short explanatory descriptions is given in the following table:

FMR FILE | DESCRIPTION
FileVersion: 2 | The version of the FMR file (*1)
NrOfVolumes: 126 | Number of time points per pixel (data points, samples)
NrOfSlices: 15 | Number of recorded slices
NrOfSkippedVolumes: 2 | Number of volumes skipped during project creation (*1)
Prefix: CG_OBJECTS- | Link to STC files containing the time series data
TR: 4500 | TR [msec] (*1)
InterSliceTime: 155 | Inter slice time (IST) [msec] (*1)
TimeResolutionVerified: 1 | Flag ensuring that "TR" and "IST" are correct (*1)
ResolutionX: 64 | Nr of columns of slice image matrix
ResolutionY: 64 | Nr of rows of slice image matrix
LoadAMRFile: CG_OBJECTS_firstvol.amr | Link to inplane anatomical AMR project (*2)
ShowAMRFile: 1 | flag: 1 - show linked AMR, 0 - show first image of STCs
ImageIndex: 0 | slice shown in the upper left subwindow
LayoutNColumns: 5 | Four columns of slices are shown
LayoutNRows: 3 | Four rows of slices are shown
LayoutZoomLevel: 2 | Zoom level range: 1 to 10 (1 = slice resolution)
SegmentSize: 8 | Subdivision (vertical lines) in time course plots (*3)
SegmentOffset: 2 | Offset for first vertical line of subdivisions
ProtocolVersion: 2 | Version of protocol (version 2 since BV2000 v3.5)
ProtocolFile: CG_OBJECTS.prt | Link to the protocol (.PRT) file (*4)
InplaneResolutionX: 1.5625 | Resolution of one pixel in x dimension [mm] (*1)
InplaneResolutionY: 1.5625 | Resolution of one pixel in y dimension [mm] (*1)
SliceThickness: 5.0000 | Slice thickness without slice gap [mm] (*1)
SliceGap: 1.0000 | The gap between slices [mm] (*1)
VoxelResolutionVerified: 1 | Flag ensuring that pixel resolution values are correct (*1)

(*1) New in BrainVoyager 2000 v4.6.

(*2) The AMR file might be from a "real" T1-weighted scan or showing the functional slices itself, i.e. the first scan with high T1-contrast.

(*3) A vertical line is placed every n-th measurement, i.e. every 10th. This subdivision is only used, if no protocol file is linked

(*4) If a protocol is linked, time course plots are subdivided based on the protocol and not on the values for SegmentSize and SegmentOffset

An important entry is the "Prefix:" string, which specifies a link to "STC" files which actually contain the time series data. For each slice, there is an extra STC file. In the example file shown above, the file "CG_OBJECTS-4.stc" would contain all time series data of slice 4, a stack of 126 images.

The version "1" format of FMR files consists of the following 19 entries:

FMR FILE | DESCRIPTION
NrOfVolumes: 260 | number of time points
NrOfSlices: 16 | number of recorded slices
NrOfFirstVolume: 270 | info only, not used internally
NrOfFirstSlice: 1 | info only, not used internally
Prefix: r1_slice- | link to STC files (i.e. r1_slice-1.stc - r1_slice-16.stc)
TR: 2081 | TR (*1)
InterSliceTime: 100 | Inter slice time (*1)
ResolutionX: 64 | nr of columns
ResolutionY: 64 | nr of rows
LoadAMRfile: func_as_anat.amr | Link to 2D anatomical AMR project (*2)
ShowAMRFile: 1 | flag: 1 - show linked AMR, 0 - show functional slices from STC
ImageIndex: 0 | slice shown in the upper left subwindow (should be set to 0)
LayoutNColumns: 4 | Four columns of slices are shown
LayoutNRows: 4 | Four rows of slices are shown
LayoutZoomLevel: 3 | Zoom level range: 1 to 10 (integral multiples of slice resolution)
SegmentSize: 10 | Subdivision (vertical lines) in time course plots (*3)
SegmentOffset: 0 | Offset for first vertical line of subdivisions
ProtocolVersion: 2 | Version of protocol (version 2 since BrainVoyager v3.5 and higher)
ProtocolFile: Stimulation.prt | Link to the protocol (.PRT) file (*4)

(*1) New in BrainVoyager 2000. In a previous version (v0.9), the entries "FileType: stc" and "Delimiter: -" were used but are no longer in use.


The format of STC Files

A STC file (STC = "slice time course") contains the functional data (time series) of one slice of an experimental run. During FMR project creation, as many STC files as there are slices will be created. A FMR project links to the STC files with an "STC Prefix". If the name of the FMR project is, for example, "CG_OBJECTS.FMR", the STC prefix will be "CG_OBJECTS-" after project creation. The STC prefix changes when the data is preprocessed to reflect the applied preprocessing steps but it can also be changed to any desired name. When BrainVoyager accesses time course data, it uses the STC prefix and a slice number to access the correct STC file. If the STC prefix is "CG_OBJECTS-" and the number of slices is "15", then it assumes that 15 STC files exist in the same folder as the FMR project with the names:

CG_OBJECTS-1.stc
CG_OBJECTS-2.stc
:
CG_OBJECTS-15.stc

A single STC file simply contains as many images as there are repeated measurements of the slice. This number is referred to as "NrOfVolumes" within the FMR text file. Prior to the series of images, a very short header is defined, containing only the image dimensions "NrOfRows" and "NrOfColumns" as 2 byte values (unsigned short). These two values are compared with the "ResolutionY" and "ResolutionX" values of the corresponding FMR project.

Each data element (intensity value) is represented in 2 bytes (unsigned short). The data is organized in three loops:

NrOfVolumes

NrOfRows

NrOfColumns


The format of PRT files

PRT files are simple text files containing the informations defining a stimulation protocol. The entries should normally not be changed directly in the file due to the risk of introducing errors. You can use the "Stimulation Protocol dialog" to specify the protocol. The information below is for programmers who want to read or write PRT files.

A PRT file starts with a file version entry and a ResolutionOfTime entry (both new since BV v4.2). The ResolutionOfTime entry can be set to "Volumes" or "msec". If set to "Volumes", the protocol behaves identical to the PRT format prior to BV v4.2. If set to "msec", times of events can be specified not in multiples of TR's (i.e. volumes) but in msec resolution. This is particularly important for event-related experiments.
The next seven entries specify global settings for the appearance of a stimulation protocol within time course plots and dialogs for defining statistical questions. These general settings are followed by the actual entries defining the conditions of the protocol. The entry "NrOfConditions:" specifies how many different conditions occurred within the experimental run. For each condition, a variable-length block of informations follows defining the intervals belonging to that condition. An example PRT file with short descriptions is shown below (note that such descriptions are not allowed in real PRT files):

PRT FILE |  | DESCRIPTION
FileVersion: | 2 | file version (new entry since BrainVoyager v4.2)
ResolutionOfTime: | Volumes | Volumes or msec (new entry since BrainVoyager v4.2)
Experiment: | Objects in LVF or RVF | name of conducted experiment
BackgroundColor: | 0 0 0 | RGB components for background color of time course plots
TextColor: | 255 255 217 | RGB components for text color, i.e. axis labels
TimeCourseColor: | 255 255 255 | RGB components for line color of time course plots
TimeCourseThick: | 3 | Line thickness of time course
ReferenceFuncColor: | 255 255 51 | RGB components for line color of reference time course plot
ReferenceFuncThick: | 2 | Line thickness of reference time course
NrOfConditions: | 3 | number of conditions within run
Fixation |  | name of first condition
9 |  | number of intervals belonging to first condition
1 | 2 | interval specifying first piece of time belonging to condition 1
11 | 18 | second interval belonging to condition 1
: | : |
123 | 126 | Nineth interval belonging to condition 1
Color: | 192 192 192 | Color for vertical segments in time course plots belonging to condition 1
Images, left |  | name of second condition
4 |  | number of intervals belonging to second condition
3 | 10 |
35 | 42 | (*1)
67 | 74 |
99 | 106 |
Color: | 255 0 0 | Color for vertical segments in time course plots belonging to condition 2
Images, right |  | name of third condition (last condition since NrOfConditions = 3)
4 |  | number of intervals belonging to third condition
19 | 26 |
51 | 58 |
83 | 90 |
115 | 122 |
Color: | 0 210 0 | Color for vertical segments in time course plots belonging to condition 3

(*1) Intervals can be in "Volumes" (multiples of TR, measurements, time points) or in "msec". If in "Volumes", the interval values are inclusive, i.e., the pair [35 42] defines an interval of 8 units (time points).The actual duration of an interval is obtained by multiplying an interval with the value of the TR. If, for example TR = 3000 ms, the duration of the mentioned interval is (42-35+1)*3000ms = 8*3000ms = 24sec. Intervals values are interpreted as msecs if the "ResolutionOfTime" entry specifies "msec".

The following figure shows the mapping between the entries in the file and corresponding values in the "Stimulation Protocol dialog":

The following figure shows the mapping between the protocol entries and the display within time course plots:


The format of MAP files

A MAP file contains statistical results as a stack of slices. Results from all statistical tests (except GLM) which were run from a FMR project are internally stored as a MAP file. The binary file contains a variable-length header followed by the data containing statistical values in 4 byte float format.

MAP header

BYTES | DATA TYPE | DEFAULT | DESCRIPTION
2 | short int | 1 | NrOfSlices/MapType (t, F, correlation, crosscorrelation etc.) (*1)
2 | short int |  | NrOfMaps (equal to NrOfSlices)
2 | short int |  | DimY (image dimension in number of pixels)
2 | short int |  | DimX (image dimension in number of pixels)
2 | short int |  | ClusterSize
4 | float |  | Statistical threshold, critical value
4 | float |  | Statistical threshold, max value
2 | short int |  | NrOfLags (ONLY PRESENT IF MapType = crosscorrelation !!)
2 | short int | 9999 | Reserved (MUST BE THIS VALUE)
2 | short int | 2 | FileVersion (VALUE MUST BE 2)
N | byte | <untitled> | Name of an RTC file (used to compute % signal changes etc.) (*2)

(*1) A MAP file may contain any statistic. For proper default settings after reading a MAP file some values for MapType are reserved, i.e., 1 -> t- or F-values, 2 -> correlation values, 3 -> cross-correlation values. For historical reasons, the first entry represents two informations simultaneously, namely MapType and NrOfSlices. The value of this field is computed as follows
value = MapTypeCode + NrOfSlices
The MapTypeCode is as follows: 0 for t-, and F- maps, 10000 for correlation maps, 20000 for crosscorrelation maps. If, for example, a crosscorrelation map has been saved and NrOfSlices equals 15, the NrOfSlices/MapType value will be 20015.

(*2) Variable length, the end of the name is indicated by '0'.

MAP data

A map file contains NrOfMaps (= NrOfSlices) 2D statistical images. Each image contains DimY*DimX data points. Each data point (statistical value) is represented in 4 bytes (float). Each slice is preceded by a 2 byte (short int) value representing the slice index (i.e. '0' for slice 1 and 'NrOfMaps-1' for the last slice). There are some additional informations about MAP files which are specific to correlation and cross-correlation maps.

Correlation maps. If the statistical map consists of correlation values, they are bounded between -1.0 and 1.0. For historical reasons the values are, however, stored in a "flipped" manner between 0.0 and 1.0 for positive correlation values and 0.0 and -1.0 for negative correlatio values:
saved_corr = 1.0 - corr { if corr > 0.0
saved_corr = -1.0 - corr { if corr < 0.0
saved_corr = 0.0 { if corr = 0.0
From these equations it is easy to get the correct corr values when reading correlation MAP files.

Cross-correlation maps. Cross-correlation tests involve the computation of many correlations of a single time series with shifted versions of a reference function. At each shift or lag, a correlation value is computed. Lag values are allowed to have only positive values. In cross-correlation maps, each data point (4 byte float) saves two values simultaneously, the lag value which yielded the highest correlation and the (positive) correlation value obtained at this lag value. The saved value is defined as follows:
saved_val = lag_of_max_corr + (1.0 - max_corr) { if max_corr > 0.0
saved_val = -lag_of_max_corr + (1.0 + max_corr) { if max_corr < 0.0
saved_val = 0.0 { otherwise
Note that in cross-correlation maps, both max_corr and lag_of_max_corr values must be positive. In the context of GLM maps (which internally use cross-correlation maps for "2 set color coding"), negative values for max_corr are, however, allowed. To retrieve the lag and correlation value back from the compound value, use code similar to this:
max_corr = saved_val - (int)saved_val;
lag_of_max_corr = (int)saved_val;


The format of VMR files

VMR files contain anatomical 3D data stored as bytes. The format is very simple consisting of a small header prior to the actual data. The only important point is that you understand how the three axes are ordered (see below).

VMR header

BYTES | DATA TYPE | DEFAULT | DESCRIPTION
2 | unsigned short | 256 | DimX, dimension of X axis
2 | unsigned short | 256 | DimY, dimension of Y axis
2 | unsigned short | 256 | DimZ, dimension of Z axis

VMR data

Each data element (intensity value) is represented in 1 byte. The data is organized in three loops:

DimZ

DimY

DimX

With the default values above, the total number of bytes (for data without header) is therefore:

DimX * DimY * DimZ = 16MB.

Note that the axes terminology follows the internal BrainVoyager (BV) format. The mapping to Talairach axes is as follows:

BV X front -> back = Y in Tal space
BV Y top -> bottom = Z in Tal space
BV Z left -> right = X in Tal space


The format of VTC files

A VTC file contains the functional data (time series) of one experimental run in a 3D format, i.e. in Talairach space. The binary file contains a variable-length header followed by the actual 4D data.

VTC header

BYTES | DATA TYPE | DEFAULT | DESCRIPTION
2 | short int | 2 | version number
N | byte |  | name of FMR file whose STC data has been transformed (*1)
M | byte | <none> | name of the linked protocol (PRT) file (*1)
2 | short int |  | NrOfVolumes (number of volumes, measurements, time points)
2 | short int | 3 | VTC-resolution, i.e. 3 -> one voxel = 3 x 3 x 3 mm (*2)
2 | short int | 57 | XStart (*3)
2 | short int | 231 | XEnd (*3)
2 | short int | 52 | YStart (*3)
2 | short int | 172 | YEnd (*3)
2 | short int | 59 | ZStart (*3)
2 | short int | 197 | ZEnd (*3)
2 | short int |  | Hemodynamic delay, simple shift value (*4)
4 | float |  | TR [ms] (*4)
4 | float |  | Hemodynamic function, delta parameter (*4)
4 | float |  | Hemodynamic function, tau parameter (*4)
2 | short int |  | Segment size, used for time course separation (*4)
2 | short int |  | Segment offset, used for time course separation (*4)

(*1) Variable length, the end of the name is indicated by '0'.

(*2) The VTC-resolution is defined with respect to the resolution of a VMR file. Typically, one VMR voxel has the resolution of 1 (Talairach) mm3. A VTC-resolution value of 3 means that one VTC voxel encompasses 3 x 3 x 3 = 27 VMR voxels. Other resolutions are possible, i.e. 1 and 2 since BrainVoyager v4.2

(*3) These values indicate the relative position within a VMR volume (must be a 2563 data set for Talairach VTC data, (see explanations below).

(*4) These values are included in the header only if the version number equals 2

VTC data

Each data element (intensity value) is represented in 2 bytes (unsigned short). The data is organized in four loops:

DimZ

DimY

DimX

DimT

The inner loop (DimT = NrOfVolumes) contains the time series for each VTC voxel. The spatial dimensions can be computed from the header info as follows:

DimX = (XEnd-XStart) / VTC-resolution
DimY = (YEnd-YStart) / VTC-resolution
DimZ = (ZEnd-ZStart) / VTC-resolution

With a VTC-Resolution of 3 and the default values provided above, this results in:

DimX = 58
DimY = 40
DimZ = 46

With these values and a typical NrOfVolumes of 200, the total number of bytes (for data without header) is therefore:

DimX * DimY * DimZ * NrOfVolumes * 2 = 42,688,000

or approximately 40MB.

Note that the axes terminology follows the internal BrainVoyager (BV) format. The mapping to Talairach axes is as follows:

BV X front -> back = Y in Tal space
BV Y top -> bottom = Z in Tal space
BV Z left -> right = X in Tal space


The format of GLM files

A GLM file contains the result of a multiple regression analysis, eventually performed across many runs of many subjects. In the most simple case, a GLM was based on the functional data (time series) of one experimental run in slice space (FMR project) or transformed 3D space (VMR/VTC project). The binary file contains a variable-length header followed by the actual stack of 3D data.
In the following the header definition of version 2 is shown as introduced with BrainVoyager 2000, version 4.4. Then the header definition of version 1 is described. Older GLM's with header version 1 can still be read by the latest BrainVoyager versions. Because of the newly introduced features, it is, however, recommended to recompute GLM's. All names, i.e. for files or predictors, are C-type strings with each character represented with 1 byte. All names are terminated with value zero. Therefore an empty string consists of just one value (0).

GLM header

BYTES | DATA TYPE | DEFAULT | SHORT DESCRIPTION
2 | short int | 2 | version number
1 | byte |  | ProjectType: 1 -> VTC-GLM, 0 -> FMR-GLM
4 | int |  | NrOfTimePoints, overall number across all included runs
4 | int |  | NrOfPredictors, for each predictor a separate 3D map is stored
4 | int |  | NrOfStudies, overall number of analyzed runs
1 | byte | 0 | SeparatePredictors: 0 -> no, 1 -> for each study, 2 -> for each subject
1 | byte | 1 | ZTransform: 1 -> time courses of runs have been z-transformed, 0 -> not
2 | short int | 3 | Resolution: 1, 2 or 3; 3 -> one voxel = 3 x 3 x 3 mm (*1)
1 | byte | 0 | SerialCorrelation: 1 -> Correction has been performed, 0 -> not
4 | float | -2.0 | MeanAR1Pre, mean lag1 autocorrelation without correction (-2.0, not used)
4 | float | -2.0 | MeanAR1Post, mean lag1 autocorr. after correction (-2.0, not used)
2 | short int | 57 | XStart (VTC-GLM) or NrOfColumns (FMR-GLM) (*2)
2 | short int | 231 | XEnd (VTC-GLM) or NrOfRows (FMR-GLM) (*2)
2 | short int | 52 | YStart (VTC-GLM) or NrOfSlices (FMR-GLM) (*2)
2 | short int | 172 | YEnd (VTC-GLM) or not present (FMR-GLM) (*2)
2 | short int | 59 | ZStart (VTC-GLM) or not present (FMR-GLM) (*2)
2 | short int | 197 | ZEnd (VTC-GLM) or not present (FMR-GLM) (*2)
1 | byte | 0 | CortexBasedStatistics: 1 -> has been used, 0 -> has not been used
4 | int | -1 | NrOfVoxelsForBonfCorrection
N | byte |  | CortexBasedStatisticsMaskFile: name of mask file
Begin of loop from analyzed study 1 to analyzed study 'NrOfStudies'
4 | int |  | number of time points of run 1
N_1 | byte |  | name of analyzed VTC file (run 1)
M_1 | byte |  | name of predictor defining RTC file (run 1)
: | : |  | :
4 | int |  | number of time points of run 'NrOfStudies' (last run)
N_NrOfStudies | byte |  | name of analyzed VTC file (last included run)
M_NrOfStudies | byte |  | name of predictor RTC file (last included run)
End of loop from analyzed study 1 to analyzed study 'NrOfStudies
Begin of loop from predictor 1 to predictor 'NrOfPredictors'
PN_1 | byte |  | name1 of predictor 1 (i.e., "predictor 1")
PM_1 | byte |  | name2 of predictor 1 (i.e., "stimuli in left visual field"
3 x 4 | int |  | R, G, B components of color for predictor 1 (*3)
: | : |  | :
PN_NrOfPredictors | byte |  | name1 of last predictor
PM_NrOfPredictors | byte |  | name2 of last predictor
3 x 4 | int |  | R, G, B components of color for last predictor (*3)
End of loop from predictor 1 to predictor 'NrOfPredictors'
NrOfTimePoints x NrOfPredictors | float |  | DesignMatrix
NrOfPredictors x NrOfPredictors | float |  | iXX: Inverse of DesignMatrix x DesignMatrix

(*1) The 'resolution' is defined with respect to the resolution of a VMR file. It matches the resolution of all analyzed VTC files (see definition of VTC files). Typically, one VMR voxel has the resolution of 1 (Talairach) mm3. A resolution value of 3 means that one GLM voxel encompasses 3 x 3 x 3 = 27 VMR voxels. Other resolutions, i.e. 1 and 2 are possible but are not fully tested yet.

(*2) For a VTC-GLM, these values indicate the relative position within a 2563 VMR volume (see explanations below). For a FMR-GLM (only possible with file version 2), only three of the six entries are used. Use the ProjectType entry to distinguish between a VTC-GLM and an FMR-GLM.

(*3) These predictor colors are not yet used in BrainVoyager but this is planned for an upcoming release.

GLM data

The GLM data contains DimP = 2 x NrOfPredictors + 3 sets of data. If the correction of serial correlations has been performed (check the SerialCorrelation flag), the data part contains 2 x NrOfPredictors + 4 data sets. Each data set contains a 3D representation of a statistical entity. The first 3D data set contains the multiple regression coefficient R for each voxel, the second data set contains the overall variance to be explained for each voxel (mean corrected sum-of-squares). These two 3D data sets are followed by NrOfPredictors 3D data sets containing the beta weights for each predictor for each voxel. This is followed by NrOfPredictors 3D data sets containing the products of a each predictor with the time course data (XY). Finally, a data set containing the mean values of the time courses for each voxel (which is zero, if the data has been z-transformed). In the case of corrected serial correlations (SerialCorrelation flag), a final data set contains the lag1 autocorrelations of the residuals for each voxel.
A single data element (i.e. beta weight) is represented in 4 bytes (float). The data is organized in four loops:

DimP

DimZ

DimY

DimX

The spatial dimensions can be computed from the header info as follows (for further informations, see definition of VTC files):

DimX = (XEnd-XStart) / resolution
DimY = (YEnd-YStart) / resolution
DimZ = (ZEnd-ZStart) / resolution

Note that the axes terminology follows the internal BrainVoyager (BV) format. The mapping to Talairach axes is as follows:

BV X front -> back = Y in Tal space
BV Y top -> bottom = Z in Tal space
BV Z left -> right = X in Tal space

The format of the header and data of version 1 GLM files

GLM header

BYTES | DATA TYPE | DEFAULT | DESCRIPTION
2 | short int | 1 | version number
4 | int |  | NrOfTimePoints, overall number across all included runs
4 | int |  | NrOfPredictors, for each predictor a separate 3D map is stored
4 | int |  | NrOfStudies, overall number of analyzed runs
1 | byte | 0 | flag: separate predictor for each study or not
1 | byte | 1 | flag: time courses of individual runs have been z-transformed or not
2 | short int | 3 | resolution, i.e. 3 -> one voxel = 3 x 3 x 3 mm (*1)
2 | short int | 57 | XStart (*2)
2 | short int | 231 | XEnd (*2)
2 | short int | 52 | YStart (*2)
2 | short int | 172 | YEnd (*2)
2 | short int | 59 | ZStart (*2)
2 | short int | 197 | ZEnd (*2)
Begin of loop from analyzed study 1 to analyzed study 'NrOfStudies'
4 | int |  | number of time points of run 1
N_1 | byte |  | name of analyzed VTC file (run 1)
M_1 | byte |  | name of predictor defining RTC file (run 1)
: | : |  | :
4 | int |  | number of time points of run 'NrOfStudies' (last run)
N_NrOfStudies | byte |  | name of analyzed VTC file (last included run)
M_NrOfStudies | byte |  | name of predictor RTC file (last included run)
End of loop from analyzed study 1 to analyzed study 'NrOfStudies
Begin of loop from predictor 1 to predictor 'NrOfPredictors'
PN_1 | byte |  | name1 of predictor 1 (i.e., "predictor 1")
PM_1 | byte |  | name2 of predictor 1 (i.e., "stimuli in left visual field"
3 x 4 | int |  | R, G, B components of color for predictor 1 (*3)
: | : |  | :
PN_NrOfPredictors | byte |  | name1 of last predictor
PM_NrOfPredictors | byte |  | name2 of last predictor
3 x 4 | int |  | R, G, B components of color for last predictor (*3)
End of loop from predictor 1 to predictor 'NrOfPredictors'
NrOfTimePoints x NrOfPredictors | float |  | Design matrix (built from individual RTC files)

(*1) The 'resolution' is defined with respect to the resolution of a VMR file. It matches the resolution of all analyzed VTC files (see definition of VTC files). Typically, one VMR voxel has the resolution of 1 (Talairach) mm3. A resolution value of 3 means that one GLM voxel encompasses 3 x 3 x 3 = 27 VMR voxels. Other resolutions, i.e. 1 and 2 are possible but are not fully tested yet.

(*2) For a VTC-GLM, these values indicate the relative position within a 2563 VMR volume (see explanations below). For a FMR-GLM (only possible with file version 2), only three of the six entries are used. Use the ProjectType entry to distinguish between a VTC-GLM and an FMR-GLM.

(*3) These predictor colors are not yet used in BrainVoyager but this is planned for an upcoming release.

GLM data

The GLM data contains DimP = 2 + NrOfPredictors sets of data. Each data set contains a 3D representation of a statistical entity. The first 3D data set contains the multiple regression coefficient R for each voxel, the second data set contains the overall variance to be explained for each voxel. These two 3D data sets are followed by NrOfPredictors 3D data sets containing the beta weights for each predictor for each voxel. A single data element (i.e. beta weight) is represented in 4 bytes (float). The data is organized in four loops:

DimP

DimZ

DimY

DimX

The spatial dimensions can be computed from the header info as follows (for further informations, see definition of VTC files):

DimX = (XEnd-XStart) / resolution
DimY = (YEnd-YStart) / resolution
DimZ = (ZEnd-ZStart) / resolution

Note that the axes terminology follows the internal BrainVoyager (BV) format. The mapping to Talairach axes is as follows:

BV X front -> back = Y in Tal space
BV Y top -> bottom = Z in Tal space
BV Z left -> right = X in Tal space


The format of VMP files

A VMP file contains statistical results in 3D format. Results of statistical tests computed within a VMR project are internally stored in a VMP file. You may save/load a VMP file using the GUI or scripting commands. The only statistical test which is not stored in a VMP internally is the GLM (multiple regression). However, a specified GLM contrast or contribution statistic is internally converted into a VMP prior to visualization and can be accessed like any other VMP.
The binary file contains a variable-length header followed by the data containing statistical values in 4 byte float format. To reduce the size of the data both on disk and in memory, only the subvolume containing functional data is stored. Prior to BrainVoyager 2000, statistical 3D maps were stored as VMR files in a simple byte format which resulted in a 16MB file per statistical map. A new VMP float map would have a size of 16MB *4 = 64MB if stored the same way. Due to the subvolume approach, the typical file size of a VMP file (containing 1 map) is about 8-10 MB.
In the following, the header definition of version 2 is shown as introduced with BrainVoyager QX. Then the header definition of version 1 is described as used in BrainVoyager 2000. Note that both programs (BV2000 since v4.6) can read both versions but only BrainVoyager QX reads and is able to display multiple VMPs. BrainVoyager 2000 will only read the first encountered map and it can only save version 1 files containing one map.

VMP header, file version 2 (BrainVoyager QX)

BYTES | DATA TYPE | DEFAULT | DESCRIPTION
2 | short int | 2 | version number
4 | int |  | NrOfMaps
4 | int | 2 | MapType (t-, F-, correlation, crosscorrelation etc.) (*1)
4 | int | 0 | NrOfLags, (only used if MapType = crosscorrelation)
Begin of loop over 'NrOfMaps' describing infos for each map
4 | int |  | ClusterSize for 3D map 1
1 | byte |  | EnableClusterCheck for 3D map 1
4 | float |  | Statistical threshold for 3D map 1, critical value
4 | float |  | Statistical color-only threshold for 3D map 1, max value
4 | int | 0 | df1, degrees of freedom for 3D map 1 (*2)
4 | int | 0 | df2, degrees of freedom for 3D map 1 (*2)
4 | int | 0 | Cortex-based Bonferroni correction value
3 | byte |  | R, G and B component of color for critical value
3 | byte |  | R, G and B component of color for max color-only threshold
1 | byte | 1 | EnableSMPColor for 3D map 1
4 | float | 1.0 | TransparentColorFactor for surface map 1
N_1 | byte |  | Name for 3D map 1
: | : |  | :
4 | int |  | ClusterSize for 3D map 'NrOfMaps'
1 | byte |  | EnableClusterCheck for 3D map 'NrOfMaps'
4 | float |  | Statistical threshold for 3D map 'NrOfMaps', critical value
4 | float |  | Statistical color-only threshold for map 'NrOfMaps', max value
4 | int | 0 | df1, degrees of freedom for 3D map 'NrOfMaps' (*2)
4 | int | 0 | df1, degrees of freedom for 3D map 'NrOfMaps' (*2)
4 | int | 0 | Cortex-based Bonferroni correction value
3 | byte |  | R, G and B component of color for critical value
3 | byte |  | R, G and B component of color for max color-only threshold
1 | byte | 1 | EnableSMPColor for 3D map 'NrOfMaps'
4 | float | 1.0 | TransparentColorFactor for 3D map 'NrOfMaps'
N_NrOfMaps | byte |  | Name for 3D map 'NrOfMaps'
End of loop over 'NrOfMaps'
4 | int | 256 | DimX of VMR from which 3D map was saved
4 | int | 256 | DimY of VMR from which 3D map was saved
4 | int | 256 | Dim Z of VMR from which 3D map was saved
4 | int |  | XStart (*3)
4 | int |  | XEnd (*3)
4 | int |  | YStart (*3)
4 | int |  | YEnd (*3)
4 | int |  | ZStart (*3)
4 | int |  | ZEnd (*3)
4 | int | 1 | resolution (*4)

VMP header, file version 1 (BrainVoyager 2000)

BYTES | DATA TYPE | DEFAULT | DESCRIPTION
2 | short int | 1 | version number
2 | short int | 1 | NrOfMaps (only used with value "1" in BV 2000)
2 | short int | 2 | MapType (t-, F-, correlation, crosscorrelation etc.) (*1)
2 | short int | 0 | NrOfLags, only used if MapType = crosscorrelation
Begin of loop over 'NrOfMaps' describing infos for each map
2 | short int |  | ClusterSize for 3D map 1
4 | float |  | Statistical threshold for 3D map 1, critical value
4 | float |  | Statistical threshold for 3D map 1, max value
2 | short int | 0 | df1, degrees of freedom for 3D map 1 (*2)
2 | short int | 0 | df2, degrees of freedom for 3D map 1 (*2)
N_1 | byte |  | Name for 3D map 1
: | : |  | :
2 | short int |  | ClusterSize for 3D map 'NrOfMaps'
4 | float |  | Statistical threshold for 3D map 'NrOfMaps', critical value
4 | float |  | Statistical threshold for 3D map 'NrOfMaps', max value
2 | short int | 0 | df1, degrees of freedom for 3D map 'NrOfMaps' (*2)
2 | short int | 0 | df1, degrees of freedom for 3D map 'NrOfMaps' (*2)
N_NrOfMaps | byte |  | Name for 3D map 'NrOfMaps'
End of loop over 'NrOfMaps'
2 | short int | 256, FIX | DimX of VMR from which 3D map was saved
2 | short int | 256, FIX | DimY of VMR from which 3D map was saved
2 | short int | 256 | Dim Z of VMR from which 3D map was saved
2 | short int |  | XStart (*3)
2 | short int |  | XEnd (*3)
2 | short int |  | YStart (*3)
2 | short int |  | YEnd (*3)
2 | short int |  | ZStart (*3)
2 | short int |  | ZEnd (*3)
2 | short int | 1 | resolution (*4)

(*1) A VMP file may contain any statistic. For proper default settings after reading a VMP file some values for MapType are reserved, i.e., 1 -> t- or F-values, 2 -> correlation values, 3 -> cross-correlation values.

(*2) These values are currently not used in BrainVoyager. They will be used in future versions to compute p-values based on the statistical values stored in the map (see *1)

(*3) These values indicate the relative position within a 2563 VMR volume (see explanations below).

(*4) The resolution is defined with respect to the resolution of a VMR file. Typically, one VMR voxel has the resolution of 1 (Talairach) mm3. VMP files normally also have a resolution of 1. Other resolutions, i.e. 2 and 3 are possible but are not fully tested and are therefore not recommended. If a statistic has been computed from a VTC with a lower resolution (i.e. 3), the resulting map is currently interpolated to the standard resolution of a VMP of 1 voxel automatically.

VMP data

A VMP file contains DimN = NrOfMaps 3D data sets. Each data set contains a 3D representation of a statistical entity. Each data element (statistical value) is represented in 4 bytes (float). The data is organized in four loops:

DimN

DimZ

DimY

DimX

The spatial dimensions can be computed from the header info as follows (the value of resolution should be "1" at present):

DimX = (XEnd - XStart + 1) / resolution
DimY = (YEnd - YStart + 1) / resolution
DimZ = (ZEnd - ZStart + 1) / resolution

Note that the axes terminology follows the internal BrainVoyager (BV) format. The mapping to Talairach axes is as follows:

BV X front -> back = Y in Tal space
BV Y top -> bottom = Z in Tal space
BV Z left -> right = X in Tal space


The format of SRF files

SRF files contain a description of surface mesh files. The binary files consist of three main sections: the description of the vertices and vertex normals, the description of triangles build from the vertices and the description of the nearest neighbors for each vertex.

BYTES | DATA TYPE | DEFAULT | DESCRIPTION
4 | float | 3 | version number
4 | int | 0 | reserved, must be '0'
4 | int |  | NrOfVertices (number of vertices)
4 | int |  | NrOfTriangles (number of triangles)
4 | float | 128.0 | MeshCenterX
4 | float | 128.0 | MeshCenterY
4 | float | 128.0 | MeshCenterZ
NrOfVertices*4 | float |  | VertexX, sequence of X coordinates of all vertices
NrOfVertices*4 | float |  | VertexY, sequence of Y coordinates of all vertices
NrOfVertices*4 | float |  | VertexZ, sequence of Z coordinates of all vertices
NrOfVertices*4 | float |  | NormalX, sequence of X components of all vertex normals
NrOfVertices*4 | float |  | NormalY, sequence of Y components of all vertex normals
NrOfVertices*4 | float |  | NormalZ, sequence of Z components of all vertex normals
4 | float | 0.322 | R component of convex curvature color (range: 0.0 - 1-0)
4 | float | 0.733 | G component of convex curvature color (range: 0.0 - 1-0)
4 | float | 0.980 | B component of convex curvature color (range: 0.0 - 1-0)
4 | float | 0.500 | Alpha component of convex curvature color (range: 0.0 - 1-0)
4 | float | 0.100 | R component of concave curvature color (range: 0.0 - 1-0)
4 | float | 0.240 | G component of concave curvature color (range: 0.0 - 1-0)
4 | float | 0.320 | B component of concave curvature color (range: 0.0 - 1-0)
4 | float | 0.500 | Alpha component of concave curvature color (range: 0.0 - 1-0)
NrOfVertices*4 | int |  | MeshColor, sequence of color indices of all vertices (*1)
4 | int |  | N, number of nearest neighbors of vertex 1
4 | int |  | Nearest neighbor 1 of vertex 1
: | : |  | :
4 | int |  | Nearest neighbor N of vertex 1
:: | :: |  | ::
4 | int |  | N, number of nearest neighbors of vertex 'NrOfVertices'
4 | int |  | Nearest neighbor 1 of vertex 'NrOfVertices'
: | : |  | :
4 | int |  | Nearest neighbor N of vertex 'NrOfVertices'
NrOfTriangels*3*4 | int |  | Sequence of three indices to constituting vertices of each triangle
4 | int |  | NrOfTriangleStripElements
NrOfStripElements*4 | int |  | Sequence of strip elements (if NrOfStripElements > 0)

(*1) Each vertex has one color index. An index value of 0 references the convex curvature color, a value of 1 references the concave curvature color. Functional colors, RGB colors can be also represented.


The format of SMP files

A surface map file or SMP file contains statistical results in a surface-based format: For each vertex, one or more float values are stored representing statistical entities like correlation or F values. Statistical tests performed/loaded within a VMR project are internally stored in VMP format. These can be converted into a SMP by using the "Create SMP" function. This function "samples" the VMP at the positions of the vertices and attaches the sampled values to the respective vertices. The new multi-map feature allows to superimpose an unrestricted number of SMPs. Each SMP can have its own color range (EnableSMPColor = 1) which is interpolated between the R, G, B values of the color for the map threshold (critical value) and the specified maximum statistical value. As an alternative (EnableSMPColor = 0), an SMP can also use the current overlay LUT. SMP colors can be rendered also transparently. As default they are rendered non-transparent (TransparentColorFactor = 1.0). If an SMP map shall be rendered transparently, set the TransparentColorFactor value between 0.0 and 1.0. the value 0.0 has a special meaning rendering a SMP map transparent with respect to the significance value at a vertex: If a statistical value at a vertex just reaches the critical threshold, it is rendered completely transparent (not visible), if the statistical value reaches or exceeds the maximum threshold, the vertex is rendered opaque; the transparency for statistical values between these two values is determined by linear interpolation.
The binary SMP file contains a variable-length header followed by the statistical data represented with 4 byte float values.

SMP header

BYTES | DATA TYPE | DEFAULT | DESCRIPTION
2 | short int | 2 | version number
4 | int |  | NrOfVertices (number of vertices)
2 | short int | 1 | NrOfMaps
2 | short int | 2 | MapType (t-, F-, correlation, crosscorrelation etc.) (*1)
2 | short int | 0 | NrOfLags, only used if MapType = crosscorrelation
N | byte |  | Name of SRF file originally used to create this SMP
Begin of loop over 'NrOfMaps' describing infos for each map
4 | int |  | ClusterSize for surface map 1
1 | byte | 1 | EnableClusterCheck for surface map 1 (*3)
4 | float |  | Statistical threshold for surface map 1, critical value
4 | float |  | Statistical color-only threshold for surface map 1, max value
4 | int | 0 | df1, degrees of freedom for surface map 1 (*2)
4 | int | 0 | df2, degrees of freedom for for surface map 1 (*2)
4 | int | 0 | Cortex-based Bonferroni correction value (*2)
3 | byte |  | R, G and B component of color for critical value (*3)
3 | byte |  | R, G and B component of color for max color-only threshold (*3)
1 | byte | 1 | EnableSMPColor for surface map 1 (*3)
4 | float | 1.0 | TransparentColorFactor for surface map 1 (*3)
N_1 | byte | <SMP> | Name of surface map 1
: | : |  | :
4 | int |  | ClusterSize for surface map 'NrOfMaps'
1 | byte | 1 | EnableClusterCheck for surface map 'NrOfMaps' (*3)
4 | float |  | Statistical threshold for surface map 'NrOfMaps', critical value
4 | float |  | Statistical color-only threshold for map 'NrOfMaps', max value
4 | int | 0 | df1, degrees of freedom for 3D map 'NrOfMaps' (*2)
4 | int | 0 | df1, degrees of freedom for 3D map 'NrOfMaps' (*2)
4 | int | 0 | Cortex-based Bonferroni correction value (*2)
3 | byte |  | R, G and B component of color for critical value (*3)
3 | byte |  | R, G and B component of color for max color-only threshold (*3)
1 | byte | 1 | EnableSMPColor for surface map 'NrOfMaps' (*3)
4 | float | 1.0 | TransparentColorFactor for surface map 'NrOfMaps' (*3)
N_NrOfMaps | byte | <SMP> | Name of surface map 'NrOfMaps'
End of loop over 'NrOfMaps'

(*1) A SMP file may contain any statistic. For proper default settings, some values for MapType are reserved, i.e., 1 -> t- or F-values, 2 -> correlation values, 3 -> cross-correlation values.

(*2) These values are currently not used in BrainVoyager. They will be used in future versions to compute p-values based on the statistical values stored in the map (see *1). The cortex-based Bonferroni correction value is used to correct single-voxel p-values with respect to the number of functional data points (in a linked VTC) located around the cortical surface. The value is saved for each surface map but should be the same for all maps.

(*3) New entry introduced in file version 2.

SMP data

A SMP file contains NrOfMaps data sets. Each data set contains NrOfVertices 4 byte (float) values representing a statistical entity. The data is thus organized in two loops, the outer loop runs across the NrOfMaps and the inner loop across NrOfVertices.