====== vmp.ComputeFormula ======

===== Motivation =====
It is often helpful to combine the maps from a VMP in various ways (e.g. to create a conjunction map). This method allows various combination options.

===== Method reference ('vmp.Help('ComputeFormula')') =====
<file> VMP::ComputeFormula  - add a conjunction map to a VMP
 
 FORMAT:       [vmp] = vmp.ComputeFormula(formula [, opts])
 
 Input fields:
 
       formula     string giving a formula, supporting the following
                   #i -> .Map(i).VMPData
                   $i -> .Map(opts.mapsel(i)).VMPData
                   whereas i can be a single number, or a valid range
                   using the i1:i2 or i1:s:i2 format
       opts        optional settings
       .mapsel     sub-selection of maps (for enhanced indexing)
       .name       set target map name to name
       .pvalues    flag, if true, convert maps to pvalues
       .source     map used as template, default first map encountered
       .target     specify a target map index (otherwise added at end)
                   - additionally all other Map. subfields are accepted
 
 Output fields:
 
       vmp         VMP with added/replaced map</file>

===== Formula =====
The formula argument has be passed as a single string which is parsed for occurrences of ''#'' and ''$'' characters followed by either a single number (e.g. ''#4''), plain vectors (e.g. ''$5:8''), or non-1-step vectors (''#1:12:120''). These patterns are expanded to ''obj.Map(NUMBER).VMPData'' for single numbers and ''cat(4, obj.Map(VECTOR).VMPData)'' for vectors. **This means that for any multi-map functions, the 4th dimension must be used!**

===== Options =====
The most important and possibly non-intuitive option is the ''.pvalues'' option. If set to ''true'', the values (VMPData) will be passed to the according distribution function (e.g. ''sdist('tinv', VMPData, DF1)'') prior to going into the formula. This is useful to compute conjunctions (and transparently supported by the [[NeuroElf GUI|main UI]]'s ''compute formula'' button for VMPs).

===== Usage examples =====
  * compute the conjunction map of the first two maps in a VMP file: <code matlab vmp_computeformula_conjunction.m>% load VMP
vmp = xff('*.vmp');

% compute conjunction map of first two maps, default options
vmp.ComputeFormula('conjvalp(#1, #2)', struct('pvalues', true));

% save VMP
vmp.Save;</code>
  * compute the average map of all maps selected by a pattern: <code matlab vmp_computeformula_average.m>% find maps that match a criterion
matched = find(~isemptycell(regexpi(vmp.MapNames, 'reappraise')));
nummatched = numel(matched);

% compute mean and store as new map
vmp.ComputeFormula(sprintf( ...
    'mean($1:%d, 4)', nummatched), struct('mapsel', matched));</code>
  * compute an ordinary-least-squares one-sample t-test on a list of 12 selected maps from [[neuroelf_gui|the GUI]]: use formula ''sqrt(12) .* mean($1:$12, 4) ./ std($1:$12, [], 4)''
  * compute a robust two-sample t-test depending on a string in a map: <code matlab vmp_computeformula_robusttst.m>% find indices of two groups
group1 = find(~isemptycell(regexpi(vmp.MapNames, 'group1')));
group2 = find(~isemptycell(regexpi(vmp.MapNames, 'group2')));
groups = [group1(:); group2(:)];
ngroup1 = numel(group1);
ngroup2 = numel(group2);
ngroups = ngroup1 + ngroup2;

% create formula
formula = sprintf( ...
    'robustnsamplet_img($1:%d, [zeros(%d, 1); ones(%d, 1)])', ...
    ngroups, ngroup1, ngroup2);

% options
cfopts = struct( ...
    'mapsel', groups, ...
    'name',   'robust two-sample t-test: group1 > group2', ...
    'DF1',    ngroups - 2);

% compute
vmp.ComputeFormula(formula, cfopts);</code>