====== GLM::RFX_rMap - simple regressions on the second level ======

===== Motivation =====
In the field of neuroscience, it is often not only of interest which areas in the brain (co- or differentially) activate for a given (set of) task(s), but also whether or not the neural correlate might be meaningful w.r.t. observed differences between subjects.

For instance, if in a mathematical task (adding three two-digit numbers, for instance) strong differences between the performance of subjects is observed (measured by reaction time and error rate), it could be of interest to see if more successful subjects show relatively stronger activation (e.g. measured as per cent signal change of the BOLD response) in regions that seem to be relevant for the task.

There are different ways to approach this kind of question, one of which is employing simple regressions, using the behavioral measure as predictor (independent variable), and the brain as dependent variable.

===== Requirements =====
This function is currently implemented for BrainVoyager QX's GLM format only. And the behavioral variable (data vector) must be available in the current workspace.

===== Reference / glm.Help('RFX_rMap') =====
<file> GLM::RFX_rMap  - calculate a second-level r contrast map
 
 FORMAT:       map = glm.RFX_rMap(c, r [, mapopts])
 
 Input fields:
 
       c           NxC contrast vector
       r           Rx1 or RxN regression data (or VOI object)
       mapopts     structure with optional fields
        .const     also create (t-) map of constant term
        .meanr     boolean flag, remove mean from map (added as cov)
        .meanrmsk  mask to get mean from (object or XxYxZ logical)
        .names     1xN cell array with map names
        .rank      flag, rank-transform data before regression
        .robust    flag, use robust regression in addition to OLS
        .subsel    subject selection (otherwise all subjects)
        .thresh    1x2 threshold (lower, upper), as p-values!
        .voiidx    index into VOI list (only used if r is a VOI object)
 
 Output fields:
 
       map         MAP/VMP/SMP object with maps</file>

===== Usage examples =====
When the behavioral variable is available as **''behav''** and the GLM (in our example voxel-based) is accessible as object variable **''glm''**, these are some syntax examples:

  * computing a simple regression with all subjects for the contrast ''[1, -1, 0]'':<code matlab>vmp = glm.RFX_rMap([1, -1, 0], behav, ...
    struct('names', {{'Correlation: task difference ./. behavior'}}));</code>
  * computing a rank-transformed correlation and auto-naming:<code matlab>vmp = glm.RFX_rMap([1, -1, 0], behav, ...
    struct('rank', true));</code>
  * computing a robust regression and also computing a t-contrast for the main effect after taking the variance explained by the behavior into account:<code matlab>vmp = glm.RFX_rMap([1, -1, 0], behav, ...
    struct('const', true, 'robust', true));</code>

The resulting map (in this case VMP) can easily be stored via the [[obj.Save|Save]] or [[obj.SaveAs|SaveAs]] methods.