Specifying kwargs as mlab_kws and make the documentation more clear.

Author: DingkunLiu

surfer/viz.py

@@ -913,7 +913,7 @@ def _iter_time(self, time_idx, interpolation):
     ###########################################################################
     # ADDING DATA PLOTS
     def add_overlay(self, source, min=2, max="robust_max", sign="abs",
-                    name=None, hemi=None, **kwargs):
+                    name=None, hemi=None, **mlab_kws):
         """Add an overlay to the overlay dict from a file or array.
 
         Parameters
@@ -932,7 +932,8 @@ def add_overlay(self, source, min=2, max="robust_max", sign="abs",
             If None, it is assumed to belong to the hemipshere being
             shown. If two hemispheres are being shown, an error will
             be thrown.
-        kwargs: other mayavi surface arguments.
+        **mlab_kws: All additional keyword arguments are passed to the
+            `mlab.pipeline.surface` call.
         """
         hemi = self._check_hemi(hemi)
         # load data here
@@ -945,7 +946,7 @@ def add_overlay(self, source, min=2, max="robust_max", sign="abs",
         views = self._toggle_render(False)
         for brain in self._brain_list:
             if brain['hemi'] == hemi:
-                ol.append(brain['brain'].add_overlay(old, **kwargs))
+                ol.append(brain['brain'].add_overlay(old, **mlab_kws))
         if name in self.overlays_dict:
             name = "%s%d" % (name, len(self.overlays_dict) + 1)
         self.overlays_dict[name] = ol
@@ -959,7 +960,7 @@ def add_data(self, array, min=None, max=None, thresh=None,
                  hemi=None, remove_existing=False, time_label_size=14,
                  initial_time=None, scale_factor=None, vector_alpha=None,
                  mid=None, center=None, transparent=False, verbose=None,
-                 **kwargs):
+                 **mlab_kws):
         """Display data from a numpy array on the surface.
 
         This provides a similar interface to
@@ -1037,7 +1038,8 @@ def add_data(self, array, min=None, max=None, thresh=None,
             vector-valued data. If None (default), ``alpha`` is used.
         verbose : bool, str, int, or None
             If not None, override default verbose level (see surfer.verbose).
-        kwargs: other mayavi surface arguments.
+        **mlab_kws: All additional keyword arguments are passed to the
+            `mlab.pipeline.surface` call.
 
         Notes
         -----
@@ -1175,7 +1177,7 @@ def time_label(x):
                 s, ct, bar, gl = brain['brain'].add_data(
                     array, min, mid, max, thresh, lut, colormap, alpha,
                     colorbar, layer_id, smooth_mat, magnitude, magnitude_max,
-                    scale_factor, vertices, vector_alpha, **kwargs)
+                    scale_factor, vertices, vector_alpha, **mlab_kws)
                 surfs.append(s)
                 bars.append(bar)
                 glyphs.append(gl)
@@ -1199,7 +1201,7 @@ def time_label(x):
         self._toggle_render(True, views)
 
     def add_annotation(self, annot, borders=True, alpha=1, hemi=None,
-                       remove_existing=True, color=None, **kwargs):
+                       remove_existing=True, color=None, **mlab_kws):
         """Add an annotation file.
 
         Parameters
