Rewrite introduction.

Author: JoeZiminski

examples/long_tutorials/handle_drift/plot_handle_drift.py

@@ -2,16 +2,51 @@
 Handle motion/drift with spikeinterface NEW
 ===========================================
 
-Spikeinterface offers a very flexible framework to handle drift as a preprocessing step.
-If you want to know more, please read the
-:ref:`motion_correction` section of the documentation.
-
-Here is a short demo on how to handle drift using the high-level function
-:py:func:`~spikeinterface.preprocessing.correct_motion()`.
-
+When running *in vivo* electrophysiology recordings, movement of the probe is
+an inevitability, especially when the subjects are not head-fixed. SpikeInterface
+includes a number of popular methods to compensate for probe motion during the
+preprocessing step.
+
+### What is drift and where does it come from?
+
+Movement of the probe means that the spikes recorded on the probe 'drift' along it.
+Typically, this motion is vertical along the probe (along the 'y' axis) which
+manifests as the units moving long the probe in space.
+
+All common motion-correction methods address this vertical drift. Horizontal ('x')
+or forward/backwards ('z') motion, that would appear as the amplitude of a unit
+changing over time, are much harder to model and not handled in available motion-correction algorithms.
+Fortunately, vertical drift is the most common form of motion as the probe is
+more likely to move along the path it was inserted, rather than in other directions
+where it is buffeted against the brain.
+
+Vertical drift can come in two forms, 'rigid' and 'non-rigid'. Rigid drift
+is drift caused by movement of the entire probe and the motion is the
+same for all points along the probe. Non-rigid drift is instead caused by
+local movement of parts of the brain along the probe, and can affect
+the recording at only certain points along the probe.
+
+### How SpikeInterface handles drift
+
+Spikeinterface offers a very flexible framework to handle drift as a
+preprocessing step. In this tutorial we will cover the three main
+drift-correction algorithms implemented in SpikeInterface with
+a focus on running the methods and interpreting the output. For
+more information on the theory and implementation of these methods,
+see the :ref:`motion_correction` section of the documentation.
+
+### The drift correction steps
+
+The easiest way to run drift correction in SpikeInterface is with the
+high-level :py:func:`~spikeinterface.preprocessing.correct_motion()` function.
 This function takes a preprocessed recording as input and then internally runs
-several steps (it can be slow!) and returns a lazy
-recording that interpolates the traces on-the-fly to compensate for the motion.
+several steps and returns a lazy recording that interpolates the traces on-the-fly
+to compensate for the motion.
+
+The
+:py:func:`~spikeinterface.preprocessing.correct_motion()`
+function provides a convenient wrapper around a number of sub-functions
+that together implement the full drift correction algorithm.
 
 Internally this function runs the following steps:
 
@@ -20,12 +55,25 @@
 | **3.** ``estimate_motion()``
 | **4.** ``interpolate_motion()``
 
-All these sub-steps can be run with different methods and have many parameters.
-The high-level function suggests 3 pre-difined "presets".
+All these sub-steps have many parameters which dictate the
+speed and effectiveness of motion correction. As such, `correct_motion`
+provides three setting 'presets' which configure the motion correct
+to proceed either as:
+
+* `rigid_fast` - a fast, not particularly accurate correction assuming ridigt drift.
+* `kilosort-like` - Mimics what is done in Kilosort (REF)
+* `nonrigid_accurate` - A decentralised drift correction, introduced by the Paninski group (REF)
+
+**Now, let's dive into running motion correction with these three
+methods on a simulated dataset and interpreting the output.
+
 """
 
+
+
 # %%
-# FIRST WE IMPORT AND # We will use GENERATE RECORDINGS
+#.. seealso::
+#    hello world
 
 from pathlib import Path
 import matplotlib.pyplot as plt