Repository: mne-tools/mne-python

Issue:
BUG: Clarify install instructions
We should make it clear that people should install Python2 for now, due to Mayavi.

Also, we need to make sure the instructions still work. Apparently Anaconda has been having some problems due to PyQt5 / matplotlib / mayavi junk. I suspect we'll need to add a line, at least for a little while, along the lines of `conda install numpy scipy sklearn mayavi matplotlib` to force dependency resolution. And this stuff should be backported.

Thanks @bloyl for suffering through the existing directions.


Discussion:
I have installed mne-python and been through this recently so I'd be happy to help.
I tried to reproduce my installation steps this morning, but I have an issue when importing numpy (`ImportError: libopenblasp-r0-ea933816.2.18.so: cannot open shared object file: No such file or directory`)

Steps to reproduce:

```
conda create --name mne python=2.7 ipython && source activate mne
conda install numpy scipy mayavi scikit-learn matplotlib
(mne) mathurin@mathurin-HP-EliteBook-840-G3:~$ which ipython
/home/mathurin/anaconda3/envs/mne/bin/ipython
(mne) mathurin@mathurin-HP-EliteBook-840-G3:~$ ipython
Python 2.7.12 |Continuum Analytics, Inc.| (default, Jul  2 2016, 17:42:40) 
Type "copyright", "credits" or "license" for more information.

IPython 5.1.0 -- An enhanced Interactive Python.
?         -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help      -> Python's own help system.
object?   -> Details about 'object', use 'object??' for extra details.

In [1]: import numpy
---------------------------------------------------------------------------
ImportError                               Traceback (most recent call last)
<ipython-input-1-5a0bd626bb1d> in <module>()
----> 1 import numpy

/home/mathurin/anaconda3/envs/mne/lib/python2.7/site-packages/numpy/__init__.py in <module>()
    178         return loader(*packages, **options)
    179 
--> 180     from . import add_newdocs
    181     __all__ = ['add_newdocs',
    182                'ModuleDeprecationWarning',

/home/mathurin/anaconda3/envs/mne/lib/python2.7/site-packages/numpy/add_newdocs.py in <module>()
     11 from __future__ import division, absolute_import, print_function
     12 
---> 13 from numpy.lib import add_newdoc
     14 
     15 ###############################################################################

/home/mathurin/anaconda3/envs/mne/lib/python2.7/site-packages/numpy/lib/__init__.py in <module>()
      6 from numpy.version import version as __version__
      7 
----> 8 from .type_check import *
      9 from .index_tricks import *
     10 from .function_base import *

/home/mathurin/anaconda3/envs/mne/lib/python2.7/site-packages/numpy/lib/type_check.py in <module>()
      9            'common_type']
     10 
---> 11 import numpy.core.numeric as _nx
     12 from numpy.core.numeric import asarray, asanyarray, array, isnan, \
     13                 obj2sctype, zeros

/home/mathurin/anaconda3/envs/mne/lib/python2.7/site-packages/numpy/core/__init__.py in <module>()
     12 if 'GOTOBLAS_MAIN_FREE' not in os.environ:
     13     os.environ['GOTOBLAS_MAIN_FREE'] = '1'
---> 14 from . import multiarray
     15 os.environ.clear()
     16 os.environ.update(envbak)

ImportError: libopenblasp-r0-ea933816.2.18.so: cannot open shared object file: No such file or directory

```

Contrary to what's mentionned [here](https://github.com/ContinuumIO/anaconda-issues/issues/445), `conda install libgfortran==1`
 does not change the error.
And the versions as shown by pip freeze are:

```
(mne) mathurin@mathurin-HP-EliteBook-840-G3:~$ pip freeze
apptools==4.2.1
backports.shutil-get-terminal-size==1.0.0
configobj==5.0.6
decorator==4.0.10
enum34==1.1.6
envisage==4.4.0
ipython==5.1.0
ipython-genutils==0.1.0
matplotlib==1.4.3
mayavi==4.4.0
mne==0.13
nibabel==2.1.0
nose==1.3.7
numpy==1.9.3
path.py==0.0.0
pathlib2==2.1.0
pexpect==4.0.1
pickleshare==0.7.4
prompt-toolkit==1.0.8
ptyprocess==0.5.1
pyface==4.4.0
Pygments==2.1.3
pyparsing==2.0.3
pysurfer==0.6
python-dateutil==2.5.3
pytz==2016.7
scikit-learn==0.16.1
scipy==0.17.1
simplegeneric==0.8.1
six==1.10.0
traitlets==4.3.1
traits==4.4.0
traitsui==4.4.0
VTK==5.10.1
wcwidth==0.1.7


```

