TMI Viewer Instructions Examples
The tmi_viewer package contains two programs:
Displays multimodal neuroimaging data (surfaces and volumes) in the same space from a TMI file (although TMI files are not required).
Features:
- Multiple surfaces with vertex painting can be easily viewed with voxel images.
- Voxel images can be viewed as: (1) surfaces using a marching cube algorithm, (2) voxel contour, (3) and voxel scalar field.
- The default settings are optimized for viewing neuroimages.
- tmi_viewer is highly optimized for speed.
- Many autothresholding algorithms available including: Otsu et al., Li et al., Yen et al., and Z threholding. (See Citations)
- Extremely fast algorithm for applying Lapacian or Taubin (low-pass) smooth. e.g., ~1000 passes takes around one minute.
- Easy export of background transparent images for creating figures.
- Many new look-up tables (LUTs) that are specifically designed for visualising neuroimaging statistics (below, at the bottom) as well as the LUTs included with matplotlib.
Outputs a web-page with whole brain slices from voxel-based neuroimages in native coordinates with optional overlaps.
Features:
- Great for making figures: Creates a web-page displaying overlapping any number of voxel-based images, and they can be at any resolution.
- Many autothresholding algorithms available including: Otsu et al., Li et al., Yen et al., and Z threholding. (See Citations)
- Import images, binarize them at any threshold, and paint the image outline.
- Specify number of slices, size of slices, transparency, etc.
These programs relies on Mayavi, and setting can changed using the Mayavi interactive session. If you use them please cite:
Ramachandran, P. and Varoquaux, G., Mayavi. 3D Visualization of Scientific Data. IEEE Computing in Science & Engineering, 13 (2), pp. 40-51 (2011).
tmi_viewer -h
OUTPUT
usage: tmi_viewer [-h] (-i *.tmi | --no-tmi | --plotluts) [-d * [* ...]]
[-dv * [* ...]] [-dvsf * [* ...]] [-dvc * [* ...]]
[-ds int [int ...]] [-lut LOOKUPTABLE] [-autothr]
[-ttype {otsu,otsu_p,li,li_p,yen,yen_p,zscore,zscore_p}]
[--zthresh float] [-t THRESHOLDS THRESHOLDS] [-a ALPHA]
[-o OPACITY] [-ifs [* [* ...]]] [-iv [* [* ...]]]
[-ivsf * [* ...]] [-ivc [* [* ...]]] [-sfa axis [axis ...]]
[-sfo float] [-save basename] [--savetype filetype]
[-ss int] [-stype str] [--interpolation str]
[-smgh * [* ...]] [-oh] [-os] [-v]
tmi_viewer: Displays multimodal neuroimaging data (surfaces and volumes) in
the same space from a TMI file (although TMI files are not required). This
program relies on Mayavi, and setting can changed using the Mayavi interactive
session. If you use it please cite: Ramachandran, P. and Varoquaux, G.,
`Mayavi: 3D Visualization of Scientific Data` IEEE Computing in Science &
Engineering, 13 (2), pp. 40-51 (2011).
optional arguments:
-h, --help show this help message and exit
-i *.tmi, -i_tmi *.tmi, --inputtmi *.tmi
Input the *.tmi file containing the statistics to
view.
--no-tmi Do not input a TMI file.
--plotluts Plots the avalable lookup tables, and exits.
-d * [* ...], --display * [* ...]
Display a surface with a scalar. The mask, contrast,
and surface are required (check values with -oh or
-os). If the same surface is used multiple times, make
sure to set the alpha to 0 for each subsequent input.
E.g., -d 0 0 0 tm-sunset_r -d 1 0 0 tm-breeze_r 0.
Format: {0 mask} {1 contrast} {2 surface} {3 LUT} {4
alpha} {5 vmin} {6 vmax}
-dv * [* ...], --displayvoxel * [* ...]
Display a volume as a surface and scalar. The mask and
contrast are required (check values with -oh or -os).
Format: -dv {0 mask} {1 contrast} {2 LUT} {3 vmin} {4
vmax}
-dvsf * [* ...], --displayvoxelscalarfield * [* ...]
Display a volume on as scalar field(s). Default [x, y]
plane (can be changed with -sfa). The mask and
contrast are required (check values with -oh or -os).
Format: -dvsf {0 mask} {1 contrast} {2 LUT} {3 vmin}
{4 vmax}
-dvc * [* ...], --displayvoxelcontour * [* ...]
Display a volume as a 3D contour. The mask and
contrast are required (check values with -oh or -os).
Format: -dvc {0 mask} {1 contrast} {2 LUT} {3 vmin} {4
vmax} {5 Contour_Opacity} {6 Number_Contours}
-ds int [int ...], --displaysurface int [int ...]
Display a surface without a scalar (i.e., just the
surface).
-lut LOOKUPTABLE, --lookuptable LOOKUPTABLE
Set the default color map to display. Use --plotluts
to see the available lookup-tables (LUTs). Any LUT can
be reverse by appending _r (e.g. -lut red-yellow_r).
-autothr, --autotheshold
Use automatic thresholding as default if none is
supplied. Default is 'otsu', but it other can be
specified using -ttype.
-ttype {otsu,otsu_p,li,li_p,yen,yen_p,zscore,zscore_p}, --thesholdingtype {otsu,otsu_p,li,li_p,yen,yen_p,zscore,zscore_p}
Method used to set the the lower threshold if
thresholds are not supplied (Default is otsu).
Appending '_p' sets all negative data to zero prior to
autothresholding.
--zthresh float The z value to use for autothresholding. Default =
[2.3264].
-t THRESHOLDS THRESHOLDS, --thresholds THRESHOLDS THRESHOLDS
Set the default lower (vmin) and upper (vmax)
thresholds. Defaults are: [0.95, 1]
-a ALPHA, --alpha ALPHA
Set alpha [0 to 255]
-o OPACITY, --opacity OPACITY
Set opacity [0 to 1]
-ifs [* [* ...]], --importfreesurfer [* [* ...]]
Import a freesurfer surface, and optionally, a *.mgh
scalar. If the same surface is used multiple times,
make sure to set the alpha to 0 for each subsequent
inputs. E.g., -ifs lh.midthickness
lh.positive.stats.mgh tm-sunset_r -ifs lh.midthickness
lh.negative.stats.mgh tm-breeze_r 0. The import
surface is required. Format: -ifs {0 surface} {1 mgh}
{2 LUT} {3 alpha} {4 vmin} {5 vmax}
-iv [* [* ...]], --importvolume [* [* ...]]
Import a volume and display it as a surface and
scalar. The import volume (Nifti, Minc, MGH) is
required. Format: -iv {0 image} {1 LUT} {2 vmin} {3
vmax} {4 opacity}
-ivsf * [* ...], --importvoxelscalarfield * [* ...]
Import a volume and display it as scalar field(s).
Default [x, y] plane (can be changed with -sfa). The
import volume (Nifti, Minc, MGH) is required. Format:
-ivsf {0 image} {1 LUT} {2 vmin} {3 vmax}
-ivc [* [* ...]], --importvoxelcontour [* [* ...]]
Import a volume display it as 3D contourd. The import
volume (Nifti, Minc, MGH) is required. Format: -ivc {0
image} {1 LUT} {2 vmin} {3 vmax} {4 Contour_Opacity}
{5 Number_Contours}
-sfa axis [axis ...], --scalarfieldaxis axis [axis ...]
Select axis/axes for scalar field. Only {X, Y, Z} are
valid arguements
-sfo float, --sfplaneopacity float
Set the plane opacity for scalar fields (the outline
will be removed). Default is: [1]
-save basename, --savesnapshots basename
Save snapshots of the image. Input the basename of the
output.
--savetype filetype Choose output snapshot type by file extension. Default
is: ['png']
-ss int, --surfacesmoothing int
Apply Laplician or Taubin smoothing before
visualization. Input the number of iterations (e.g.,
-ss 5).
-stype str, --smoothingtype str
Set type of surface smoothing to use (choices are:
laplacian, taubin). The default is laplacian. The
Taubin (aka low-pass) filter smooths curves/surfaces
without the shrinkage of the laplacian filter.
--interpolation str Specify the reslice interpolation (choices are: cubic,
linear, nearest_neighbour). The default is linear
-smgh * [* ...], --selectmghvolume * [* ...]
Set the subject/contrast/timepoint in 4D MGH file
imported with -ifs. Optionally, a multiplier can also
be supplied. The # of inputs for -ifs and -smgh must
match (If an input MGH is 3D use 0). Format: {0
volnum} {1 multiplier}
-oh, --history Output tmi file history and exits.
-os, --outputstats Output min/max values from value for each contrast per
mask and exits.
-v, --version show program's version number and exit
TMI files can contain multiple modalities in a single file so it may be necessary to view what is in the file before attempting to visualize the images. Therefore, it is recommended to view a text summary of the mask, contrastis, and statistics prior to using tmi_viewer.
In this example, the TMI file is: pFWER_stats_all.mmr.tmi (1-p stats after undergoing family-wise error rate correction for all masks)
View the stats:
tmi_viewer -i pFWER_stats_all.mmr.tmi -os
OUTPUT
--- Subject/Contrast[0]: tstat_pFWER_con1 ---
Mask[0] lh.all.area.03B.mgh [0.0000, 0.9784]
Mask[1] rh.all.area.03B.mgh [0.0000, 0.9553]
Mask[2] lh.all.thickness.03B.mgh [0.0000, 0.9497]
Mask[3] rh.all.thickness.03B.mgh [0.0000, 0.8226]
Mask[4] lh.all.ICVF.03B.mgh [0.0000, 0.9881]
Mask[5] rh.all.ICVF.03B.mgh [0.0000, 0.9441]
Mask[6] lh.all.nbackS8.03B.mgh [0.0000, 0.9993]
Mask[7] rh.all.nbackS8.03B.mgh [0.0000, 0.9993]
--- Subject/Contrast[1]: negtstat_pFWER_con1 ---
Mask[0] lh.all.area.03B.mgh [0.0000, 0.0000]
Mask[1] rh.all.area.03B.mgh [0.0000, 0.0000]
Mask[2] lh.all.thickness.03B.mgh [0.0000, 0.0000]
Mask[3] rh.all.thickness.03B.mgh [0.0000, 0.0014]
Mask[4] lh.all.ICVF.03B.mgh [0.0000, 0.0000]
Mask[5] rh.all.ICVF.03B.mgh [0.0000, 0.0035]
Mask[6] lh.all.nbackS8.03B.mgh [0.0000, 0.9818]
Mask[7] rh.all.nbackS8.03B.mgh [0.0000, 0.7018]
--- Surfaces ---
Surface[0] lh.midthickness
Surface[1] rh.midthickness
Surface[2] lh.midthickness
Surface[3] rh.midthickness
Surface[4] lh.midthickness
Surface[5] rh.midthickness
Surface[6] lh.midthickness
Surface[7] rh.midthickness
Explanation
The output provides four important pieces of information.
- There are two contrasts [0] tstat_pFWER_con1 and [1] negtstat_pFWER_con1
- There are eight masks [0] lh.all.area.03B.mgh ... [7] rh.all.nbackS8.03B.mgh
- There are eigth surface objects [0] lh.midthickness ... [7] rh.midthickness note: these are the same two surfaces repeated. There could be just two.
- The maximum and minimum values (in this case, 1-p FWER corrected) are included for each mask.
a. Quicly viewing the left, surface area mask[0], contrast [0], with lh.midthickness surface object[0]. All default settings are used.
tmi_viewer -i pFWER_stats_all.mmr.tmi -d 0 0 0
Explanation
The -d option takes the following input (the first three are required): {0 mask} {1 contrast} {2 surface} {3 LUT} {4 alpha} {5 vmin} {6 vmax}
We used: mask[0] lh.all.area.03B.mgh , contrast[0] tstat_pFWER_con1, Surface[0] lh.midthickness
With the default values for: LUT (red-yellow), alpha (255; i.e., surface is fully visible), vmin (0.95), vmax (1.0)
b. View both hemispheres with spatial smoothing.
tmi_viewer -i pFWER_stats_all.mmr.tmi -d 6 0 0 -d 7 0 1 -ss 10 -stype taubin
Explanation
The -d option is called twice for the right and left hemispehere. In this example, the N-back 2v0 contrast is displayed. 10 iterations of spatial smoothing was performed using the Taubin (low-pass) algorithm to prevent surface object shrinkage.
c. Viewing multiple contrasts on the same surface.
tmi_viewer -i pFWER_stats_all.mmr.tmi -d 6 0 6 tm-sunset_r -d 7 0 7 tm-sunset_r -d 6 1 6 tm-breeze_r 0 -d 7 1 7 tm-breeze_r 0
OUTPUT
ERROR: In /build/vtk-NWL3SN/vtk-5.10.1+dfsg/Common/vtkLookupTable.cxx, line 117
vtkLookupTable (0xc5e7ca0): Bad table range: [0.95, 0.701816]
Explanation
The -d option is called 4 times. The L/R positive contrast and the L/R negative contrast. For the positiv and negative contrasts different LUTs are input. Importantly, the alpha for the first two surfaces is 255 (i.e., full visiable) which the alpha for the next two surfaces is 0 (i.e., the backgroud surface is invisiable). An error is given because the Mask[7] rh.all.nbackS8.03B.mgh [0.0000, 0.7018] value is less than .95 (the minimum value).