Merge pull request #121 from mwaskom/remove_config_file

Remove config_opts and config file

Author: larsoner

CHANGES

@@ -1,14 +1,38 @@
 PySurfer Changes
 ================
 
+Version 0.6
+-----------
+
+- Values that were previously selected using a ``config_opts``
+  dictionary in the ``Brain`` constructor are now keyword arguments.
+  This should make it easier to use tab-completion in IPython, and will
+  generally simplify your scripts. To ease transition, a ``config_opts``
+  argument will still be caught, and its entries will be used (overriding
+  the keyword arguments), but it will be removed in a future release.
+- The ability to set default values in a config file has been removed.
+  While convenient, this approach encourages code that is not fully
+  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
+  a specific colormap and anchor points for that colormap. Additionally,
+  the default anchor points now use robust statistics to give better
+  values.
+
 Version 0.5
 -----------
 
 - Added control over the width of outlines when plotting the borders of
   annotations or labels.
-- The visual display of the surfaces was improved by using surface normals
+- The visual display of the surfaces was improved by using surface normals.
 - Made colormap specification in Brain.add_data and Brain.add_contour_overlay
-  more flexible, with better defaults
+  more flexible, with better defaults.
 - Brain.save_montage() can now produce 2d grids of views in addition to
   horizontal and vertical arrangements. 
 - Fixed some installation issues and added explicit checks for dependencies

bin/pysurfer

@@ -72,16 +72,10 @@ if __name__ == '__main__':
 
         from surfer import Brain
 
-        # Get a dict of config override options
-        confkeys = ["size", "background", "cortex"]
-        argdict = args.__dict__
-        config_opts = dict([(k, v) for k, v in argdict.items()
-                            if k in confkeys and v])
-        views = args.views
-
         # Load  up the figure and underlying brain object
         b = Brain(args.subject_id, args.hemi, args.surf, args.curv,
-                  args.title, views=views, config_opts=config_opts)
+                  args.title, views=args.views, size=args.size,
+                  background=args.background, cortex=args.cortex)
 
         # Maybe load some morphometry
         if args.morphometry is not None:

doc/documentation/custom_viz.rst

@@ -12,7 +12,17 @@ have to delve into the underlying engine to get a different look.
 Changing the display background
 -------------------------------
 
-The display background can take any valid matplotlib color.
+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).
+
+Changing the display size
+-------------------------
+
+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
 ----------------------------------- 
@@ -22,45 +32,33 @@ cortical curvature values, so you can see which patches of cortex
 are gyri and which are sulci (pass ``curv=False`` to the
 :class:`Brain` constructor, or use the ``-no-curv`` switch in the
 command-line interface to turn this off). There are four preset
-themes for the curvature color scheme: ``classic``, ``bone``,
-``high_contrast``, and ``low_contrast``:
+themes for the curvature color scheme, which you can pass to the
+``cortex`` parameter in the :class:`Brain` constructor: ``classic``,
+``bone``, ``high_contrast``, and ``low_contrast``:
 
 .. image:: ../_static/cortex_options.png
 
 Note that, in each theme, the darker color signifies sulci.
 
-Changing the display size
--------------------------
+It's also possible to customize this further by passing the name of
+a mayavi colormap or a colormap name along with the endpoints of the
+colormap and whether it should be reversed.
 
-The default display window is 800px by 800px, but this is also
-customizable. You may use any positive number for the size
-(subject, possibly, to Mayavi/hardware limitations we are not
-aware of). The viewing window is always square, so just give one
-number and it will be used for both width and height.
+Additionally, you can load a continuous curvature map with the
+:func:`add_morphometry` method.
 
 How to use these themes
 -----------------------
 
-These options can be set in three places. The first is in your
-config file. Set your preferred visualization theme there, and it
-will be used automatically whenever you start PySurfer. You may
-also override this theme for any individual visualization session.
-If using the Python ``surfer`` library, you may pass a
-``config_opts`` dictionary to the :class:`Brain` constructor,
-which will override any values you have set in your config file.
-If using the command-line interface, there are parameters for each
-of the above options. Regardless of method, the key names are
-``background``, ``cortex``, and ``size``.
-
-For example:
+These options can be selected either as keyword arguments to the
+:class:`Brain` constructor,
 
 .. sourcecode:: ipython
 
     In [1]: from surfer import Brain
-    In [2]: b = Brain('fsaverage', 'lh', 'inflated', config_opts={'cortex':'bone'})
+    In [2]: b = Brain('fsaverage', 'lh', 'inflated', cortex='bone')
 
-or::
+or as options in the command-line interface::
 
     pysurfer fsaverage lh inflated -background slategray -size 400
 
-in your shell terminal.

examples/plot_fmri_conjunction.py

@@ -20,8 +20,7 @@
 """
 Initialize the visualization.
 """
-brain = Brain("fsaverage", "lh", "inflated",
-              config_opts=dict(background="white"))
+brain = Brain("fsaverage", "lh", "inflated", background="white")
 
 """
 Read both of the activation maps in using

examples/plot_meg_inverse_solution.py

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

examples/plot_morphometry.py

@@ -11,7 +11,7 @@
 print(__doc__)
 
 brain = Brain("fsaverage", "both", "pial", views="frontal",
-              config_opts=dict(background="dimgray"))
+              background="dimgray")
 
 """
 Because the morphometry files generated by

examples/plot_parc_values.py

@@ -22,8 +22,7 @@
 """
 Bring up the visualization.
 """
-brain = Brain(subject_id, hemi, surface,
-              config_opts=dict(background="white"))
+brain = Brain(subject_id, hemi, surface, background="white")
 
 """
 Read in the Buckner resting state network annotation. (This requires a

examples/plot_parcellation.py

@@ -20,8 +20,7 @@
 Bring up the visualization
 """
 brain = Brain(subject_id, hemi, surface, views=view,
-              config_opts={"cortex": "bone",
-                           "background": "ivory"})
+              cortex="bone", background="ivory")
 
 """
 Display the 'aparc' parcellation borders.

examples/plot_probabilistic_label.py

@@ -15,8 +15,7 @@
 
 print(__doc__)
 
-brain = Brain("fsaverage", "lh", "inflated",
-              config_opts=dict(cortex="low_contrast"))
+brain = Brain("fsaverage", "lh", "inflated", cortex="low_contrast")
 
 """
 The easiest way to label any vertex that could be in the region is with

examples/plot_resting_correlations.py

@@ -15,8 +15,8 @@
 print(__doc__)
 
 """Bring up the visualization"""
-brain = Brain("fsaverage", "split", "inflated", views=['lat', 'med'],
-              config_opts=dict(background="white"))
+brain = Brain("fsaverage", "split", "inflated",
+              views=['lat', 'med'], background="white")
 
 """Project the volume file and return as an array"""
 mri_file = "example_data/resting_corr.nii.gz"