@@ -1226,7 +1228,8 @@ def add_annotation(self, annot, borders=True, alpha=1, hemi=None,
         color : matplotlib-style color code
             If used, show all annotations in the same (specified) color.
             Probably useful only when showing annotation borders.
-        kwargs: other mayavi surface arguments.
+        **mlab_kws: All additional keyword arguments are passed to the
+            `mlab.pipeline.surface` call.
         """
         hemis = self._check_hemis(hemi)
 
@@ -1309,11 +1312,11 @@ def add_annotation(self, annot, borders=True, alpha=1, hemi=None,
                 if brain['hemi'] == hemi:
                     self.annot_list.append(
                         brain['brain'].add_annotation(annot, ids, cmap,
-                                                      **kwargs))
+                                                      **mlab_kws))
         self._toggle_render(True, views)
 
     def add_label(self, label, color=None, alpha=1, scalar_thresh=None,
-                  borders=False, hemi=None, subdir=None, **kwargs):
+                  borders=False, hemi=None, subdir=None, **mlab_kws):
         """Add an ROI label to the image.
 
         Parameters
@@ -1345,7 +1348,8 @@ def add_label(self, label, color=None, alpha=1, scalar_thresh=None,
             label directory rather than in the label directory itself (e.g.
             for ``$SUBJECTS_DIR/$SUBJECT/label/aparc/lh.cuneus.label``
             ``brain.add_label('cuneus', subdir='aparc')``).
-        kwargs: other mayavi surface arguments.
+        **mlab_kws: All additional keyword arguments are passed to the
+            `mlab.pipeline.surface` call.
         Notes
         -----
         To remove previously added labels, run Brain.remove_labels().
@@ -1426,7 +1430,7 @@ def add_label(self, label, color=None, alpha=1, scalar_thresh=None,
         for brain in self.brains:
             if brain.hemi == hemi:
                 array_id, surf = brain.add_label(label, label_name, color,
-                                                 alpha, **kwargs)
+                                                 alpha, **mlab_kws)
                 surfaces.append(surf)
                 array_ids.append((brain, array_id))
         self._label_dicts[label_name] = {'surfaces': surfaces,
@@ -1536,7 +1540,7 @@ def remove_labels(self, labels=None, hemi=None):
 
     def add_morphometry(self, measure, grayscale=False, hemi=None,
                         remove_existing=True, colormap=None,
-                        min=None, max=None, colorbar=True, **kwargs):
+                        min=None, max=None, colorbar=True, **mlab_kws):
         """Add a morphometry overlay to the image.
 
         Parameters
@@ -1558,7 +1562,8 @@ def add_morphometry(self, measure, grayscale=False, hemi=None,
             of the data is used.
         colorbar : bool
             If True, show a colorbar corresponding to the overlay data.
-        kwargs: other mayavi surface arguments.
+        **mlab_kws: All additional keyword arguments are passed to the
+            `mlab.pipeline.surface` call.
         """
         hemis = self._check_hemis(hemi)
         morph_files = []
@@ -1620,12 +1625,12 @@ def add_morphometry(self, measure, grayscale=False, hemi=None,
                 if brain.hemi == hemi:
                     self.morphometry_list.append(brain.add_morphometry(
                         morph_data, colormap, measure, min, max, colorbar,
-                        **kwargs))
+                        **mlab_kws))
         self._toggle_render(True, views)
 
     def add_foci(self, coords, coords_as_verts=False, map_surface=None,
                  scale_factor=1, color="white", alpha=1, name=None,
-                 hemi=None, **kwargs):
+                 hemi=None, **mlab_kws):
         """Add spherical foci, possibly mapping to displayed surf.
 
         The foci spheres can be displayed at the coordinates given, or
@@ -1655,7 +1660,8 @@ def add_foci(self, coords, coords_as_verts=False, map_surface=None,
             If None, it is assumed to belong to the hemipshere being
             shown. If two hemispheres are being shown, an error will
             be thrown.
-        kwargs: other mayavi point3d arguments.
+        **mlab_kws: All additional keyword arguments are passed to the
+            `mlab.point3d` call.
         """
         from matplotlib.colors import colorConverter
         hemi = self._check_hemi(hemi)
@@ -1692,14 +1698,14 @@ def add_foci(self, coords, coords_as_verts=False, map_surface=None,
             if brain['hemi'] == hemi:
                 fl.append(brain['brain'].add_foci(foci_coords, scale_factor,
                                                   color, alpha, name,
-                                                  **kwargs))
+                                                  **mlab_kws))
         self.foci_dict[name] = fl
         self._toggle_render(True, views)
 
     def add_contour_overlay(self, source, min=None, max=None,
                             n_contours=7, line_width=1.5, colormap="YlOrRd_r",
                             hemi=None, remove_existing=True, colorbar=True,
-                            **kwargs):
+                            **mlab_kws):
         """Add a topographic contour overlay of the positive data.
 
         Note: This visualization will look best when using the "low_contrast"
@@ -1729,7 +1735,8 @@ def add_contour_overlay(self, source, min=None, max=None,
             If there is an existing contour overlay, remove it before plotting.
         colorbar : bool
             If True, show the colorbar for the scalar value.
-        kwargs: other mayavi surface arguments.
+        **mlab_kws: All additional keyword arguments are passed to the
+            `mlab.pipeline.surface` call.
         """
         hemi = self._check_hemi(hemi)
 
