From 96d8b48e4f9e989616beec897e642e5772cd590b Mon Sep 17 00:00:00 2001
From: jaeilepp <jaeilepp@gmail.com>
Date: Wed, 22 Mar 2017 15:01:57 +0100
Subject: [PATCH] Fix to eeg_reference docs. (#4084)

---
 mne/channels/channels.py | 44 +++++++++++++++++++++++++++++++++++-----
 mne/io/reference.py      |  1 -
 2 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/mne/channels/channels.py b/mne/channels/channels.py
index 522ee76bc30..83d248712b9 100644
--- a/mne/channels/channels.py
+++ b/mne/channels/channels.py
@@ -239,11 +239,39 @@ class SetChannelsMixin(object):
 
     @verbose
     def set_eeg_reference(self, ref_channels=None, verbose=None):
-        """Rereference EEG channels to new reference channel(s).
-
-        If multiple reference channels are specified, they will be averaged. If
-        no reference channels are specified, an average reference will be
-        applied.
+        """Specify which reference to use for EEG data.
+
+        By default, MNE-Python will automatically re-reference the EEG signal
+        to use an average reference (see below). Use this function to
+        explicitly specify the desired reference for EEG. This can be either an
+        existing electrode or a new virtual channel. This function will
+        re-reference the data according to the desired reference and prevent
+        MNE-Python from automatically adding an average reference.
+
+        Some common referencing schemes and the corresponding value for the
+        ``ref_channels`` parameter:
+
+        No re-referencing:
+            If the EEG data is already using the proper reference, set
+            ``ref_channels=[]``. This will prevent MNE-Python from
+            automatically re-referencing the data to an average reference.
+
+        Average reference:
+            A new virtual reference electrode is created by averaging the
+            current EEG signal. Make sure that all bad EEG channels are
+            properly marked and set ``ref_channels=None``.
+
+        A single electrode:
+            Set ``ref_channels`` to the name of the channel that will act as
+            the new reference.
+
+        The mean of multiple electrodes:
+            A new virtual reference electrode is created by computing the
+            average of the current EEG signal recorded from two or more
+            selected channels. Set ``ref_channels`` to a list of channel names,
+            indicating which channels to use. For example, to apply an average
+            mastoid reference, when using the 10-20 naming scheme, set
+            ``ref_channels=['M1', 'M2']``.
 
         Parameters
         ----------
@@ -277,6 +305,12 @@ def set_eeg_reference(self, ref_channels=None, verbose=None):
         3. In order to apply a reference other than an average reference, the
            data must be preloaded.
 
+        4. Re-referencing to an average reference is done with an SSP
+           projector. This allows applying this reference without preloading
+           the data. Be aware that on preloaded data, SSP projectors are not
+           automatically applied. Use the ``apply_proj()`` method to apply
+           them.
+
         .. versionadded:: 0.13.0
 
         See Also
diff --git a/mne/io/reference.py b/mne/io/reference.py
index 1eb6eb387d0..2abfb7eac38 100644
--- a/mne/io/reference.py
+++ b/mne/io/reference.py
@@ -260,7 +260,6 @@ def set_eeg_reference(inst, ref_channels=None, copy=True, verbose=None):
         channels to use. For example, to apply an average mastoid reference,
         when using the 10-20 naming scheme, set ``ref_channels=['M1', 'M2']``.
 
-
     Parameters
     ----------
     inst : instance of Raw | Epochs | Evoked