====== map.CreateVMP ======

===== Motivation =====
This method can be used to transfer a statistical map ([[xff - MAP format|MAP]]) from [[xff - FMR format|FMR]] space (where minimal smoothing is applied to the data) to the [[xff - VMP format|VMP format]] in normalized (ISO- / [[xff - VTC format|VTC]]) voxel space (and, potentially, from there to [[xff - SMP format|SMP format]] in surface space) in BrainVoyager QX.

===== Requirements =====
You need:

  * one (or multiple) [[xff - MAP format|MAP]] object(s) containing the statistical map(s) you wish to display on a [[xff - VMR format|VMR]] (or [[xff - SRF format|SRF]])
  * the initial alignment ([[xff - TRF format|IA.trf]]) and fine alignment (''FA.trf'') files
  * if you wish to visualize the data on either the ''ACPC.vmr'' or the ''TAL.vmr'', you also need the ''ACPC.trf'' and [[xff - TAL format|ACPC.tal]] files
  * further, if you wish to visualize this data on a surface (SRF), you also need the TAL-transformed SRF object

===== Method reference ('map.Help('CreateVMP')') =====
<file> MAP::CreateVMP  - create VMP from FMR based MAP object
 
 FORMAT:       vmp = map.CreateVMP(fmr, afs [, vmpfile, meth, res, bb, o])
 
 Input fields:
 
       fmr         FMR object matching MAP
       afs         cell array with alignment files, {ia, fa, acpc, tal}
       vmpfile     target VMP filename, if not given: unsaved
       meth        interpolation, 'nearest', {'linear'}, 'cubic'
       res         VMP resolution, default: 1
       bb          bounding box, default: small TAL box
       o           optional struct with settings
        .df        degrees of freedom, 1x1 or 1x2 DF setting
 
 Output fields:
 
       vmp         resulting VMP object</file>

===== Input fields (details) =====
==== fmr ====
The ''fmr'' input variable must be a valid [[xff - FMR format|FMR]] object, e.g. you can use the file selector of ''xff'' by using the syntax, ''fmr = xff('*.fmr');''.

This is required as the [[xff - MAP format|MAP]] object on which the method is called does **not** contain the required spatial information about resolution, etc.!

==== afs ====
This is a cell array with the required transformation ([[xff - TRF format|TRF]] and [[xff - TAL format|TAL]]) objects. For example, you could use the following lines of code to create one such array:

<code matlab map_createvmp_getafs.m>% request IA.trf
ia = xff('*IA*.trf', 'Please select IA TRF file...');
if isempty(ia) || ...
   ~isxff(ia, 'trf')
    error('No IA TRF file selected.');
end

% request FA.trf
fa = xff('*FA*.trf', 'Please select FA TRF file...');
if isempty(fa) || ...
   ~isxff(fa, 'trf')
    error('No FA TRF file selected.');
end

% request ACPC.trf
acpc = xff('*ACPC*.trf', 'Please select ACPC file... (leave blank for ISO-voxel space)');

% request TAL.trf (if ACPC is not empty)
if ~isempty(acpc)
    tal = xff('*.TAL', 'Please select TAL file...');
end

% compile afs cell array
if ~isempty(acpc)
    if ~isempty(tal)
        acpc = {acpc, tal};
    else
        acpc = {acpc};
    end
else
    acpc = {};
end
afs = {ia, fa, acpc{:}};</code>

==== vmpfile ====
Either leave blank of give desired output filename of [[xff - VMP format|VMP object]] to be created.

==== meth ====
Interpolation method to use. For maximum quality (lowest smoothing between MAP and VMP), set to '''cubic''' (or even '''lanczos3''').

==== res ====
Depending on the resolution in the ''FMR'' (and ''MAP''), as well as the purpose for display (e.g. surface space), you might want to select an appropriate resolution. Eventually, using ''1'' (the default) will only cost performance during VMP creation and some additional disk space while ensuring that any additional interpolation (from VMP to SMP) does not introduce further smoothing.

==== bb ====
Bounding box to be used. This must be given in BrainVoyager coordinate system (TAL axes order, however). For instance, the default bounding box is given as ''<nowiki>[59, 57, 52; 197, 231, 172]</nowiki>'', which means that the X axis will be covered from 59 to 197 (in ''.res'' step size), which translates to TAL coordinates 69 through -69 (BrainVoyager's X axis runs into negative TAL X axis direction!) and so forth.

==== o ====
This is only to be used if the ''MAP'' object does not contain the correct degrees of freedom (DF1/DF2) parameter. To override the settings in the ''MAP'' (e.g. the statistic therein is an F-map), use the following syntax: ''<nowiki>o = struct('df', [3, 140]);</nowiki>'' for (3, 140) being the DF.

===== Complete syntax example =====
This example assumes the ''afs'' argument has been made already (see above!):

<code matlab map_createvmp_example>% the following variables are being used and must exist
% - map: MAP object (fitting FMR!)
% - fmr: FMR object
% - afs: collection of TRF/TAL objects
% the following settings are used
% - no VMP filename (requires manual saving)
% - high quality interpolation (lanczos3)
% - 1mm resolution (best for going to SRF/SMP later)
% - large bounding box (covering ALL TAL space)
% - no df override
vmp = map.CreateVMP(fmr, afs, '', 'lanczos3', 1, [44, 44, 38; 212, 242, 194]);
vmp.SaveAs;</code>