@@ -1756,11 +1763,12 @@ def add_contour_overlay(self, source, min=None, max=None,
             if brain.hemi == hemi:
                 self.contour_list.append(brain.add_contour_overlay(
                     scalar_data, min, max, n_contours, line_width, lut,
-                    colorbar, **kwargs))
+                    colorbar, **mlab_kws))
         self._toggle_render(True, views)
 
     def add_text(self, x, y, text, name, color=None, opacity=1.0,
-                 row=-1, col=-1, font_size=None, justification=None, **kwargs):
+                 row=-1, col=-1, font_size=None, justification=None,
+                 **mlab_kws):
         """ Add a text to the visualization
 
         Parameters
@@ -1783,13 +1791,14 @@ def add_text(self, x, y, text, name, color=None, opacity=1.0,
             Row index of which brain to use
         col : int
             Column index of which brain to use
-        kwargs: other mayavi text3d arguments.
+        mlab_kws: All additional keyword arguments are passed to the
+            `mlab.text` call.
         """
         if name in self.texts_dict:
             self.texts_dict[name]['text'].remove()
         text = self.brain_matrix[row, col].add_text(x, y, text,
                                                     name, color, opacity,
-                                                    **kwargs)
+                                                    **mlab_kws)
         self.texts_dict[name] = dict(row=row, col=col, text=text)
         if font_size is not None:
             text.property.font_size = font_size
@@ -3206,7 +3215,7 @@ def _remove_vector_data(self, glyphs):
         if glyphs is not None:
             glyphs.parent.parent.remove()
 
-    def add_overlay(self, old, **kwargs):
+    def add_overlay(self, old, **mlab_kws):
         """Add an overlay to the overlay dict from a file or array"""
         array_id, mesh = self._add_scalar_data(old.mlab_data)
 
@@ -3216,7 +3225,7 @@ def add_overlay(self, old, **kwargs):
                 pos = mlab.pipeline.surface(
                     pos_thresh, colormap="YlOrRd", figure=self._f,
                     vmin=old.pos_lims[1], vmax=old.pos_lims[2],
-                    reset_zoom=False, **kwargs)
+                    reset_zoom=False, **mlab_kws)
                 pos.actor.property.backface_culling = False
                 pos_bar = mlab.scalarbar(pos, nb_labels=5)
             pos_bar.reverse_lut = True
@@ -3232,7 +3241,7 @@ def add_overlay(self, old, **kwargs):
                 neg = mlab.pipeline.surface(
                     neg_thresh, colormap="PuBu", figure=self._f,
                     vmin=old.neg_lims[1], vmax=old.neg_lims[2],
-                    reset_zoom=False, **kwargs)
+                    reset_zoom=False, **mlab_kws)
                 neg.actor.property.backface_culling = False
                 neg_bar = mlab.scalarbar(neg, nb_labels=5)
             neg_bar.scalar_bar_representation.position = (0.05, 0.01)
@@ -3246,7 +3255,7 @@ def add_overlay(self, old, **kwargs):
     @verbose
     def add_data(self, array, fmin, fmid, fmax, thresh, lut, colormap, alpha,
                  colorbar, layer_id, smooth_mat, magnitude, magnitude_max,
-                 scale_factor, vertices, vector_alpha, **kwargs):
+                 scale_factor, vertices, vector_alpha, **mlab_kws):
         """Add data to the brain"""
         # Calculate initial data to plot
         if array.ndim == 1:
@@ -3289,7 +3298,7 @@ def add_data(self, array, fmin, fmid, fmax, thresh, lut, colormap, alpha,
             surf = mlab.pipeline.surface(
                 pipe, colormap=colormap, vmin=fmin, vmax=fmax,
                 opacity=float(alpha), figure=self._f, reset_zoom=False,
-                **kwargs)
+                **mlab_kws)
             surf.actor.property.backface_culling = False
 
         # apply look up table if given
@@ -3314,13 +3323,13 @@ def add_data(self, array, fmin, fmid, fmax, thresh, lut, colormap, alpha,
             scale_factor_norm=scale_factor_norm)
         return surf, orig_ctable, bar, glyphs
 
