Improving aesthetics of the focus label example

Author: mwaskom

examples/plot_label_foci.py

@@ -1,59 +1,65 @@
 """
-============================================
-Plot a label generated at an activation foci
-============================================
+=======================
+Generate Surface Labels
+=======================
 
-Plot a spheroid at a position on the surface manifold
-according to an MNI coordinate, generate a label
-around it and plot it.
+Define a label that is centered on a specific vertex in the surface mesh. Plot
+that label and the focus that defines its center.
 
 """
 print __doc__
 
-import os
 from surfer import Brain, utils
 
 subject_id = "fsaverage"
-subjects_dir = os.environ["SUBJECTS_DIR"]
 
 """
 Bring up the visualization.
 """
 brain = Brain(subject_id, "lh", "inflated")
 
 """
-First we'll get a set of stereotaxic foci in the MNI
-coordinate system. These might be peak activations from
-a volume based analysis.
+First we'll identify a stereotaxic focus in the MNI coordinate system. This
+might be a peak activations from a volume based analysis.
 """
 coord = [-43, 25, 24]
 
+"""
+Next we grow a label along the surface around the neareset vertex to this
+coordinate in the white surface mesh. The `n_steps` argument controls the size
+of the resulting label.
+"""
 utils.coord_to_label(subject_id, coord, label='example_data/coord',
-                     hemi='lh', n_steps=50, map_surface="white")
-brain.add_label('example_data/coord-lh.label')
+                     hemi='lh', n_steps=25, map_surface="white")
+brain.add_label('example_data/coord-lh.label', color="darkseagreen", alpha=.8)
 
 """
-Now we plot the foci on the inflated surface. We will map
-the foci onto the surface by finding the vertex on the "white"
-mesh that is closest to the coordinate of the point we want
-to display.
+Now we plot the focus on the inflated surface at the vertex identified in the
+previous step.
 """
-brain.add_foci([coord], map_surface="white", color="gold")
+brain.add_foci([coord], map_surface="white", color="mediumseagreen")
 
 """
-or using a vertex index
+We can also do this using a vertex index, perhaps defined as the peak
+activation in a surface analysis. This will be more accurate than using a
+volume-based focus.
 """
 coord = 0
 
 utils.coord_to_label(subject_id, coord, label='example_data/coord',
-                     hemi='lh', n_steps=50, map_surface="white",
+                     hemi='lh', n_steps=40, map_surface="white",
                      coord_as_vert=True)
-brain.add_label('example_data/coord-lh.label', color='blue')
+brain.add_label('example_data/coord-lh.label', color='royalblue', alpha=.8)
+
+"""
+Now we plot the foci on the inflated surface. We will map the foci onto the
+surface by finding the vertex on the "white" mesh that is closest to the
+coordinate of the point we want to display.
+"""
+brain.add_foci([coord], map_surface="white", coords_as_verts=True,
+                color="mediumblue")
 
 """
-Now we plot the foci on the inflated surface. We will map
-the foci onto the surface by finding the vertex on the "white"
-mesh that is closest to the coordinate of the point we want
-to display.
+Set the camera position to show the extent of the labels.
 """
-brain.add_foci([coord], map_surface="white", color="red", coords_as_verts=True)
+brain.show_view(dict(elevation=40, distance=430))