Merge branch 'main' into rt-sort

Author: alejoe91

doc/api.rst

@@ -22,6 +22,8 @@ spikeinterface.core
     .. autofunction:: estimate_sparsity
     .. autoclass:: ChannelSparsity
         :members:
+    .. autoclass:: Motion
+        :members:
     .. autoclass:: BinaryRecordingExtractor
     .. autoclass:: ZarrRecordingExtractor
     .. autoclass:: BinaryFolderRecording
@@ -277,8 +279,6 @@ spikeinterface.comparison
 
     .. autoclass:: CollisionGTComparison
     .. autoclass:: CorrelogramGTComparison
-    .. autoclass:: CollisionGTStudy
-    .. autoclass:: CorrelogramGTStudy
 
 
 
@@ -449,7 +449,6 @@ Motion Correction
 ~~~~~~~~~~~~~~~~~
 .. automodule:: spikeinterface.sortingcomponents.motion
 
-    .. autoclass:: Motion
     .. autofunction:: estimate_motion
     .. autofunction:: interpolate_motion
     .. autofunction:: correct_motion_on_peaks

doc/conf.py

@@ -31,14 +31,12 @@
 folders =  [
     '../examples/tutorials/core/my_recording',
     '../examples/tutorials/core/my_sorting',
-    '../examples/tutorials/core/waveform_folder',
-    '../examples/tutorials/core/waveform_folder_parallel',
-    '../examples/tutorials/core/waveform_folder_sparse',
-    '../examples/tutorials/core/waveform_folder_sparse_direct',
-    '../examples/tutorials/core/waveform_folder2',
-    '../examples/tutorials/core/waveform_folder',
-    '../examples/tutorials/qualitymetrics/waveforms_mearec',
-    '../examples/tutorials/qualitymetrics/wfs_mearec',
+    '../examples/tutorials/core/analyzer_folder',
+    '../examples/tutorials/core/analyzer_some_units',
+    '../examples/tutorials/core/analyzer.zarr',
+    '../examples/tutorials/curation/my_folder',
+    '../examples/tutorials/qualitymetrics/curated_sorting',
+    '../examples/tutorials/qualitymetrics/clean_analyzer.zarr',
     '../examples/tutorials/widgets/waveforms_mearec',
 
 ]
@@ -101,7 +99,6 @@
     import sphinx_rtd_theme
 
     html_theme = "sphinx_rtd_theme"
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 except ImportError:
     print("RTD theme not installed, using default")
     html_theme = 'alabaster'
@@ -110,8 +107,9 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 # html_static_path = ['_static']
-
-html_favicon = "images/favicon-32x32.png"
+# html_css_files = ['custom.css']
+html_favicon = "images/logo.png"
+html_logo = "images/logo.png"
 
 
 from sphinx_gallery.sorting import ExplicitOrder

doc/how_to/load_your_data_into_sorting.rst

@@ -65,8 +65,8 @@ the requested unit_ids).
 
     # in this case we are making a monosegment sorting
     # we have four spikes that are spread among two neurons
