## Users Guide (2.3) - The Format Of MAP Files

- Details
- Category: File Formats
- Last Updated: 17 April 2018
- Published: 17 April 2018
- Hits: 3221

A MAP file contains (statistical) values as a stack of slices resulting from analyses of FMR projects. Results from all statistical tests (e.g. correlation analysis) as well as overlayed GLM contrasts 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-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;