Merge pull request #110 from mwaskom/docs_and_prerelease_stuff

Update docs and other housekeeping before 0.5 release

Author: agramfort

.gitignore

@@ -22,3 +22,5 @@ doc/samples
 pysurfer.egg-info
 *.avi
 .tmp/*.png
+examples/example_data/coord-lh.label
+.ipynb_checkpoints/

.mailmap

@@ -0,0 +1 @@
+Michael Waskom <[email protected]> mwaskom <[email protected]>

doc/install.rst

@@ -1,15 +1,33 @@
 .. _install:
 
-Installation and Dependencies
-=============================
+Installing and Getting Started
+==============================
 
-Installing PySurfer is quite simple with easy_install_::
+Installing PySurfer is quite simple with pip_::
 
-    easy_install -U pysurfer
+    pip install pysurfer
 
-or pip_::
+If you already have PySurfer installed, you can also use pip to update it::
 
-    pip install pysurfer
+    pip install -U pysurfer
+
+If you'd like to install the development version, you have two options. You can
+use pip::
+
+    pip install git+git://github.com/nipy/pysurfer.git#egg=pysurfer
+
+Or you can clone the `git repository <https://github.com/nipy/PySurfer>`_ and
+install from the source directory::
+
+    python setup.py install
+
+If you don't have pip, you can also install PySurfer with easy_install_, or use
+easy_install to get pip.
+
+Dependencies
+~~~~~~~~~~~~
+
+PySurfer requires Python 2.7, and it does not work on Python 3.
 
 To use PySurfer, you will need to have the following Python packages:
 
@@ -19,17 +37,42 @@ To use PySurfer, you will need to have the following Python packages:
 * nibabel_
 * mayavi_
 * matplotlib_
-* PIL_
 
-An easy option to get all of these packages is to use the Enthought
-Python Distribution (EPD_) which is free for academic use.
+Some functions also make use of the Python Imaging Library (PIL_), although
+it's not mandatory.
 
-.. include:: links_names.txt
+An easy option to set up this environment is the Anaconda_ distribution, which
+is free and ships with many of the required packages. If you use Anaconda,
+you'll need to install Mayavi separately. This can be done using the ``conda``
+command::
+
+    conda install mayavi
 
-.. note::
+You'll also need to install nibabel, which can be done using ``pip`` as above.
+
+Another option for getting set up is the Enthough Canopy_ environment, which is
+similar to Anaconda and free for academic use.
+
+Getting started
+~~~~~~~~~~~~~~~
+
+PySurfer generally works out of the box on Linux systems. Getting started on
+OSX can be a bit more difficult. We have had success using the Anaconda
+distribution with the additional step of setting the environment variable
+``QT_API`` to ``pyqt``::
+
+    export QT_API=pyqt
+
+If you want to use PySurfer interactively, you should do so in ipython_. After
+starting ipython (either in the terminal, qtconsole, or notebook), you have to
+activate the correct GUI backend, which is probably qt::
+
+    %gui qt
+
+This will allow you to have an open PySurfer window while still being able to
+execute code in the console/notebook.
+
+If you are having trouble getting started using PySurfer, please describe the problem on the `nipy mailing list`_.
+
+.. include:: links_names.txt
 
-    For optimal results and performance make sure IPython is invoked using the
-    best GUI back end. In an EPD environment on Mac OS X this would be WX,
-    so `ipython --pylab wx`. On Linux Debian / Ubuntu (Neurodebian) QT seems
-    to be more appropriate, so `ipython --pylab qt`. Reports for other platforms
-    and distributions are appreciated.

doc/links_names.txt

@@ -75,6 +75,8 @@
 .. _EPD: http://www.enthought.com/products/epd.php
 .. _Traits: http://code.enthought.com/projects/traits/
 .. _PIL: http://www.pythonware.com/products/pil/
+.. _Anaconda: https://store.continuum.io/cshop/anaconda/
+.. _Canopy: https://www.enthought.com/products/canopy/
 
 .. Python imaging projects
 .. _PyMVPA: http://www.pymvpa.org

examples/plot_probabilistic_label.py

@@ -33,7 +33,7 @@
 overlay the label on an activation plot to asses whether it falls within that
 region.
 """
-brain.add_label("BA45", color="#F0F8FF", borders=True, scalar_thresh=.5)
+brain.add_label("BA45", color="#F0F8FF", borders=3, scalar_thresh=.5)
 brain.add_label("BA45", color="#F0F8FF", alpha=.3, scalar_thresh=.5)
 
 """
@@ -46,10 +46,3 @@
 ids, probs = io.read_label(label_file, read_scalars=True)
 prob_field[ids] = probs
 brain.add_data(prob_field, thresh=1e-5, colormap="RdPu")
-
-"""
-Adjust the colorbar to represent the coarseness of the probability estimates
-more closely.
-"""
-brain.data["colorbar"].number_of_colors = 10
-brain.data["colorbar"].number_of_labels = 11

setup.py

@@ -4,7 +4,7 @@
 #                    Michael Waskom <[email protected]>
 #                    Scott Burns <[email protected]>
 
-descr = """PySurfer: Python / FreeSurfer / Mayavi2 for brain imaging"""
+descr = """PySurfer: cortical surface visualization using Python."""
 
 import os
 # deal with MPL sandbox violations during easy_install
@@ -30,12 +30,40 @@
 DOWNLOAD_URL = 'https://github.com/nipy/PySurfer'
 VERSION = version
 
+def check_dependencies():
+
+    needed_deps = ["IPython",
+                   "numpy", "scipy", "matplotlib",
+                   "nibabel",
+                   "mayavi",
+                   ]
+    missing_deps = []
+    for dep in needed_deps:
+        try:
+            __import__(dep)
+        except ImportError:
+            missing_deps.append(dep)
+
+    if missing_deps:
+        missing = ", ".join(missing_deps)
+        raise ImportError("Missing dependencies: %s" % missing)
+
+
 from setuptools import setup
 
 if __name__ == "__main__":
     if os.path.exists('MANIFEST'):
         os.remove('MANIFEST')
 
+    import sys
+    if not (len(sys.argv) >= 2 and ('--help' in sys.argv[1:] or
+            sys.argv[1] in ('--help-commands',
+                            '--version',
+                            'egg_info',
+                            'clean'))):
+        check_dependencies()
+
+
     setup(name=DISTNAME,
           maintainer=MAINTAINER,
           include_package_data=True,
@@ -49,6 +77,7 @@
           zip_safe=False,  # the package can run out of an .egg file
           classifiers=['Intended Audience :: Science/Research',
                        'Intended Audience :: Developers',
+                       'Programming Language :: Python :: 2.7',
                        'License :: OSI Approved',
                        'Programming Language :: Python',
                        'Topic :: Software Development',