I cannot install numpy=1.10 because of mayavi requirements, nor numpy=1.8 because of fontconfig requirements.

It turns out installing numpy=1.9.0 along with libgfortran==1 allows me to import numpy. I had issues importing surfer, caused by `import traits.api` (`ImportError: cannot import name _py2to3`), which was apparently due to conflicting install of traits=4.5.0 and 4.4.0 in ~/anaconda3/pkgs. As adviced [here](https://github.com/ContinuumIO/anaconda-issues/issues/767) I removed the traits related folders and reinstalled traits=4.4.0 with conda, which solved the issue. But now `import surfer` fails, with error message:

```
RuntimeError                              Traceback (most recent call last)
RuntimeError: module compiled against API version a but this version of numpy is 9

...

/home/mathurin/anaconda3/envs/mne/lib/python2.7/site-packages/tvtk/array_handler.py in <module>()
     26 
     27 # Enthought library imports.
---> 28 from tvtk.array_ext import set_id_type_array
     29 from tvtk.common import is_old_pipeline
     30 

ImportError: numpy.core.multiarray failed to import
```

I have in the past had such problems ... but using pip to upgrade `matplotlib` and `numpy` after installing everything via conda seems to have worked for me

I wouldn't recommend using `pip` to install `numpy` in an Anaconda install. Anaconda by default uses MKL, and installing via `pip` will not. I'm a bit surprised this didn't break a lot of stuff.

I can't manage to find out why pysurfer isn't built with the correct version of numpy; 1.9.0 is the only one installed in my environment. I have also tried building pysurfer from source, but I still obtain `RuntimeError: module compiled against API version a but this version of numpy is 9`

I have not found a clean way to install a working version of mayavi using only conda. However I'm posting this as it might help  others in the future: my solution was to install everything with conda, then update mayavi to 4.5 and numpy to 1.11 with pip:

```
conda create --name test_mne python=2.7  matplotlib scipy scikit-learn ipython numpy mayavi
source activate test_mne
pip install -U mayavi numpy
```

It is also worth adding that if I launch `ipython --matplotlib=qt`, the following import crashes
`from mayavi import mlab`
with error `ValueError: API 'QDate' has already been set to version 1`
The workaround is to launch ipython without options, and as first command input 

```
from pyface.qt import QtGui, QtCore
%matplotlib qt
```

@Eric89GXL 

> We should make it clear that people should install Python2 for now, due to Mayavi.

Are you sure? I installed mayavi on python 3 with conda:

```
conda install -c menpo mayavi
```

and I have no problems with mayavi (except occasional window freezing in jupyter which I also get for matplotlib in [some cases](https://github.com/matplotlib/matplotlib/issues/6675)).

I'm not sure if we should recommend using an unofficial repository.
@agramfort WDYT?

Yeah, it's not official but it was recommended once in mayavi github issue. I can only say that it works for me.

I also use an unofficial mayavi build on conda with py35

i tried many things but apparently using vtk7 from satra and mayavi from
pip works on my machine (TM)

This combination seems to work for me (OS X, Python 2.7):

`$ conda install numpy scipy matplotlib mayavi h5py pyqt=4.10 pygments=1`
`$ pip install mne imageio pysurfer`

With the caveat mentioned by @mathurinm  that I have to import `mlab` before `%matplotlib qt`

We should probably also break up the Python install page (https://mne-tools.github.io/stable/install_mne_python.html) to have the advanced steps separate. That way the install instructions almost fit on a single page, which is more user-friendly.
+1


Resolving patch:
diff --git a/doc/conf.py b/doc/conf.py
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -153,7 +153,7 @@
         ("Examples", "auto_examples/index"),
         ("API", "python_reference"),
         ("Manual", "manual/index"),
-        ("Contribute", "contributing"),
+        ("Contribute", "contribute_to_mne"),
         ("FAQ", "faq"),
     ],
     }
@@ -260,7 +260,7 @@
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-latex_use_parts = True
+latex_toplevel_sectioning = 'part'
 
 # Additional stuff for the LaTeX preamble.
 # latex_preamble = ''
diff --git a/mne/source_space.py b/mne/source_space.py
--- a/mne/source_space.py
+++ b/mne/source_space.py
@@ -2359,6 +2359,7 @@ def get_volume_labels_from_aseg(mgz_fname, return_colors=False):
         The names of segmented volumes included in this mgz file.
     label_colors : list of str
         The RGB colors of the labels included in this mgz file.
+
     Notes
     -----
     .. versionadded:: 0.9.0


Test patch: