Repository: mne-tools/mne-python

Issue:
[ENH] Add more complete `mne.viz.Brain` functionality tutorial
Per @rob-luke 's suggestion in #9618, it might be a good idea to explain all the methods of `mne.viz.Brain`.

We have from @rob-luke :
- creating a brain figure
- adding some sensors
- rotating it
- taking a screenshot
- marking a region
- adding a stc

I would add:
- Adding the head
- Removing mesh objects
- Explaining the different views

There are probably many more useful things not on here...


Discussion:

Resolving patch:
diff --git a/examples/visualization/brain.py b/examples/visualization/brain.py
new file mode 100644
--- /dev/null
+++ b/examples/visualization/brain.py
@@ -0,0 +1,113 @@
+"""
+.. _ex-brain:
+
+===============================
+Plotting with ``mne.viz.Brain``
+===============================
+
+In this example, we'll show how to use :class:`mne.viz.Brain`.
+"""
+# Author: Alex Rockhill <aprockhill@mailbox.org>
+#
+# License: BSD-3-Clause
+
+# %%
+# Plot a brain
+# ------------
+#
+# In this example we use the ``sample`` data which is data from a subject
+# being presented auditory and visual stimuli to display the functionality
+# of :class:`mne.viz.Brain` for plotting data on a brain.
+
+import os.path as op
+import matplotlib.pyplot as plt
+
+import mne
+from mne.datasets import sample
+
+print(__doc__)
+
+data_path = sample.data_path()
+subjects_dir = op.join(data_path, 'subjects')
+sample_dir = op.join(data_path, 'MEG', 'sample')
+
+# %%
+# Add source information
+# ----------------------
+#
+# Plot source information.
+
+brain_kwargs = dict(alpha=0.1, background='white', cortex='low_contrast')
+brain = mne.viz.Brain('sample', subjects_dir=subjects_dir, **brain_kwargs)
+
+stc = mne.read_source_estimate(op.join(sample_dir, 'sample_audvis-meg'))
+stc.crop(0.09, 0.1)
+
+kwargs = dict(fmin=stc.data.min(), fmax=stc.data.max(), alpha=0.25,
+              smoothing_steps='nearest', time=stc.times)
+brain.add_data(stc.lh_data, hemi='lh', vertices=stc.lh_vertno, **kwargs)
+brain.add_data(stc.rh_data, hemi='rh', vertices=stc.rh_vertno, **kwargs)
+
+# %%
+# Modify the view of the brain
+# ----------------------------
+#
+# You can adjust the view of the brain using ``show_view`` method.
+
+brain = mne.viz.Brain('sample', subjects_dir=subjects_dir, **brain_kwargs)
+brain.show_view(azimuth=190, elevation=70, distance=350, focalpoint=(0, 0, 20))
+
+# %%
+# Highlight a region on the brain
+# -------------------------------
+#
+# It can be useful to highlight a region of the brain for analyses.
+# To highlight a region on the brain you can use the ``add_label`` method.
+# Labels are stored in the Freesurfer label directory from the ``recon-all``
+# for that subject. Labels can also be made following the
+# `Freesurfer instructions
+# <https://surfer.nmr.mgh.harvard.edu/fswiki/mri_vol2label>`_
+# Here we will show Brodmann Area 44.
+#
+# .. note:: The MNE sample dataset contains only a subselection of the
+#           Freesurfer labels created during the ``recon-all``.
+
+brain = mne.viz.Brain('sample', subjects_dir=subjects_dir, **brain_kwargs)
+brain.add_label('BA44', hemi='lh', color='green', borders=True)
+brain.show_view(azimuth=190, elevation=70, distance=350, focalpoint=(0, 0, 20))
+
+# %%
+# Include the head in the image
+# -----------------------------
+#
+# Add a head image using the ``add_head`` method.
+
+brain = mne.viz.Brain('sample', subjects_dir=subjects_dir, **brain_kwargs)
+brain.add_head(alpha=0.5)
+
+# %%
+# Add sensors positions
+# ---------------------
+#
+# To put into context the data that generated the source time course,
+# the sensor positions can be displayed as well.
+
+brain = mne.viz.Brain('sample', subjects_dir=subjects_dir, **brain_kwargs)
+evoked = mne.read_evokeds(op.join(sample_dir, 'sample_audvis-ave.fif'))[0]
+trans = mne.read_trans(op.join(sample_dir, 'sample_audvis_raw-trans.fif'))
+brain.add_sensors(evoked.info, trans)
+brain.show_view(distance=500)  # move back to show sensors
+
+# %%
+# Create a screenshot for exporting the brain image
+# -------------------------------------------------
+#
+# For publication you may wish to take a static image of the brain,
+# for this use ``screenshot``.
+
+brain = mne.viz.Brain('sample', subjects_dir=subjects_dir, **brain_kwargs)
+img = brain.screenshot()
+fig, ax = plt.subplots()
+ax.imshow(img)
+ax.axis('off')
+fig.suptitle('Brain')


Test patch: