← Back to branch summary

~nipy-developers/nipy/fff2

« back to all changes in this revision

Viewing changes to doc/activation_map.rst

  • Committer: Gael Varoquaux
  • Date: 2009-02-17 06:25:47 UTC
  • mto: This revision was merged to the branch mainline in revision 226.
  • Revision ID: gael.varoquaux@normalesup.org-20090217062547-elvvdbec9pv3816j
Document the activation map visualization scripts

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/activation_map.rst
 
1
 
 
2
Automatic plotting of activation maps
 
3
=====================================
 
4
 
 
5
.. currentmodule:: fff2.viz.activation_maps
 
6
 
 
7
The module :mod:`fff2.viz.activation_maps` provides functions to plot
 
8
visualization of activation maps in a non-interactive way.
 
9
 
 
10
2D cuts of an activation map can be plotted and superimposed on an
 
11
anatomical map using matplotlib_. In addition, Mayavi2_ can be used to
 
12
plot 3D maps, using volumetric rendering. Some emphasis is made on
 
13
automatic choice of default parameters, such as cut coordinates, to give
 
14
a sensible view of a map in a purely automatic way, for instance to save
 
15
a summary of the output of a calculation.
 
16
 
 
17
.. _matplotlib: http://matplotlib.sourceforge.net
 
18
 
 
19
.. _Mayavi2: http://code.enthought.com/projects/mayavi
 
20
 
 
21
An example
 
22
-----------
 
23
 
 
24
::
 
25
 
 
26
    from fff2.viz.activation_maps import plot_map, mni_sform, \
 
27
            coord_transform
 
28
 
 
29
    # First, create a fake activation map: a 3D image in MNI space with
 
30
    # a large rectangle of activation around Brodmann Area 26
 
31
    import numpy as np
 
32
    mni_sform_inv = np.linalg.inv(mni_sform)
 
33
    map = np.zeros((182, 218, 182))
 
34
    x, y, z = -6, -53, 9
 
35
    x_map, y_map, z_map = coord_transform(x, y, z, mni_sform_inv)
 
36
    map[x_map-30:x_map+30, y_map-3:y_map+3, z_map-10:z_map+10] = 1
 
37
    
 
38
    # And now, visualize it:
 
39
    plot_map(map, mni_sform, cut_coords=(y, x, z), vmin=0.5)
 
40
 
 
41
This creates the following image:
 
42
 
 
43
.. image:: activation_map.png
 
44
 
 
45
The same plot can be obtained fully automaticaly, by using
 
46
:func:`auto_plot_map` to find the activation threshold `vmin` and the cut
 
47
coordinnates::
 
48
 
 
49
    from fff2.viz.activation_maps import auto_plot_map
 
50
    auto_plot_map(map, mni_sform)
 
51
 
 
52
In this simple example, the code will easily detect the bar as activation
 
53
and position the cut at the center of the bar.
 
54
 
 
55
 
 
56
fff2.viz.activation_maps functions
 
57
-----------------------------------
 
58
 
 
59
.. autosummary::
 
60
    :toctree: generated
 
61
 
 
62
    coord_transform
 
63
    find_activation
 
64
    find_cut_coords
 
65
    plot_map_2d
 
66
    plot_map_3d
 
67
    auto_plot_map
 
68
    plot_niftifile
 
69
 
 
70
The plot_activation script
 
71
---------------------------
 
72
 
 
73
In addition to the above functions, callable from Python, there is also
 
74
script :program:`plot_activation` that can be used to easily render
 
75
previews from Nifti files. It can also optionally output an html file, to
 
76
summarize many maps on one screen.
 
77
 
 
78
In its simplest use, it is called like this::
 
79
 
 
80
    plot_activation file1.nii file2.nii [...]
 
81
 
 
82
The :program:`plot_activation` script has several many options:
 
83
 
 
84
**-h**, **--help**            
 
85
    show the help message and exit
 
86
 
 
87
**-o** *DIR*, **--outdir=DIR**
 
88
    write all output to DIR
 
89
 
 
90
**-f** *FILE*, **--htmlfile=FILE**
 
91
    write report to a html file FILE, useful when visualizing multiple files
 
92
 
 
93
**-a** *FILE*, **--anat=FILE**
 
94
    use the given Nifti file as an anatomy
 
95
 
 
96
**-M** *FILE*, **--mask=FILE**  
 
97
    use the given Nifti file as a mask
 
98
 
 
99
**-d**, **--no3d**
 
100
    don't try to do a 3D view
 
101
 
 
102
**-s**, **--sign**  
 
103
    force activation sign to be positive
 
104
 
 
105
**-c** *CUT_COORDS*, **--cut-coords=CUT_COORDS**
 
106
    Talairach coordinates of the 2D cuts
 
107
 
 
108
**-m** *VMIN*, **--vmin=VMIN**
 
109
    Minimum value for the activation, used for thresholding
 
110
 
 
111