Brain Innovation

support portal

Navigation

BrainVoyager Automation & Development File Formats Users Guide (2.3) - The Format Of NR-VMP Files

Users Guide (2.3) - The Format Of NR-VMP Files

A native resolution volume map (NR-VMP) file contains statistical results in 3D format. It is the default format for volume maps. It is called "native-resolution" VMP because one or more 3D maps are stored in the resolution of the original data from which they are derived. For functional maps, the "native" resolution corresponds to the resolution of VTC voxels (typically 3x3x3 mm voxels). In contrast, anatomical resolution volume maps (AR-VMPs) store maps in the resolution of "hosting" VMR files (typically 1x1x1 mm voxels) and are usually internally created by interpolation. NR-VMPs are also used to store other data, e.g. component maps resulting from Independent Component Analysis (ICA), or directed influence maps resulting from Granger Causality Mapping (GCM). The plugin system of BrainVoyager allows to "register" custom file extensions for NR-VMPs; therefore .ICA files or .GCM files are also native resolution .VMP files.

A NR-VMP data structure can hold any number of individual 3D sub-maps (volumes). The number of sub-maps is stored in the "NrOfMaps" entry. For each sub-map, a time course can be optionally stored, each having "NrOfTimePoints" values. In addition, any number of extra parameters ("NrOfComponentParams") can be stored containing one value per component. For further details, see the description of NR-VMP data structures and access functions in the "Plugins" chapter of the "User's Guide".

The binary component file contains a variable-length header followed by the data containing 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 3 pairs of start/end values. The current version of NR-VMP files is 6. Older version are also described below.

NR-VMP Header (Version 6)

 

