Remove height and width kwargs in favor of a single size parameter

size can be either a single value, for a square window, or a tuple of
values, to give the width and height of a rectangular window.

Author: mwaskom

CHANGES

@@ -15,6 +15,9 @@ Version 0.6
   reproducible. While existing code that was written expecting a config
   file will still run, the visualization will fall back to default values.
   These should be updated directly in your plotting scripts.
+- Figure size is now specified only through the ``size`` keyword argument
+  of :class:`Brain`. To make a rectangular window, pass a ``(width, height)``
+  tuple. Passing a single value to ``size`` will still make a square window.
 - The ``cortex`` keyword argument can now be a mayavi colormap name or
   a ``(colormap, min, max, reverse)`` tuple for full control.
 - Morphometry plotting was made more flexible with the ability to pass

doc/documentation/custom_viz.rst

@@ -14,15 +14,15 @@ Changing the display background
 
 The display background can take any valid matplotlib color (i.e.,
 it can be a tuple of rgb values, an rgb hex string, or a named HTML
-color.
+color).
 
 Changing the display size
 -------------------------
 
-The default display window is 800px by 800px, but this is also
-customizable. You can set the size of a square window with the ``size``
-parameter or make a rectangular window with the ``width`` and ``height``
-parameters.
+The default display window is 800px by 800px, but this can be configured
+using the ``size`` keyword argument in the Brain constructor. ``size``
+should either be a single number to make a square window, or a pair of
+values, ``(width, height)``, to make a rectangular window.
 
 Changing the curvature color scheme
 ----------------------------------- 

examples/plot_meg_inverse_solution.py

@@ -22,7 +22,7 @@
 """
 create Brain object for visualization
 """
-brain = Brain(subject_id, hemi, surface, width=800, height=400)
+brain = Brain(subject_id, hemi, surface, size=(800, 400))
 
 """
 read MNE dSPM inverse solution

examples/save_movie.py

@@ -16,7 +16,7 @@
 """
 create Brain object for visualization
 """
-brain = Brain('fsaverage', 'split', 'inflated', width=800, height=400)
+brain = Brain('fsaverage', 'split', 'inflated', size=(800, 400))
 
 """
 read and display MNE dSPM inverse solution

surfer/tests/test_viz.py

@@ -76,19 +76,16 @@ def test_brains():
     curvs = [True, False]
     titles = [None, 'Hello']
     cortices = ["low_contrast", ("Reds", 0, 1, False)]
-    widths = [200, "w"]
-    heights = [400, "h"]
-    sizes = [None, 600]
+    sizes = [500, (400, 300)]
     backgrounds = ["white", "blue"]
     foregrounds = ["black", "white"]
     figs = [None, mlab.figure()]
     subj_dirs = [None, subj_dir]
-    for surf, hemi, curv, title, cort, w, h, s, bg, fg, fig, sd \
-            in zip(surfs, hemis, curvs, titles, cortices,
-                   widths, heights, sizes,
+    for surf, hemi, curv, title, cort, s, bg, fg, fig, sd \
+            in zip(surfs, hemis, curvs, titles, cortices, sizes,
                    backgrounds, foregrounds, figs, subj_dirs):
         brain = Brain(subject_id, hemi, surf, curv, title,
-                      cort, w, h, s, bg, fg, fig, sd)
+                      cort, s, bg, fg, fig, sd)
         brain.close()
     assert_raises(ValueError, Brain, subject_id, 'lh', 'inflated',
                   subjects_dir='')

surfer/viz.py

@@ -302,10 +302,9 @@ class Brain(object):
         'classic', 'bone', 'low_contrast', or 'high_contrast'), or the
         name of mayavi colormap, or a tuple with values (colormap, min,
         max, reverse) to fully specify the curvature colors.
-    width, height : floats
-        width and height (in pixels) of the display window
-    size : float
-        specify a square display window, overriding the width and height
+    size : float or pair of floats
+        the size of the window, in pixels. can be one number to specify
+        a square window, or the (width, height) of a rectangular window.
     background, foreground : matplotlib colors
         color of the background and foreground of the display window
     figure : list of instances of mayavi.core.scene.Scene | None
@@ -331,10 +330,10 @@ class Brain(object):
 
     """
     def __init__(self, subject_id, hemi, surf, curv=True, title=None,
-                 cortex="classic", width=800, height=800, size=None,
-                 background="black", foreground="white", figure=None,
-                 subjects_dir=None, views=['lat'],
-                 show_toolbar=False, offscreen=False, config_opts=None):
+                 cortex="classic", size=800, background="black",
+                 foreground="white", figure=None, subjects_dir=None,
+                 views=['lat'], show_toolbar=False, offscreen=False,
+                 config_opts=None):
 
         # Keep backwards compatability
         if config_opts is not None:
@@ -344,12 +343,14 @@ def __init__(self, subject_id, hemi, surf, curv=True, title=None,
                    "constructor.")
             warn(msg)
             cortex = config_opts.get("cortex", cortex)
-            width = config_opts.get("width", width)
-            height = config_opts.get("height", height)
-            size = config_opts.get("size", size)
             background = config_opts.get("background", background)
             foreground = config_opts.get("foreground", foreground)
 
+            size = config_opts.get("size", size)
+            width = config_opts.get("width", size)
+            height = config_opts.get("height", size)
+            size = (width, height)
+
         col_dict = dict(lh=1, rh=1, both=1, split=2)
         n_col = col_dict[hemi]
         if hemi not in col_dict.keys():
@@ -388,8 +389,7 @@ def __init__(self, subject_id, hemi, surf, curv=True, title=None,
             self.geo[h] = geo
 
         # deal with making figures
-        self._set_window_properties(width, height, size,
-                                    background, foreground)
+        self._set_window_properties(size, background, foreground)
         figures, _v = _make_viewer(figure, n_row, n_col, title,
                                    self._scene_size, offscreen)
         self._figures = figures
@@ -471,11 +471,12 @@ def _toggle_render(self, state, views=None):
             _force_render(self._figures, self._window_backend)
         return views
 
-    def _set_window_properties(self, width, height, size,
-                               background, foreground):
+    def _set_window_properties(self, size, background, foreground):
         """Set window properties that are used elsewhere."""
         # old option "size" sets both width and height
-        if size is not None:
+        try:
+            width, height = size
+        except TypeError:
             width, height = size, size
         self._scene_size = height, width