README: Calculating Pythagorean Displacement and Derivatives

Kenny Vaden  (vaden@musc.edu)

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 

CONTENTS

1. pythag_motion.m ......... Matlab script (Feb 20, 2013)
2. README.txt  ............. file that you're reading
3. gpl.txt ................. GNU General Public License
4. rp_example.txt .......... example input motion textfile
5. pythag_rp_example.txt ... example output pythagorean vectors
6. pythag_rp_example.tiff .. example output pythagorean plot

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 

The enclosed matlab script uses the Pythagorean Theorem to 
calculate the magnitude of head movements in two parameters,
based on the 6 measurements needed to express 3D translation
and rotation in X, Y, and Z planes. 

In addition to the head moving around inside the coil and
(possibly) inducing position-related artifacts, motion also can
result in apparent BOLD/CBF. Consequently, the enclosed program
generates two first-derivative vectors that describe the magnitude
of position-change (aka MOTION).

The program generates an output plot that shows the original 
displacements and pythagorean descriptions for translation (top)
and rotation (bottom), as well as a text file that contains 4 columns:

 1: translation-displacement
 2: rotation-displacement
 3: translation-motion
 4: rotation-motion

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 

To use the script:

1) Copy the script to the directory that contains the rp*.txt file
   that was generated using spm8 (cols 1:3 = x,y,z translation; 
   cols 4:6 = x,y,z rotation).

2) Edit input filename in the pythag_motion.m code
    % INPUT FILENAME
    input_rpfile = 'rp_example.txt';

3) In Matlab change directory to directory that contains both the
   input textfile & pythag_motion.m

4) At the command line: 
   > clear all; pythag_motion

That should be it! If everything works, then 2 output files are created. 

Good luck!

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 

How to report using the use of Pythagorean motion regressors
in a manuscript:

Four additional nuisance regressors (displacement and motion in 
translation and rotation) were calculated using the Pythagorean 
Theorem from the six realignment parameters generated in SPM8 
(for examples, see Kuchinsky et al., 2012 and Wilke, 2012).

1. Kuchinsky, S.E., Vaden, K.I., Keren, N.I., Harris, K.C., 
Ahlstrom, J.B., Dubno, J.R., Eckert, M.A. (2012). Word 
intelligibility and age predict visual cortex activity 
during word listening. Cerebral Cortex, 22(6), 1360-1371. 
[PMID: 21862447]

2. Wilke, M. (2012). An alternative approach towards assessing
of and accounting for individual motion in fMRI timeseries. 
NeuroImage, 59(3), 2062–2072.

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 

Copyright:

This program (pythag_motion.m) is free software; you can 
redistribute it and/or modify it under the terms of the GNU 
General Public License as published by the Free Software 
Foundation; either version 2 of the License, or (at your 
option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.