##################################################
Plotting Subject Motion During Active fMRI Session 
##################################################

Using "plotmotion" or "plotmotion_me" to Generate Motion Statistics
===================================================================

During an active scan session, it is crucial to the success of the study to ensure that your subject remains still during image acquisition.

Adequate padding, instruction, and reminders can help keep your participant from moving, but these methods are not always effective.

Using the in-line real-time viewer (on the scanner GUI) can be very effective when reviewing the acquired data for gross head movement, but is not very effective at assisting with careful examination of smaller head movements over the length of your scan.

A new script is running on cfmridcm.ucsd.edu (in the 3TE control room) that allows you to review subject motion within minutes of the run completion.

To initiate "plotmotion", open a terminal on cfmridcm (the Mac workstation in the MRI control room):

.. code-block:: csh

   plotmotion # Used for standard fmri

   or...

   plotmotion_me # Used for multi-echo fmri

You will be prompted to select the your session from a short list of the most recent scan sessions

.. code-block:: csh

   20220714__birn_thurs_20220714_adj_67p9_AUTO__30000022071216485430200000025.tar
   20220714__jacobson_proto1__30000022071216485430200000028
   20220715__birn_20220715_68p2_adj_AUTO__30000022071515355597400000010
   20220715__experiment_phantom_test__30000022071515355597400000001
   20220715__JB_7165_Y0__30000022071515355597400000004
   20220715__JB_7166_Y0__30000022071515355597400000007
   20220715__12-0014__30000022071515355597400000019
   20220718__birn_adj_64p4_20220718_AUTO__30000022071515355597400000025
   20220718__FTP_101_FTP_101__30000022071515355597400000022
   20220718__MZH_01_02_MZH_01_02__30000022071515355597400000031
   20220718__subcf0_mri__30000022071515355597400000034
   20220718__sub050_mri__30000022071515355597400000028
   20220719__birn_tues_20220719_adj_65p9_AUTO__30000022071515355597400000037

   Which session contains the data you want to assess? (copy+paste)

In this example, we will use the session: 

  * 20220719__birn_tues_20220719_adj_65p9_AUTO__30000022071515355597400000037

Next you will be prompted to select the fMRI run you would like to assess

.. code-block:: csh

    Which fMRI scan do you want to assess? (copy+paste) 

    0001_localizer_32ch
    0002_T1_struc
    0003_fMRI_AP_revPE_rpt1
    0004_fMRI_AP_revPE_rpt2
    0005_FBIRN_QA_fMRI_flip77_rpt1
    0005_FBIRN_QA_fMRI_flip77_rpt2
    0099_PhoenixZIPReport

In this example, I will use the scan:

  * 0003_fMRI_AP_revPE_rpt1

The "plotmotion" script will run for ~1 minute

Upon completion, you will be presented with a motion plot containing A-P, R-L, & I-S translation/shifts (in mm), as well as Pitch, Yaw, & Roll rotation (in degrees) over the length of your fMRI acquisition

.. image:: images/plotmotion_images/motion_plot.png
  :width: 800

The user is also shown a figure containing the euclidean norm motion plot, combining rotations with shifts - sometimes used to determine time-points with motion above a specified threshold for censoring purposes

.. image:: images/plotmotion_images/enorm_motion.png
  :width: 800

Finally, a report of the number of time-points that may require censoring, as well as the percentage of potentially problematic data is presented

.. image:: images/plotmotion_images/censor_info.png
  :width: 800

While you may not have time to re-run a problematic scan, or your study design does not allow it, awareness of motion issues within the first few minutes of your scan session will allow the study team to address any potential subject comfort issues, or re-explain the importance of remaining still (the entire body, not just the head), hopefully resulting in much cleaner runs for the remainder of the scan session