-    def add_annotation(self, annot, ids, cmap, **kwargs):
+    def add_annotation(self, annot, ids, cmap, **mlab_kws):
         """Add an annotation file"""
         # Add scalar values to dataset
         array_id, pipe = self._add_scalar_data(ids)
         with warnings.catch_warnings(record=True):
             surf = mlab.pipeline.surface(pipe, name=annot, figure=self._f,
-                                         reset_zoom=False, **kwargs)
+                                         reset_zoom=False, **mlab_kws)
             surf.actor.property.backface_culling = False
 
         # Set the color table
@@ -3331,13 +3340,13 @@ def add_annotation(self, annot, ids, cmap, **kwargs):
         return dict(surface=surf, name=annot, colormap=cmap, brain=self,
                     array_id=array_id)
 
-    def add_label(self, label, label_name, color, alpha, **kwargs):
+    def add_label(self, label, label_name, color, alpha, **mlab_kws):
         """Add an ROI label to the image"""
         from matplotlib.colors import colorConverter
         array_id, pipe = self._add_scalar_data(label)
         with warnings.catch_warnings(record=True):
             surf = mlab.pipeline.surface(pipe, name=label_name, figure=self._f,
-                                         reset_zoom=False, **kwargs)
+                                         reset_zoom=False, **mlab_kws)
             surf.actor.property.backface_culling = False
         color = colorConverter.to_rgba(color, alpha)
         cmap = np.array([(0, 0, 0, 0,), color])
@@ -3349,13 +3358,13 @@ def add_label(self, label, label_name, color, alpha, **kwargs):
         return array_id, surf
 
     def add_morphometry(self, morph_data, colormap, measure,
-                        min, max, colorbar, **kwargs):
+                        min, max, colorbar, **mlab_kws):
         """Add a morphometry overlay to the image"""
         array_id, pipe = self._add_scalar_data(morph_data)
         with warnings.catch_warnings(record=True):
             surf = mlab.pipeline.surface(
                 pipe, colormap=colormap, vmin=min, vmax=max, name=measure,
-                figure=self._f, reset_zoom=False, **kwargs)
+                figure=self._f, reset_zoom=False, **mlab_kws)
 
         # Get the colorbar
         if colorbar:
@@ -3370,27 +3379,27 @@ def add_morphometry(self, morph_data, colormap, measure,
                     array_id=array_id)
 
     def add_foci(self, foci_coords, scale_factor, color, alpha, name,
-                 **kwargs):
+                 **mlab_kws):
         """Add spherical foci, possibly mapping to displayed surf"""
         # Create the visualization
         with warnings.catch_warnings(record=True):  # traits
             points = mlab.points3d(
                 foci_coords[:, 0], foci_coords[:, 1], foci_coords[:, 2],
                 np.ones(foci_coords.shape[0]), name=name, figure=self._f,
                 scale_factor=(10. * scale_factor), color=color, opacity=alpha,
-                reset_zoom=False, **kwargs)
+                reset_zoom=False, **mlab_kws)
         return points
 
     def add_contour_overlay(self, scalar_data, min=None, max=None,
                             n_contours=7, line_width=1.5, lut=None,
-                            colorbar=True, **kwargs):
+                            colorbar=True, **mlab_kws):
         """Add a topographic contour overlay of the positive data"""
         array_id, pipe = self._add_scalar_data(scalar_data)
         with warnings.catch_warnings(record=True):
             thresh = threshold_filter(pipe, low=min)
             surf = mlab.pipeline.contour_surface(
                 thresh, contours=n_contours, line_width=line_width,
-                reset_zoom=False, **kwargs)
+                reset_zoom=False, **mlab_kws)
         if lut is not None:
             l_m = surf.module_manager.scalar_lut_manager
             l_m.load_lut_from_list(lut / 255.)
@@ -3408,12 +3417,12 @@ def add_contour_overlay(self, scalar_data, min=None, max=None,
         # Set up a dict attribute with pointers at important things
         return dict(surface=surf, colorbar=bar, brain=self, array_id=array_id)
 
-    def add_text(self, x, y, text, name, color=None, opacity=1.0, **kwargs):
+    def add_text(self, x, y, text, name, color=None, opacity=1.0, **mlab_kws):
         """ Add a text to the visualization"""
         color = self._fg_color if color is None else color
         with warnings.catch_warnings(record=True):
             text = mlab.text(x, y, text, name=name, color=color,
-                             opacity=opacity, figure=self._f, **kwargs)
+                             opacity=opacity, figure=self._f, **mlab_kws)
             return text
 
     def remove_data(self, layer_id):