====== MAP (BrainVoyager QX's FMR-based map) file format ======

===== Motivation =====
The more common case of running statistics is in either 3D voxel ([[xff - VTC format|VTC]]/[[xff - VMP format|VMP]]) space, but there are still quite a few applications for running statistics with data that has been altered as little as possible (minimal preprocessing). The MAP format provides the ability to store a slice-based maps that match the FMR layout. At this point, there is no support for storing multiple statistics per FMR voxel.

===== General setup =====
Binary files are stored in little-endian byte ordering (for all platforms!) so as to allow cross-platform file exchange. Strings are stored as \0-terminated sequences of 8-bit integer values (ASCII charset, and not as either fixed-length or flag-specified-length strings).

The types in the list of fields are given as [[Matlab datatypes|Matlab type]] (not in C notation).

===== Fields =====
^ Loop / Condition  ^ Field                   ^ Field type       ^ Dimensions         ^ Comment  ^
|                   | CombinedTypeSlices      | uint16           | ''1x1''            | stores **both** the type of statistical map **and** number of slices; combination formula is ''(RESERVED_TOKEN + 1) * STATTYPE_VALUE + NR_OR_SLICES'' where ''RESERVED_TOKEN'' is set to ''9999'' (see below); supported types are: t-statistic (value 0), r-statistic (value 1), lag+r-statistic (value 2), F-statistic (value 3); see ''ReservedToken'' below  |
|                   | NrOfSlices              | uint16           | ''1x1''            | stores the number of slices separately; if set to ''0'', number of slices is determined from the ''CombinedTypeNrOfSlices'' field  |
|                   | DimY                    | uint16           | ''1x1''            | stores the number of columns (2nd dim in Matlab) in each slice's map  |
|                   | DimX                    | uint16           | ''1x1''            | stores the number of rows (1st dim in Matlab) in each slice's map  |
|                   | ClusterSize             | uint16           | ''1x1''            | if cluster thresholding enabled, value is set ''> 1''  |
|                   | LowerThreshold          | single           | ''1x1''            | lower statistics threshold, map values below are not shown  |
|                   | UpperThreshold          | single           | ''1x1''            | upper statistics threshold, map values above are shown in same color as if being ''UpperThreshold''  |
| ''STATTYPE_VALUE == 2''  | NrOfLags         | uint16           | ''1x1''            | for maps that contain combined r-statistic and lag value (description see below), this additional header parameter is read  |
|                   | ReservedToken           | uint16           | ''1x1''            | used in computation to split statistics and number of slices; **as this is given //AFTER// the ''NrOfLags'' field must be read, this value //MUST// remain set at ''9999''; otherwise BrainVoyager will not read those maps correctly!**  |
|                   | FileVersion             | uint16           | ''1x1''            | //this is an exceptional case, normally the FileVersion is the first or at least one of the very first flags in any file format of BrainVoyager QX!//  |
| ''FileVersion > 2''  | DF1                  | uint32           | ''1x1''            | degrees of freedom for t/r-statistic, first d.f. parameter of F-statistic  |
| ''FileVersion > 2''  | DF2                  | uint32           | ''1x1''            | second d.f. parameter of F-statistic; **important: while only required for F-statistic maps, this parameter is ALWAYS present** (for ''FileVersion'' of ''3'' and above!)  |
|                   | NameOfSDMFile           | string           | ''\0-terminated''  | name of design matrix file that was used (empty of non-applicable  |
^ **//Loop over ''NR_OF_SLICES''//**  |  |  |  |  |
|                   | Map(LOOP_SLICE).Number  | uint16           | ''1x1''            | number of map, 0-based (first slice has a value of ''0'')  |
|                   | Map(LOOP_SLICE).Data    | single           | ''DimX-by-DimY''   | statistics value; **important: for r-statistics, the actual r-statistical value is computed as ''sign(MAP_VALUE) .* (1 - abs(MAP_VALUE))'' (!) where an r-statistical value of ''0'' remains at ''0'' (prohibiting a value of ''1'')**, for r+lag-statistical maps, the value is comprised of ''MAP_VALUE = MAP_VALUE_R + MAP_VALUE_LAG'' so that, in reverse, the lag can be extracted as ''MAP_VALUE_LAG = floor(MAP_VALUE)'' and the internal r-value (1-r!) can be retrieved as ''MAP_VALUE_R = MAP_VALUE - MAP_VALUE_LAG''  |
^ //End of Loop over ''NR_OF_SLICES''//  |  |  |  |  |