Home > BrainVoyager > Automation & Development > File Formats

File Formats

The Format of STC Files
A STC file (STC = "slice time course") contains the functional data (time series... more
The Format of VMP Files

 

A VMP file contains statistical results in 3D format. Results of statistical tests computed with a VMR-VTC project are internally stored in a VMP (and CMP) data structure. You may save/load a VMP file using the GUI or scripting commands. A single VMP file may contain an array of individual 3D data sets. VMP maps are stored in the resolution of VMR files (typically 1x1x1 mm voxels) whereas CMPs are stored in the resolution of VTC files (typically 3x3x3 mm voxels).

The binary VMP 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 data is stored. The subvolume is specified with three pairs of start/end values. The current version of VMP files is 3. Older versions are also described below.
 

VMP Header 

BYTESDATA TYPEDEFAULTDESCRIPTION
2short int3VersionNumber
4int1NrOfMaps (number of 3D maps)
<--- Begin of "m" loop over "NrOfMaps" maps --->
4int1TypeOfMap of sub-map "m" (all sub-maps should have same type at present)
4int NrOfLags - only stored if "TypeOf Map" = 3
4int DisplayMinLag - only stored if "TypeOf Map" = 3
4int DisplayMaxLag - only stored if "TypeOf Map" = 3
4int ShowCorrelationOrLag - only stored if "TypeOf Map" = 3
4int ClusterSizeThreshold for sub-map "m"
1byte EnableClusterSizeThreshold for sub-map "m"
4float Threshold for sub-map "m"
4float UpperThreshold (only used to determine color range)
4int1ShowValuesAboveUpperThreshold
4int0DF1 (degrees-of-freedom)
4int0DF2 (degrees-of-freedom)
4int0NrOfMaskVoxels (for p correction methods)
3byte

 

R, G and B part of color for positive values above threshold (positive min value)
3byte

 

R, G and B part of color for values at and above upper threshold (positive max value)
3byte

 

R, G and B part of color for negative values above threshold (negative min value)
3byte

 

R, G and B part of color for values at and above upper threshold (negative max value)
1byte0UseVMPColor - Use map-specific color ("1") or generic look-up table ("0")
4float1.0TransparentColorFactor - Blend map colors with anatomical background
N_Namebyte0MapName - Name of sub-map "m"
<--- End of "m" loop over "NrOfMaps" --->
4int256DimX of VMR from which VMP was saved
4int256DimY of VMR from which VMP was saved
4int256DimZ of VMR from which VMP was saved
4int57XStart (subvolume specification)
4int231XEnd (subvolume specification)
4int52YStart (subvolume specification)
4int172YEnd (subvolume specification)
4int59ZStart (subvolume specification)
4int197ZEnd (subvolume specification)
4int1Resolution (should be "1" at present)


Notes

A VMP file may contain any type of value, e.g. from both hypothesis- and data-driven analyses. For proper default settings for visualizaing VMP data structures, some values for "TypeOfMap" are reserved, i.e., 1 -> t-values, 2 -> correlation values, 3 -> cross-correlation values, 4 -> F-values, 11 -> percent signal change values, 12 -> ICA z values.

The "X/Y/Z Start/End" values indicate the relative position of the VMP subvolume within a 2563 VMR volume (see explanations below).

The "Resolution" value 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 interpolated to the standard VMR resolution automatically. If you want to store data in VTC resolution, you may want to use CMP files.


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 (single value) is represented in float format (4 bytes per value). The data is organized in four loops:

DimN (NrOfMaps)

DimZ

DimY

DimX

The spatial dimensions can be computed from the header info as follows (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 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 VDW Files
 The following table describes VDW file format 2 and also version 1 by indicating the entries which have been changed.

 

VDW Header
 
BYTESDATA TYPEDEFAULTDESCRIPTION
2                        short int                                  2                                  version number                                                     
Sbyte name of DMR file whose DWI data has been transformed (*1)
2short int1number of protocols (NP) attached to VDW    (new v2)
NP x Mibyte<none>NP names, each specifying a linked protocol (PRT) file (*1)
2short int0index specifying the "current" protocol    (new v2)
2short int NrOfVolumes (number of volumes, measurements, time points)                       
2short int3resolution relative to VMR, e.g. "3" - 1 voxel = 3 x 3 x 3 VMR voxels (*2)
2short int57XStart (*3)
2short int231XEnd  (*3)
2short int52YStart (*3)
2short int172YEnd  (*3)
2short int59ZStart (*3)
2short int197ZEnd  (*3)
1byte  left-right convention flag (*4)    (new v2)
1byte  reference space flag (*5)   (new v2)
4float TR [ms]
4int TE [ms]
1byte  GradientDirectionsVerified, boolean entry, values "1" or "0"
1byte GradientXDirInterpretation, values "1" - "6" (*6)
1byte GradientYDirInterpretation, values "1" - "6" (*6)
1byte GradientZDirInterpretation,values "1" - "6" (*6)
1byte GradientInformationAvailable
N x 4float IF table available, NrOfVolumes x 4 - gradient X/Y/Z plus B - values
1byte NrOfSpatialTransformations, used to update direction table
   IF (NrOfPastSpatialTransformations > 0) list of past spatial transformations (*7)
  
(*1) Variable length ("S" bytes), the end of the name is indicated by '0'.
(*2) The VDW resolution is defined with respect to the resolution of a VMR file. Typically, one VMR voxel has the resolution of 1 (Talairach) mm3.
A VDW 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.
(*3) These values indicate the relative position within a VMR volume (must be a 256^3 data set for Talairach VDW data, (see explanations below).
(*4) The left-right convention flag may assume one of three values: "1" specifies radiological convention ("left-is-right"), "2" specifies neurological convention ("left-is-left") and "0" indicates that the convention is unknown.
(*5) The reference space flag may have the following values: "1" indicates that the functional data is aligned to a 3D data set in "native" space
(e.g. in the position scanned), "2" indicates ACPC space, "3" indicates "Talairach" space and "0" indicates that the reference space is not known.
(*6) ...
(*7) The structure of how spatial transformations are stored is described in the topic about VMR files.
 
 
VDW data
Probably similar to 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 MDM Files

MDM files are used for the design of group analyses. References to individual time course data and design matrices are combined to cluster the data. A MDM file is a text file.

 

ENTRY

DESCRIPTION

FileVersion:

1

zTransformation

0=no 1=yes (desired for group statistics)

SeparatePredictors:

0=no 1=yes

 

 

NrOfStudies:

 

"C:\study.fmr/study.vtc" "C:\study.rtc"

Loop over number of studies; combination of *.vtc or *.fmr file with the *.rtc file

 

The Format of MAP Files

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 is crosscorrelation !)

2

short int

9999

Reserved (MUST BE THIS VALUE)

2

short int

 3

FileVersion (was 2; 3 since BrainVoyager 23)

4int DF1 (only present if the file version is 3)
4int DF2 (only present if the file version is 3)

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-values, 2 -> correlation values, 3 -> cross-correlation values, 4 -> F-values, 11 -> percent signal change values (QX 1.2 and higher). 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 MTC Files

The Format of MTC Files

A MTC file contains the functional data (time series) of one experimental run (one functional scan) in surface space, typically in cortex space. It is important to realize that the order of vertex time series in a MTC file follows the order of vertices in a corresponding mesh (SRF) file. When the mesh file links the MTC file, proper correspondence between the two files is established since the first time course is attached to the first vertex of the SRF file, the second time course in the MTC file is attached to the second vertex and so on. As with VTC data, the whole time series for a single vertex is stored contiguously, followed by the time course of the next vertex. This speeds up file access of the data. The binary MTC file contains a variable-length header followed by the actual vertices x time data.

MTC Header

BYTES

DATA TYPE

DEFAULT

DESCRIPTION

4

int

1

version number

4

int

 

number of vertices

4

int

 

number of time points

N * 1

char

 

name of source VTC file' (ends with '0')

M * 1

char

 

name of linked protocol file; if not available: '<none>; (ends with '0')

4

int

 

hemodynamic delay (*1)

4

float

 

TR - Repetition Time (*1)

4

float

 

delta parameter for hemodynamic response function (*1)

4

float

 

tau parameter for hemodynamic response function (*1)

4

int

 

segment size (intervals per stimulus block/event) (*1)

4

int

 

segment offset - first datapoint after first rest period (*1)

1

char

1

datatype of MTC data; 1 = 'float'

  
(*1) These values are not important anymore and might be dropped in future versions (they can be ignored).
 

MTC Data

The data is organized in a vertices x time matrix: all data points per vertex are saved together, so time runs as the inner loop:

DimVertices

DimT

The Format of VTC Files
The Format of VTC Files A VTC file contains the functional data (time series) o... more
The Format of VMR Files

The Format of VMR Files

VMR files contain high-resolution anatomical 3D data sets, typically containing the whole brain (head) of subjects. The intensity values are stored as a series of bytes. See the V16 format for a version storing each intensity value with two bytes (short integers). The VMR format contains a small header followed by the actual data. The current description of VMR files is "2", which contains additional header information after the actual data ("post-data header"). The information in the post-data header contains position information (if available) and stores a series of spatial transformations, which might have been performed to the original data set ("history record"). The post-header data can be probably ignored for custom routines, but is important for coregistration routines in BrainVoyager.

VMR Pre-Data Header

BYTES

DATA TYPE

DEFAULT

DESCRIPTION

2

unsigned short

2

File version

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

 

VMR Post-Data Header

The post-data header keeps scan position information from the original file headers, e.g. from DICOM files. The coordinate axes are not in terms of BrainVoyager's internal conventions but follow the DICOM standard.

BYTES

DATA TYPE

DEFAULT

DESCRIPTION

4

int

 

"PosInfosVerified" flag indicating that info could be read from original files

4

int

1

Coordinate system entry, "1" = DICOM

4

float

 

X coordinate of center of first slice

4

float

 

Y coordinate of center of first slice

4

float

 

Z coordinate of center of first slice

4

float

 

X coordinate of center of last slice

4

float

 

Y coordinate of center of last slice

4

float

 

Z coordinate of center of last slice

4

float

 

Slice row direction vector, x component

4

float

 

Slice row direction vector, y component

4

float

 

Slice row direction vector, z component

4

float

 

Slice column direction vector, x component

4

float

 

Slice column direction vector, y component

4

float

 

Slice column direction vector, z component

4

int

 

Nr of rows of slice image matrix

4

int

 

Nr of columns of slice image matrix

4

float

 

Extent of field of view (FoV) in row direction [mm]

4

float

 

Extent of field of view (FoV) in column direction [mm]

4

float

 

Slice thickness in mm

4

float

 

Gap thickness in mm

 

 

 

NrOfPastSpatialTransformationsAlways "0", not used at present

 

 

 

 

1

byte

1

radiological (1) or neurological (0) convention

 

 

 

 

 

 

 

Name of file selected when loading original data from disk

 

Old VMR file versions

The header of version 1 was defined as follows:

VMR header, version "1"

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

  
The data was saved in the same way as for version 2. There was no additional header information after the data.

The Format of GIFTI files

Introduction

The GIFTI file format was an designed by the Data Format Working Group (DFWG), an initiative by the NIH, USA. GIFTI files use the XML format to save surface meshes, functional, statistical and label files for cortical surfaces. The specification can be downloaded from NITRC: https://www.nitrc.org/frs/download.php/2871/GIFTI_Surface_Format.pdf.

Part of surface                                BrainVoyager format       GIFTI format        NIfTI intent code                       
Polygon mesh*.srf*.surf.giiNIFTI_INTENT_POINTSET
Curvature*_CURVATURE.smp*.shape.giiNIFTI_INTENT_SHAPE
Functional data (time series)*.mtc*.time.giiNIFTI_INTENT_TIME_SERIES
Statistical data*.smp*.func.giiNIFTI_FIRST_STATCODE - NIFTI_LAST_STATCODE
Region-of-interest*.poi*.label.giiNIFTI_INTENT_LABEL

GIFTI in BrainVoyager

Previously, GIFTI could be converted to BrainVoyager and reverse via a plugin. GIFTI files (*.gii) are native in BrainVoyager 23.2+. Load via the Meshes > Load GIFTI Mesh...

Latest update: 19-08-2024

The Format Of UFF Files

About user-defined files (*.uff)

Besides DICOM (*.dcm), Philips (*.PAR, *.REC) and GE (*.MR, *.I) and other file formats, it is also possible to read a file using a user defined format (*.uff) when creating a BrainVoyager project (*.vmr, *.dmr, *.fmr, *.amr). The *.uff file is a simple text file describing features of the data like header size, number of columns and rows, etc. The UFF format could for example be used for Bruker data.

How to use the UFF file in BrainVoyager

The *.uff file should be stored in the BrainVoyager directory (/Applications/BrainVoyager/); when starting a "New Project" in BrainVoyager, the names of *.uff files in the BrainVoyager directory are added to the known file formats.

 

The format of UFF files

UFF file parameter

Sample values

Description

 

 

 

FileVersion:

2

Describes file version of UFF format

NSpalten:

128

Number of columns

NZeilen:

64

Number of rows

HeaderSize:

0

Size of image header

PixelFormat:

1

Datatype, defining number of bytes per pixel

1 = 1 byte integer

2 = 2 bytes integer

3 = 4 bytes integer

4 = 4 bytes float

DICOM:

0

Boolean value defining whether the datatype conforms to the DICOM standard or not. 0 = no, 1 = yes.

SwapBytes:

0

Boolean value defining whether the data should be swapped or not. Default is 0 (little endian). Big endian data should have value 1.

Explicit VR:

0

Explicit value representation (only applicable in case of DICOM)

MultiImageFile:

1

Defines whether there are more than one images in the file. 0 = no, 1 = yes.

SubHeaderSize:

0

In case of a multi-image file, defines whether each image in the file does have a header (1) or not (0).

ImageIndex:

1

First image to be read from the multi-image volume

SingleFuncType:

 

Defines order of appearance of the dimensions in the file.  

1 = slices x time (single file)

2 = time x slices (single file)

3 = N slice files

4 = N volume files

TimeRunsFastest:

0

Defines whether all timepoints per pixel or voxel appear before the next pixel or voxel values. If yes, then 'TimeRunsFastest' should be 1, 0 otherwise.

 

The Format Of SRF Files: illustration

Document illustrating header fields of surface files (SRF): PDF

The Format Of SMP Files

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.

Latest update: 06-07-2021

SMP header

version 2-5

 

BYTES
DATA TYPE
DEFAULT
DESCRIPTION
2
short int
3
version number (max: 5)
4
int
 
NrOfVertices (number of mesh vertices)
2
short int
1
NrOfMaps (number of stacked maps within SMP file)
N
byte
 
Name of SRF file originally used to create this SMP
Begin of loop over 'NrOfMaps' describing infos for each map
4
int
 
Maptype (t-, F-, correlation, cross-correlation, etc)(*1)
4
int
 
NrOfLags (*4)
4
int
 
MinLag (*4)
4
int
 
MaxLag (*4)
4
int
 
CCOverlay (*4) (show overlay correlation or lag values)
4
int
 
ClusterSize
1
byte
1
EnableClusterCheck (*3)
4
float
 
Statistical threshold, critical value
4
float
 
Statistical threshold, max value (*5)
4int IncludeValuesGreaterThreshMax (SMP version 4 or higher)
4
int
 
DF1 (degrees of freedom, nominator if F-test) (*2)
4
int
0
DF2 (degrees of freedom, denominator for F-test) (*2)
4int PosNegFlag (SMP version 5 or higher)
4
int
0
Cortex-based Bonferroni correction value (*2)
3
byte
 
R, G and B component of color pos min (*3)
3
byte
 
R, G and B component of color pos max (*3)
3byte R, G and B component of color neg min (SMP version 4 or higher)
3byte R, G and B component of color neg max (SMP version 4 or higher)
1
byte
1
EnableSMPColor (use SMP-specific colors or general LUT)
Nbyte Name for map-specific LUT file (SMP version 5 or higher)
4
float
1.0
TransparentColorFactor for surface map (*3)
N_1
byte
 
Name of surface map
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-values, 2 -> correlation values, 3 -> cross-correlation values, 4 -> F-values,  11 -> percent signal change values (QX 1.2 and higher); see below for more codes:

BrainVoyager map type codes:
1: T-statistic
2: correlation
3: cross-correlation
4: F-statistic
5: Z-statistic
11: percent signal change
12: ICA
13: cortical thickness
14: chi^2
15: beta
16: probability
21: mean diffusivity map
22: fractional anisotropy map
25: polar angle map (in radians: -pi to pi)

(*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.

(*4) Only used when maptype is crosscorrelation

(*5) The max threshold is currently NOT used to clip statistical values. It is only used to determine the color range: All statistical values beyond the max threshold will be colored using the corresponding max color value, but they are not hidden. Statistical values falling between the min and the max threshold will get a color corresponding to the relative position in the color scale.

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.

 

The Format Of NIfTI/BIDS Files

The Format of NIfTI Files

The NIfTI file format is described on the page of the National Institutes of Health: https://nifti.nimh.nih.gov/nifti-1/

Example data and software can be downloaded from the NeuroImaging Tools & Resources Collaboratory: https://www.nitrc.org/projects/nifti

Information about the BIDS standard can be found at: https://github.com/bids-standard/

The Format of PRT Files

The Format of PRT Files

PRT files are simple text files containing the information 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" in BrainVoyager 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 Format Of SSM Files

SSM File format

The header of the sphere-to-sphere (SSM) mapping:

16 bit  File version (min 2)
32 bit  No of vertices
32 bit  No of vertices of references mesh

The data:

No of vertices x 32 bit

 

The Format of GLM Files

The table below describes the order of values stored in version 4 of GLM files. Note that a GLM file's structure partially depends on the type of data (FMR-STC, VMR-VTC, SRF-MTC data) that was originally used to calcualte the GLM, which is stored in the second entry "Type of GLM". The GLM format is also different for RFX-GLMs as compared to standard GLMs (entry 3 "RFX-GLM flag"). The data itself is stored at the end of the file and needs to use provided header information to know how many voxels are stored and how many values are stored for each voxel. Note that provided axis/bounding box names are not in DICOM convention, but in internal (BV) convention.

BYTESTYPEDESCRIPTION
2intFile version
1byteType of GLM flag (0 - FMR-STC, 1 - VMR-VTC, 2 - SRF-MTC)
1byteRFX-GLM flag (0 - std, 1 - RFX)
 
-- begin: only if RFX-GLM flag is 1 --
4intNo. of subjects ("NSubjects", see explanations after table)
4intNo. of predictors per subject ("NPredictorsPerSubject", see below)
-- end: only if RFX-GLM flag is 1 --
 
4intNo. of time points ("NTimePoints", see explanations after table)
4intNo. of all predictors ("NAllPredictors", see explanations after table)
4intNo. of confound predictors
4intNo. of studies
 
-- begin: only if more than 1 study --
4intNo. of studies with confound info - for loop below (can be 0, if not info provided)
N x 4intLoop over no. of studies (N) providing no. of confounds per study
-- end: only if more than 1 study --
 
1byteSeparate predictors flag (0 -> no, 1 -> seperate study, 2 -> sepearate subject predictors)
1byteTime course normalization flag (1 -> z transf, 2 - baseline z, 3 -> perc-change)
2intResolution (1, 2, 3… with respect to anatomical resolution)
1byteSerial correlation performed flag (0 -> no, 1 -> AR(1), 2 -> AR(2))
4floatMean serial correlation before correction
4floatMean serial correlation after correction
 
-- begin: if type of GLM flag 0 (FMR-STC GLM) --
2intDimX (no. of slice columns)
2intDimY (no. of slice rows)
2intDimZ (no. of slices)
-- end: if type of GLM flag 0 (FMR-STC GLM) --
 
-- begin: if type of GLM flag 1 (VMR-VTC GLM) --
2intBounding box: StartX
2intBounding box: EndX
2intBounding box: StartY
2intBounding box: EndY
2intBounding box: StartZ
2intBounding box: EndZ
-- end: if type of GLM flag 1 (VMR-VTC GLM) --
 
-- begin: if type of GLM flag 2 (SRF-MTC GLM) --
4intNo. of vertices
-- end: if type of GLM flag 2 (SRF-MTC GLM) --
 
1byteCortex-based mask flag (1 -> (grey matter) mask has been used)
4intNo. of voxels in mask (e.g. for adjusted Bonferroni correction)
N x 1charName of cortex-based mask file
 
++ begin: loop over no. of studies ++
4intNo. of time points (volumes) in study
N x 1charName of study data file
-- begin: only if type of GLM 2 (cg-aligned SRF-MTC GLM) --
N x 1charName of SSM file (cortex-based alignment data)
-- end: only if type of GLM 2 (cg-aligned SRF-MTC GLM) --
N x 1charName of SDM file (study design matrix file)
++ end: loop over no. of studies ++
 
-- begin: only if RFX-GLM flag is 0 --
N x MfloatDesign matrix (outer loop: N rows (time points); inner loop: M cols (predictors))
M x MfloatM rows, cols (predictors): Inverted X'X matrix (inv(transposed DM x DM))
-- end: only if RFX-GLM flag is 0 --
 
N x MfloatThe actual data (outer loop: N values (e.g. betas); inner loop: M voxels/vertices), for details, see below

The last row in the table above refers to the actual data that follows the header information. The data is stored as a series of volumes each containing a map for a specific beta (or other) value for each voxel/vertex. The number of voxels/vertices is calculated based on the provided dimensions for the type of GLM. For FMR-STC GLMs, the number of voxels is:

NVoxels = DimX (no. of slice columns) x DimY (no. of slice rows) x DimZ (no. of slices)

For VMR-VTC GLMs, the number of voxels is:

NVoxels = (EndX - StartX)/Resolution * (EndY - StartY)/Resolution *(EndZ - StartZ)/Resolution

For SRF-MTC GLMs, the number of "voxels" is the number of vertices. The number of values (and, thus, the number of volume maps) differs with respect to the type of GLM. For a RFX-GLM (RFX-GLM flag equals 1), the number of values per voxel is simply:

NValuesPerVoxel = 1 + NSubjects * NPredictorsPerSubject

In case of a standard GLM, the number depends mainly on the number of overall predictors (see "NAllPredictors" entry in the header) but differes with respect to the performed serial correlation approach (if any). In case that no serial correlation correction has been performed, the number of values per voxel is:

NValuesPerVoxel = 2 * NAllPredictors + 2

If a AR(1) approach (first-order autoregressive model) has been used to correct serial correlations, 1 additional volume is stored (NValuesPerVoxel = 2*NAllPredictors+3), and in case of a AR(2) approach (second-order autoregressive model) has been used, two additional values are stored (NValuesPerVoxel = 2*NAllPredictors + 4).

 

The first value (volume) of the data contains the multiple correlation coefficient R indicating the goodness-of-fit for the respective voxel's time course and to allow to calculate the proportion of explained (R2) and unexplained (1 - R2) variance. The second stored value per voxel contains the overall sum-of-squares term (SStotal) that can be used together with the R value to calculate the variance of the residuals (see below). Following the first two values, the estimated beta values are stored, i.e. one value for each predictor of the design matrix (NAllPredictors values). Following the beta values, another set of NAllPredictors values follows containing the sum-of-squares indicating the covariation of each predictor with the time course data (SSXiY). These values are stored to allow easy calculation of explained variance terms for restricted models (i.e. to allow application of the extra-sum-of-squares principle); these values may be probably ignored (not stored) for custom processing. The next volume contains the mean value of the (normalized) fMRI time course.

Only in case that serial correlation correction has been performed, one or two more values are stored. In case that the AR(1) model has been used (serial correlation flag equals 1, see table above), the estimated order 1 autocorrelation value (ACF(1) term) is stored for each voxel. In case that the AR(2) model has been used (serial correlation flag equals 2, see table above), the two estimated ACF terms are stored, i.e. the data contains one value more than in the case of the AR(1) model. With the proper number of values per voxel, the number of overall values to be read at the end of the file can finally calculated as:

NValues = NValuesPerVoxel * NVoxels

Calculating standard errors for beta and contrast values

The (non-RFX) GLM file stores enough values to allow calculation of standard errors for beta and contrast values for each voxel, if desired. The stored multiple correlation coefficient R together with the overall sum-of-squares term (SStotal) can be used to calculate the variance of the residuals as follows:

VARresiduals = SStotal * (1 - R2) / (NTimePoints - NAllPredictors)

Together with the stored inverted X'X matrix, this allows calculating the standard error for any beta or contrast t value using the usual equation (c is the contrast vector and b is the voxel's vector of stored beta values):

t = c'b / sqrt(VARresiduals * c'(X'X)-1c)

Note, however, that in case of performed serial correlation correction, the inverted X'X matrix needs to be recalculated for each voxel from the stored design matrix X using the voxel-specific autocorrelation function term(s); furthermore the number of time points (NTimePoints) needs to be corrected (subtraction of 1 for AR(1) model, subtraction of 2 for AR(2) model).