Merge pull request #3167 from alejoe91/update-docs

Extend docs and API for generation module

doc/api.rst

@@ -338,14 +338,60 @@ spikeinterface.curation
 spikeinterface.generation
 -------------------------
 
+Core
+~~~~
 .. automodule:: spikeinterface.generation
 
+    .. autofunction:: generate_recording
+    .. autofunction:: generate_sorting
+    .. autofunction:: generate_snippets
+    .. autofunction:: generate_templates
+    .. autofunction:: generate_recording_by_size
+    .. autofunction:: generate_ground_truth_recording
+    .. autofunction:: add_synchrony_to_sorting
+    .. autofunction:: synthesize_random_firings
+    .. autofunction:: inject_some_duplicate_units
+    .. autofunction:: inject_some_split_units
+    .. autofunction:: synthetize_spike_train_bad_isi
+    .. autofunction:: inject_templates
+    .. autofunction:: noise_generator_recording
+    .. autoclass:: InjectTemplatesRecording
+    .. autoclass:: NoiseGeneratorRecording
+
+Drift
+~~~~~
+.. automodule:: spikeinterface.generation
+
+    .. autofunction:: generate_drifting_recording
+    .. autofunction:: generate_displacement_vector
+    .. autofunction:: make_one_displacement_vector
     .. autofunction:: make_linear_displacement
     .. autofunction:: move_dense_templates
     .. autofunction:: interpolate_templates
     .. autoclass:: DriftingTemplates
     .. autoclass:: InjectDriftingTemplatesRecording
 
+Hybrid
+~~~~~~
+.. automodule:: spikeinterface.generation
+
+    .. autofunction:: generate_hybrid_recording
+    .. autofunction:: estimate_templates_from_recording
+    .. autofunction:: select_templates
+    .. autofunction:: scale_template_to_range
+    .. autofunction:: relocate_templates
+    .. autofunction:: fetch_template_object_from_database
+    .. autofunction:: fetch_templates_database_info
+    .. autofunction:: list_available_datasets_in_template_database
+    .. autofunction:: query_templates_from_database
+
+
+Noise
+~~~~~
+.. automodule:: spikeinterface.generation
+
+    .. autofunction:: generate_noise
+
 
 spikeinterface.sortingcomponents
 --------------------------------

doc/how_to/benchmark_with_hybrid_recordings.rst

@@ -9,7 +9,7 @@ with known spiking activity. The template (aka average waveforms) of the
 injected units can be from previous spike sorted data. In this example,
 we will be using an open database of templates that we have constructed
 from the International Brain Laboratory - Brain Wide Map (available on
-`DANDI <https://dandiarchive.org/dandiset/000409?search=IBL&page=2&sortOption=0&sortDir=-1&showDrafts=true&showEmpty=false&pos=9>`__).
+`DANDI <https://dandiarchive.org/dandiset/000409?search=IBL&page=2&sortOption=0&sortDir=-1&showDrafts=true&showEmpty=false&pos=9>`_).
 
 Importantly, recordings from long-shank probes, such as Neuropixels,
 usually experience drifts. Such drifts have to be taken into account in

doc/modules/generation.rst

@@ -1,9 +1,28 @@
 Generation module
 =================
 
-The :py:mod:`spikeinterface.generation` provides functions to generate recordings containing spikes.
-This module proposes several approaches for this including purely synthetic recordings as well as "hybrid" recordings (where templates come from true datasets).
+The :py:mod:`spikeinterface.generation` provides functions to generate recordings containing spikes,
+which can be used as "ground-truth" for benchmarking spike sorting algorithms.
 
+There are several approaches to generating such recordings.
+One possibility is to generate purely synthetic recordings. Another approach is to use real
+recordings and add synthetic spikes to them, to make "hybrid" recordings.
+The advantage of the former is that the ground-truth is known exactly, which is useful for benchmarking.
+The advantage of the latter is that the spikes are added to real noise, which can be more realistic.
 
-The :py:mod:`spikeinterface.core.generate` already provides functions for generating synthetic data but this module will supply an extended and more complex
-machinery, for instance generating recordings that possess various types of drift.
+For hybrid recordings, the main challenge is to generate realistic spike templates.
+We therefore built an open database of templates that we have constructed from the International
+Brain Laboratory - Brain Wide Map (available on
+`DANDI <https://dandiarchive.org/dandiset/000409?search=IBL&page=2&sortOption=0&sortDir=-1&showDrafts=true&showEmpty=false&pos=9>`_).
+You can check out this collection of over 600 templates from this `web app <https://spikeinterface.github.io/hybrid_template_library/>`_.
+
+The :py:mod:`spikeinterface.generation` module offers tools to interact with this database to select and download templates,
+manupulating (e.g. rescaling and relocating them), and construct hybrid recordings with them.
+Importantly, recordings from long-shank probes, such as Neuropixels, usually experience drifts.
+Such drifts can be taken into account in order to smoothly inject spikes into the recording.
+
+The :py:mod:`spikeinterface.generation` also includes functions to generate different kinds of drift signals and drifting
+recordings, as well as generating synthetic noise profiles of various types.
+
+Some of the generation functions are defined in the :py:mod:`spikeinterface.core.generate` module, but also exposed at the
+:py:mod:`spikeinterface.generation` level for convenience.