  GLOBAL AND MOTION OUTLIERS (art.m)

  This is a tool for automatic and manual detection of outliers.

  NEW: 
  (-) "signal-task corr." shows on a new window an intensity map of the correlations between
  the global signal and the task conditions for each session.
  (-) "Show Spectrum" displays the power spectrum of the task conditions and motion parameters
  on a new window (each session has its own graph). The highpass cutoff frequency is also displayed.
  The user may choose which parameters to display by (un)checking the appropriate checkboxes.
  Note: It is far better to use a design matrix where the motion parameters are not considered as
  covariates, since the motion parameters are shown anyway.
  (-) "motion-task corr." shows on a new window an intensity map of the correlations between
  the task conditions and motion parameters for each session.
  Note: It is far better to use a design matrix where the motion parameters are not considered as
  covariates, since the motion parameters are shown anyway.
  (-) "Show Design" checkbox. When this checkbox is checked, the task conditions from 
  the design matrix are superimposed on the z-normalized graph. This might help identify
  correlations between the motion or the task and the experimental design. This design
  matrix is obtained from an SPM.mat file specified by the user. this option only works
  with SPM (not with FSL).
  (-) press the "+" button to the left of the z-normalized graph to it (the graph) in 
  a large new window
  (-) The tool window is now resizebale and editable (try moving the legend if it hides
  part of the graph)
  (-) The annoying crashes on some motion parameters file names are gone!
  (-) art is now SPM5 compatibile.
  (-) FSL motion parameter files are supported. Note that when FSL files are used, the
  rotational degrees of freedom are not roll/pitch/yaw, but the three Euler angles (even 
  though the legends and titles still show roll/pitch/yaw).

  This utility asks for image files and a text motion parameters file.
  It then displays four graphs:
  - The top graph is the global brain activation mean as a function of time.
  - The second is a z-normalized (stdv away from mean) global brain activation
    as a function of time.
  - The Third shows the linear motion parameters (X,Y,Z) in mm as a function of time
  - The fourth shows the rotational motion parameters (roll,pitch,yaw) in radians as
    a function of time.

  using default threshold values for each of the bottom three graphs we define outliers
  as points that exceed the threshold in at least one of these graphs. The thresholds
  are shown as horizontal black lines in each of the graphs.
  Points which are identified as outliers, are indicated by vertical red lines in the
  graphs that correspond to the outlying parameters. For example, the if the absolute value
  of the Y motion parameter for time t=17 is above the motion threshold, it is identified
  as an outlier and indicated by a red vertical line at t=17 in the third graph.
  The union of all outliers is indicated by vertical lines on the top graph.
  The list of outliers is also displayed in the editable text box below the graphs.
  The current values of the thresholds are displayed by the side of the corresponding
  graphs. These values may can be changed by the user either by pressing the up/down buttons,
  which increment/decrement the current value by 10%, or by specifying a new value in the
  text box.

  By checking the "Use Differences" checkbox, you can identify outliers in the temporal difference
  series, rather than the original motion parameter values. Note that there are different thresholds
  for the difference series and that you can toggle back and forth between the two modes.
  You can threshold the norms (L2 norm) of the motion parameters and of the angular motion 
  parameters (instead of each parameter individually) by checking the "Use norm" checkbox.

  In Addition, the user can manually add or remove points from the list of outliers by editing
  the list. Note that the list is only updated once the cursor points outside the text box
  (i.e. click the mouse somewhere outside the text box). Since any changes made by the user are
  overridden once the thresholds are updated, it is recommended to do any manual changes as the
  last step before saving.
  Pressing the save button lets the user choose whet er to save the motion statistics (.mat or .txt)
  the list of outliers (.mat or .txt), or save the graphs (.jpg, .eps or matlab .fig).

  Please report any bugs or new requirements to Susan Withfieled-Gabrieli swg@mit.edu or to Shay Mozes shaym@mit.edu

