Users Guide (2.3) - The Format Of NR-VMP Files
- Details
- Category: File Formats
- Last Updated: 17 April 2018
- Published: 17 April 2018
- Hits: 4825
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