-    my_sorting = NumpySorting.from_times_labels(
-        times_list=[
+    my_sorting = NumpySorting.from_samples_and_labels(
+        samples_list=[
             np.array([1000,12000,15000,22000])   # Note these are samples/frames not times in seconds
             ],
         labels_list=[
@@ -120,7 +120,7 @@ Loading multisegment data into a :code:`Sorting`
 One of the great advantages of SpikeInterface :code:`Sorting` objects is that they can also handle
 multisegment recordings and sortings (e.g. you have a baseline, stimulus, post-stimulus). The
 exact same machinery can be used to generate your sorting, but in this case we do a list of arrays instead of
-a single list. Let's go through one example for using :code:`from_times_labels`:
+a single list. Let's go through one example for using :code:`from_samples_and_labels`:
 
 .. code-block:: python
 
@@ -130,8 +130,8 @@ a single list. Let's go through one example for using :code:`from_times_labels`:
     # in this case we are making three-segment sorting
     # we have four spikes that are spread among two neurons
     # in each segment
-    my_sorting = NumpySorting.from_times_labels(
-        times_list=[
+    my_sorting = NumpySorting.from_samples_and_labels(
+        samples_list=[
             np.array([1000,12000,15000,22000]),
             np.array([30000,33000, 41000, 47000]),
             np.array([50000,53000,64000,70000]),

doc/index.rst

@@ -2,11 +2,6 @@ Welcome to SpikeInterface's documentation!
 ==========================================
 
 
-.. image:: images/logo.png
-  :scale: 100 %
-  :align: center
-
-
 SpikeInterface is a Python module to analyze extracellular electrophysiology data.
 
 With a few lines of code, SpikeInterface enables you to load and pre-process the recording, run several

doc/modules/comparison.rst

@@ -26,7 +26,7 @@ For spike train comparison, there are three use cases:
 
 A ground-truth dataset can be a paired recording, in which a neuron is recorded both extracellularly and with
 a patch or juxtacellular electrode (either **in vitro** or **in vivo**), or it can be a simulated dataset
-(**in silico**) using spiking activity simulators such as `MEArec`_.
+(**in silico**) using spiking activity simulators such as `MEArec <https://github.com/SpikeInterface/MEArec>`_.
 
 The comparison to ground-truth datasets is useful to benchmark spike sorting algorithms.
 

doc/modules/core.rst

@@ -711,8 +711,13 @@ In this example, we create a recording and a sorting object from numpy objects:
         spike_trains += spike_trains_i
         labels += labels_i
 
-    sorting_memory = NumpySorting.from_times_labels(times=spike_trains, labels=labels,
-                                                    sampling_frequency=sampling_frequency)
+    # construct a mono-segment
+    samples_list = [np.array(spike_trains)]
+    labels_list = [np.array(labels)]
+
+    sorting_memory = NumpySorting.from_samples_and_labels(
+        samples_list=samples_list, labels_list=labels_list, sampling_frequency=sampling_frequency
+    )
 
 
 Any sorting object can be transformed into a :py:class:`~spikeinterface.core.NumpySorting` or

doc/modules/curation.rst

@@ -120,31 +120,31 @@ the unit (among the redundant ones), with a better template alignment.
 Auto-merging units
 ^^^^^^^^^^^^^^^^^^
 
-The :py:func:`~spikeinterface.curation.get_potential_auto_merge` function returns a list of potential merges.
+The :py:func:`~spikeinterface.curation.compute_merge_unit_groups` function returns a list of potential merges.
 The list of potential merges can be then applied to the sorting output.
-:py:func:`~spikeinterface.curation.get_potential_auto_merge` has many internal tricks and steps to identify potential
+:py:func:`~spikeinterface.curation.compute_merge_unit_groups` has many internal tricks and steps to identify potential
 merges. It offers multiple "presets" and the flexibility to apply individual steps, with different parameters.
 **Read the function documentation carefully and do not apply it blindly!**
 
 
 .. code-block:: python
 
     from spikeinterface import create_sorting_analyzer
-    from spikeinterface.curation import get_potential_auto_merge
+    from spikeinterface.curation import compute_merge_unit_groups
 
     analyzer = create_sorting_analyzer(sorting=sorting, recording=recording)
 
     # some extensions are required
     analyzer.compute(["random_spikes", "templates", "template_similarity", "correlograms"])
 
     # merges is a list of unit pairs, with unit_ids to be merged.
-    merge_unit_pairs = get_potential_auto_merge(
+    merge_unit_pairs = compute_merge_unit_groups(
         analyzer=analyzer,
         preset="similarity_correlograms",
     )
     # with resolve_graph=True, merges_resolved is a list of merge groups,
     # which can contain more than two units
-    merge_unit_groups = get_potential_auto_merge(
+    merge_unit_groups = compute_merge_unit_groups(
         analyzer=analyzer,
         preset="similarity_correlograms",
         resolve_graph=True
@@ -153,6 +153,44 @@ merges. It offers multiple "presets" and the flexibility to apply individual ste
     # here we apply the merges
     analyzer_merged = analyzer.merge_units(merge_unit_groups=merge_unit_groups)
 
+There is also the convenient :py:func:`~spikeinterface.curation.auto_merge_units` function that combines the
+:py:func:`~spikeinterface.curation.compute_merge_unit_groups` and :py:func:`~spikeinterface.core.SortingAnalyzer.merge_units` functions.
+This is a high level function that allows you to apply either one or several presets/lists of steps in one go. For example, let's
+assume you want to apply the "x_contamination" preset, but iteratively and with slightly different parameters: first,
+you want to focus on the templates that are very similar, according to their template similarities, before
+considering those that might be more distant. Such a greedy and iterative scheme has been proved to be less
+prone to wrong merges. To do so, you'll need to do the following:
+
+.. code-block:: python
+
+    from spikeinterface import create_sorting_analyzer
+    from spikeinterface.curation import auto_merge_units
+
+    analyzer = create_sorting_analyzer(sorting=sorting, recording=recording)
+
+    # some extensions are required
+    analyzer.compute(["random_spikes", "templates", "template_similarity", "correlograms"])
+    analyzer.compute("unit_locations", method="monopolar_triangulation")
+
+    template_diff_thresh = [0.05, 0.15, 0.25]
+    presets = ["x_contaminations"] * len(template_diff_thresh)
+    steps_params = [
+        {"template_similarity": {"template_diff_thresh": i}}
+        for i in template_diff_thresh
+    ]
+
+    analyzer_merged = auto_merge_units(
+        analyzer,
+        presets=presets,
+        steps_params=steps_params,
+        recursive=True,
+        **job_kwargs,
+    )
+
+The extra keyword ``recursive`` specifies that for each presets/sequences of steps, merges are performed
+until no further merges are possible. The ``job_kwargs`` are the parameters for the parallelization.
+**Be careful that the merges can not be reverted, so be sure to not erase your analyzer and create a new variable**
+
 
 Manual curation
 ---------------

doc/modules/index.rst

@@ -17,3 +17,4 @@ Modules documentation
     sortingcomponents
     motion_correction
     generation
+    benchmark

doc/modules/sorters.rst

@@ -474,8 +474,6 @@ Here is the list of external sorters accessible using the run_sorter wrapper:
 * **HDSort** :code:`run_sorter(sorter_name='hdsort')`
 * **YASS** :code:`run_sorter(sorter_name='yass')`
 
-Internal Sorters
-----------------
 
 Here a list of internal sorter based on `spikeinterface.sortingcomponents`; they are totally
 experimental for now:

examples/tutorials/core/plot_2_sorting_extractor.py

@@ -40,7 +40,7 @@
 ##############################################################################
 # And instantiate a :py:class:`~spikeinterface.core.NumpySorting` object:
 
-sorting = se.NumpySorting.from_times_labels([times0, times1], [labels0, labels1], sampling_frequency)
+sorting = se.NumpySorting.from_samples_and_labels([times0, times1], [labels0, labels1], sampling_frequency)
 print(sorting)
 
 ##############################################################################