frequent operations

Smoothing or registering

These examples show how to smooth data or register data in small memory bites using read loop. Commands are "jip input 1.5" (1.5 mm smoothing kernel) and "jip input" to read file "input.nii" and to output files "input-smooth.nii" or "input-reg.nii"

   usage: jip input 1.5                    usage: jip input 
   read-loop $1.nii                                                        read
   smooth-3d $2                                                          read-loop $1.nii data
   write $1-smooth.nii                                                  register data
   end-loop                                                                  write $1-reg.nii data

   bye                                                                          end-loop


Averaging in 4 dimensions

4-D averaging can be useful for fMRI in cases where the response form is not known (e.g., a drug stimulus). When there are x*y*z*t voxels and n subjects, memory requirements can blow up. This shows how to create a subject-averaged time series by averaging small bites from each file.
          usage: "jip" to average 3 subjects with 550 time points each.
Note that subject data should be normalized 1st ("normalize" command) if the data are raw MRI signal levels, as opposed to a physiological quantity like fCBV or relaxation rate.

              read 0-99                                  read subject1.nii>$1 s1
              read 100-199                            read subject2.nii>$1 s2
              read 200-299                            read subject3.nii>$1 s3
              read 300-399                            average-stacks av
              read 400-n                                  write average.bshort av
              bye                                                                  delete   # clear memory

Converting between overlays and bitmaps

An “overlay" is a series of voxel indices with weights between 0 and 1, whereas a bitmap is a full volume (an “image”) complete with physical dimensions and here also enabled with weights (image intensities) between 0 and 1. Overlays are ASCII files that may be quite small, if they only refer to a small region of an image, whereas all bitmaps will have the same dimensions for a given matrix size.

               bitmap to overlay                                                   overlay to bitmap

          read brain-mask.nii brain                                            read brain.ovl

          create-overlay-from-bitmap brain                               read brain-mask.nii template   # a template is needed to define dimensions

          write-overlay brain.ovl                                                create-bitmap-from-overlay  bitmap template # bitmap has dimensions of template

          bye                                                                             write brain.nii bitmap

Overlays are convenient to work with due to their small size, but in order to do things like down-sample them or register them to another space, they first need to be converted to images (bitmaps). 

Creating your own template

Cross-subject registration based upon a template is a common function during analysis.
Let's suppose you have a template volume and you want to maintain the field of view for use with wire frames (which can generate overlays), but you want to change the resolution and perhaps the number of slices.  This can be done by "jip", which calls "".  The file "" is:

          read template-rare.nii rare
          write my-template.nii

... and the file "" looks something like this:

          # It is necessary to set the resolution and matrix size.
          # If not set explictly, the origin and direction will be inherited.
          # Matrix size: resolution * matrix should be conserved in each dimension.
          # The original matrix is 64 x 50 x 42 with resolution 0.25 x 0.25 x 0.5
          shift-pixels 0 0 -2  # This command keeps track of the origin!
          clip-z-to 36         # now the z extent is 18 mm, not 21 mm
          set registration-resolution   0.25 0.25 1
          set registration-matrix       64   50   18

Joseph B. Mandeville, Athinoula A. Martinos Center for Biomedical Imaging at MGH/MIT/Harvard