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.

 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

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!

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 main UI's compute formula button for VMPs).

• compute the conjunction map of the first two maps in a VMP file:

  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;

• compute the average map of all maps selected by a pattern:

  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));

• compute an ordinary-least-squares one-sample t-test on a list of 12 selected maps from 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:

  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);