BYTES DATA TYPE DEFAULT DESCRIPTION
4 int 0xA1B2C3D4 "magic number" to identify NR-VMP files
2 short int 6 VersionNumber (four entries added from version 3 to version 4)
2 short int 1 DocumentType (only value "1" allowed at present)
4 int 1 NrOfSubMaps (number of sub-maps/component maps)
4 int 0 NrOfTimePoints ("0" if no associated component time courses)
4 int 0 NrOfComponentParams ("0" if no associated component parameters)
4 int 0 ShowParamsRangeFrom (params shown in special ICA dlg)
4 int 0 ShowParamsRangeTo
4 int 0 UseForFingerprintParamsRangeFrom (relevant only for ICA)
4 int 0 UseForFingerprintParamsRangeTo (relevant only for ICA)
4 int 57 XStart (subvolume specification)
4 int 231 XEnd (subvolume specification)
4 int 52 YStart (subvolume specification)
4 int 172 YEnd (subvolume specification)
4 int 59 ZStart (subvolume specification)
4 int 197 ZEnd (subvolume specification)
4 int 3 Resolution (typically same as source (e.g. VTC) resolution
4 int 256 DimX (expected size of hosting VMR)
4 int 256 DimY (expected size of hosting VMR)
4 int 256 DimZ (expected size of hosting VMR)
N_VTC byte 0 NameOfVTCFile from which CMP data has been derived
N_PRT byte 0 NameOfProtocolFile (used for time course display)
N_VOI byte 0 NameOfVOIFile (optional, not used at present)
Begin of "m" loop over "NrOfSubMaps" maps
4 int 1 TypeOfMap of sub-map "m" (all sub-maps must have same type at present)
4 float 2.0 MapThreshold for sub-map "m"
4 float 10.0 UpperThreshold (only used to determine color range)
N_Name byte 0 MapName (name of sub-map "m")
3 byte   R, G and B part of color for positive values above threshold (positive min value)
3 byte   R, G and B part of color for values at and above upper threshold (positive max value)
3 byte   R, G and B part of color for negative values above threshold (negative min value)
3 byte   R, G and B part of color for values at and above upper threshold (negative max value)
1 byte 0 UseVMPColor: Use sub-map specific color range ("1") or look-up table ("0")
N_Name byte <default> LUTFileName - Name of color look-up table to be used for this sub-map
4 float 1.0 TransparentColorFactor: Blend map colors with anatomical background
4 int   NrOfLags - only stored if "TypeOf Map" = 3
4 int   DisplayMinLag - only stored if "TypeOf Map" = 3
4 int   DisplayMaxLag - only stored if "TypeOf Map" = 3
4 int   ShowCorrelationOrLag - only stored if "TypeOf Map" = 3
4 int   ClusterSizeThreshold for sub-map "m"
1 byte   EnableClusterSizeThreshold for sub-map "m"
4 int 1 ShowValuesAboveUpperThreshold
4 int 0 DF1 (degrees-of-freedom)
4 int 0 DF2 (degrees-of-freedom)
1 byte 3 ShowPosNegValues flag (1 -> pos, 2 -> neg, 3 -> both)
4 int 0 NrOfUsedVoxels (e.g. no. masked voxels for p correction methods)
4 int 0 SizeOfFDRTable
3*SizeOfFDRTable float 0 FDRTableInfo (each entry: q, crit std, crit conservative)
4 int 0 UseFDRTableIndex (stores q selected for thresholding)
End of "m" loop over "NrOfSubMaps"
If (NrOfTimePoints > 0):Begin of "c" loop over "NrOfSubMaps"
NrOfTimePoints float   Time course values associated with component "c"
End of "c" loop over "NrOfComponents"
If (NrOfComponentParams > 0):Begin of "p" loop over "NrOfComponentParams"
N_Name byte 0 Name of parameter "p"
NrOfComponents float 0.0 Values of parameter "p" for each CMP
End of "p" loop over "NrOfComponentParams"

NR-VMP Header (Version 4)

BYTES DATA TYPE DEFAULT DESCRIPTION
2 short int 4 version number (four entries added from version 3 to version 4)
2 short int 1 Document type (only value "1" allowed at present)
4 int 1 NrOfComponents (number of component maps)
4 int 0 NrOfTimePoints ("0" if no associated component time courses)
4 int 0 NrOfComponentParams ("0" if no associated component parameters)
4 int 0 ShowParamsRangeFrom (limit params shown in dlg, new in version 4)
4 int NrOfComponentParams ShowParamsRangeTo (new in version 4)
4 int 0 UseForFingerprintParamsRangeFrom (new in version 4, relevant only for ICA)
4 int 0 UseForFingerprintParamsRangeTo (new in version 4, relevant only for ICA)
4 int 57 XStart (subvolume specification)
4 int 231 XEnd (subvolume specification)
4 int 52 YStart (subvolume specification)
4 int 172 YEnd (subvolume specification)
4 int 59 ZStart (subvolume specification)
4 int 197 ZEnd (subvolume specification)
4 int 3 Resolution (typically same as VTC resolution)
4 int 256 DimX (expected size of hosting VMR)
4 int 256 DimY (expected size of hosting VMR)
4 int 256 DimZ (expected size of hosting VMR)
N_VTC byte 0 Name of VTC file from which CMP data has been derived
N_PRT byte 0 Name of a stimulation protocol file (used for time course display)
N_VOI byte 0 Name of a VOI file (optional, not used at present)
Begin of "c" loop over "NrOfComponents" maps
4 int 1 Type of Map of component "c" (all CMPs must have same type at present)
4 float 2.0 Map threshold for component "c"
4 float 10.0 Upper threshold (only used to determine color range)
N_Name byte 0 Name of component "c"
3 byte   R, G and B part of color for positive values above threshold (positive min value)
3 byte   R, G and B part of color for values at and above upper threshold (positive max value)
3 byte   R, G and B part of color for negative values above threshold (negative min value)
3 byte   R, G and B part of color for values at and above upper threshold (negative max value)
1 byte 0 UseCMPColor: Use component-specific color ("1") or generic look-up table ("0")
4 float 1.0 TransparentColorFactor: Blend map colors with anatomical background
End of "c" loop over "NrOfComponents"
If (NrOfTimePoints > 0):Begin of "c" loop over "NrOfComponents"
NrOfTimePoints float   Time course values associated with component "c"
End of "c" loop over "NrOfComponents"
If (NrOfComponentParams > 0):Begin of "p" loop over "NrOfComponentParams"
N_Name byte 0 Name of parameter "p"
NrOfComponents float 0.0 Values of parameter "p" for each CMP
End of "p" loop over "NrOfComponentParams"

Notes

A NR-VMP file may contain any type of value, i.e. from hypothesis- or data-driven data analyses. For proper default settings for visualizing CMP data structures, some values for "Type of Map" 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 CMP 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. NR-VMP files normally have the same resolution of the data from which they are derived (e.g. VTC files) in most cases. If, for example, a VTC file has resolution "3", one voxel in a VTC or NR-VMP data encompasses 3 x 3 x 3 = 27 VMR voxels.

NR-VMP data

A NR-VMP file contains DimN = NrOfSubMaps 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 (NrOfComponents)

DimZ

DimY

DimX

The spatial dimensions can be computed from the header info as follows:

DimX = (XEnd - XStart) / Resolution
DimY = (YEnd - YStart) / Resolution
DimZ = (ZEnd - ZStart) / 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

You are here: HomeBrainVoyagerAutomation & DevelopmentFile Formats ≫ Users Guide (2.3) - The Format Of NR-VMP Files