Censoring frames in EPI time-series

Program name: jump_censor

  • Purpose: Mark frames as "censored", i.e., to be ignored, if the motion of a point 8.7cm from the center of rotation moves by more than a given threshold.


  • -c, --cross-slice Only consider motion across slices. Neglect in-plane motion.
  • --interleave Improves temporal resolution by de-interleave odd and even numbered slices. Each frame is split into half-frames of even and odd numbered slices. Each series of half-frames is then motion-corrected. Both series are then interleaved to yield a time series with half the TR as the original EPI time series. Motion is detected on this time series and then frames are collapsed to the orginal resolution. This option improves sensitivity to quick motions that occur in less than 2 seconds.
  • -v, --verbose Verbose mode.
  • --store-plot Create plot of results and store as a png.
  • --show-plot Create plot of results, store as a png, and display to screen.
  • -k, --keep Keep intermediate files.
  • --threshold=THRESHOLD Threshold for censoring in mm/half-frame. Defaults to 2mm.
  • --prefix= Filename (without suffix) for output files.
  • --label= Label identifying the data, e.g., "gonogo_run1".


  1. Files written by default.
    • _censor.1D: A censor file compatible with AFNI.
    • _censor_stats.txt: A one line text file containing the std. dev. of the motion and the fraction of frames censored. The fraction of frames censored can be used to determine when to exclude a subject. 25% is a reasonable threshold.
  2. Optional outputs
    • For the --interleave opton, a file named _il_mtn.txt is written. This file contains the interleaved motion parameters in the same format as files created withe -dfile option in AFNI's 3dvolreg program.
    • For the --show-plot or --store-plot option, the plot is written to disk in a png file named _censor.png where is the file specified by either <<>input_file<>> with the suffix stripped away or by the --prefix option.

Example of the output

Graphs of censor results

The plot at the top shows the distance moved in mm at each frame. The plot at bottom shows the censor mask, where frames with a value of zero are omitted from the analysis.

Example bash script


SUBNUMS=`cat subjects_to_use.txt`
RUNS="1 2"

# Jumps in position (at coordinate (5,5,5)cm from center of rotation) that 
# exceed the censor threshold will be censored.

# The --interleave splits each frame into even and odd frames, processes the
# resulting time-series, then collapses the results down to the orginal resolution.
# This option improves sensitivity to quick motions that occur in less than 2 seconds.

if [ -e ${STATS_FILE} ] then
    date >> ${STATS_FILE}
    date > ${STATS_FILE}

for subnum in ${SUBNUMS} do
#    echo Processing subject_${subnum}
    for run in ${RUNS} do
        if [ ! -e ${censor} ] & [ -e ${epi}+orig.HEAD ] then
            ARGS="--store-plot --interleave --threshold=2 ${epi}+orig"
#            echo jump_censor ${ARGS}
            stats=`jump_censor ${ARGS}`
            echo ${stats}
            echo ${stats} >> ${STATS_FILE}

Last modified February 24, 2011