Merge branch 'main' into sc2_recording_slices

doc/development/development.rst

@@ -213,6 +213,25 @@ We use Sphinx to build the documentation. To build the documentation locally, yo
 
 This will build the documentation in the :code:`doc/_build/html` folder. You can open the :code:`index.html` file in your browser to see the documentation.
 
+Adding new documentation
+------------------------
+
+Documentation can be added as a
+`sphinx-gallery <https://sphinx-gallery.github.io/stable/index.html>`_
+python file ('tutorials')
+or a
+`sphinx rst <https://sphinx-tutorial.readthedocs.io/step-1/>`_
+file (all other sections).
+
+To add a new tutorial, add your ``.py`` file to ``spikeinterface/examples``.
+Then, update the ``spikeinterface/doc/tutorials_custom_index.rst`` file
+to make a new card linking to the page and an optional image. See
+``tutorials_custom_index.rst`` header for more information.
+
+For other sections, write your documentation in ``.rst`` format and add
+the page to the appropriate ``index.rst`` file found in the relevant
+folder (e.g. ``how_to/index.rst``).
+
 How to run code coverage locally
 --------------------------------
 To run code coverage locally, you can use the following command:

doc/index.rst

@@ -51,7 +51,7 @@ SpikeInterface is made of several modules to deal with different aspects of the
 
     overview
     get_started/index
-    tutorials/index
+    tutorials_custom_index
     how_to/index
     modules/index
     api

doc/tutorials_custom_index.rst

@@ -0,0 +1,196 @@
+.. This page provides a custom index to the 'Tutorials' page, rather than the default sphinx-gallery
+.. generated page. The benefits of this are flexibility in design and inclusion of non-sphinx files in the index.
+..
+.. To update this index with a new documentation page
+.. 1) Copy the grid-item-card and associated ".. raw:: html" section.
+.. 2) change :link: to a link to your page. If this is an `.rst` file, point to the rst file directly.
+..    If it is a sphinx-gallery generated file, format the path as separated by underscore and prefix `sphx_glr`,
+..    pointing to the .py file. e.g. `tutorials/my/page.py` -> `sphx_glr_tutorials_my_page.py
+.. 3) Change :img-top: to point to the thumbnail image of your choosing. You can point to images generated
+..    in the sphinx gallery page if you wish.
+.. 4) In the `html` section, change the `default-title` to your pages title and `hover-content` to the subtitle.
+
+:orphan:
+
+Tutorials
+============
+
+Longer form tutorials about using SpikeInterface. Many of these are downloadable
+as notebooks or Python scripts so that you can "code along" with the tutorials.
+
+If you're new to SpikeInterface, we recommend trying out the
+:ref:`get_started/quickstart:Quickstart tutorial` first.
+
+Updating from legacy
+--------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorials/waveform_extractor_to_sorting_analyzer
+
+Core tutorials
+--------------
+
+These tutorials focus on the :py:mod:`spikeinterface.core` module.
+
+.. grid:: 1 2 2 3
+   :gutter: 2
+
+   .. grid-item-card:: Recording objects
+      :link-type: ref
+      :link: sphx_glr_tutorials_core_plot_1_recording_extractor.py
+      :img-top: /tutorials/core/images/thumb/sphx_glr_plot_1_recording_extractor_thumb.png
+      :img-alt: Recording objects
+      :class-card: gallery-card
+      :text-align: center
+
+   .. grid-item-card:: Sorting objects
+      :link-type: ref
+      :link: sphx_glr_tutorials_core_plot_2_sorting_extractor.py
+      :img-top: /tutorials/core/images/thumb/sphx_glr_plot_2_sorting_extractor_thumb.png
+      :img-alt: Sorting objects
+      :class-card: gallery-card
+      :text-align: center
+
+   .. grid-item-card:: Handling probe information
+      :link-type: ref
+      :link: sphx_glr_tutorials_core_plot_3_handle_probe_info.py
+      :img-top: /tutorials/core/images/thumb/sphx_glr_plot_3_handle_probe_info_thumb.png
+      :img-alt: Handling probe information
+      :class-card: gallery-card
+      :text-align: center
+
+   .. grid-item-card:: SortingAnalyzer
+      :link-type: ref
+      :link: sphx_glr_tutorials_core_plot_4_sorting_analyzer.py
+      :img-top: /tutorials/core/images/thumb/sphx_glr_plot_4_sorting_analyzer_thumb.png
+      :img-alt: SortingAnalyzer
+      :class-card: gallery-card
+      :text-align: center
+
+   .. grid-item-card:: Append and/or concatenate segments
+      :link-type: ref
+      :link: sphx_glr_tutorials_core_plot_5_append_concatenate_segments.py
+      :img-top: /tutorials/core/images/thumb/sphx_glr_plot_5_append_concatenate_segments_thumb.png
+      :img-alt: Append/Concatenate segments
+      :class-card: gallery-card
+      :text-align: center
+
+   .. grid-item-card:: Handle time information
+      :link-type: ref
+      :link: sphx_glr_tutorials_core_plot_6_handle_times.py
+      :img-top: /tutorials/core/images/thumb/sphx_glr_plot_6_handle_times_thumb.png
+      :img-alt: Handle time information
+      :class-card: gallery-card
+      :text-align: center
+
+Extractors tutorials
+--------------------
+
+The :py:mod:`spikeinterface.extractors` module is designed to load and save recorded and sorted data, and to handle probe information.
+
+.. grid:: 1 2 2 3
+   :gutter: 2
+
+   .. grid-item-card:: Read various formats
+      :link-type: ref
+      :link: sphx_glr_tutorials_extractors_plot_1_read_various_formats.py
+      :img-top: /tutorials/extractors/images/thumb/sphx_glr_plot_1_read_various_formats_thumb.png
+      :img-alt: Read various formats
+      :class-card: gallery-card
+      :text-align: center
+
+   .. grid-item-card:: Working with unscaled traces
+      :link-type: ref
+      :link: sphx_glr_tutorials_extractors_plot_2_working_with_unscaled_traces.py
+      :img-top: /tutorials/extractors/images/thumb/sphx_glr_plot_2_working_with_unscaled_traces_thumb.png
+      :img-alt: Unscaled traces
+      :class-card: gallery-card
+      :text-align: center
+
+Quality metrics tutorial
+------------------------
+
+The :code:`spikeinterface.qualitymetrics` module allows users to compute various quality metrics to assess the goodness of a spike sorting output.
+
+.. grid:: 1 2 2 3
+   :gutter: 2
+
+   .. grid-item-card:: Quality Metrics
+      :link-type: ref
+      :link: sphx_glr_tutorials_qualitymetrics_plot_3_quality_mertics.py
+      :img-top: /tutorials/qualitymetrics/images/thumb/sphx_glr_plot_3_quality_mertics_thumb.png
+      :img-alt: Quality Metrics
+      :class-card: gallery-card
+      :text-align: center
+
+   .. grid-item-card:: Curation Tutorial
+      :link-type: ref
+      :link: sphx_glr_tutorials_qualitymetrics_plot_4_curation.py
+      :img-top: /tutorials/qualitymetrics/images/thumb/sphx_glr_plot_4_curation_thumb.png
+      :img-alt: Curation Tutorial
+      :class-card: gallery-card
+      :text-align: center
+
+Comparison tutorial
+-------------------
+
+The :code:`spikeinterface.comparison` module allows you to compare sorter outputs or benchmark against ground truth.
+
+.. grid:: 1 2 2 3
+   :gutter: 2
+
+   .. grid-item-card:: Sorter Comparison
+      :link-type: ref
+      :link: sphx_glr_tutorials_comparison_plot_5_comparison_sorter_weaknesses.py
+      :img-top: /tutorials/comparison/images/thumb/sphx_glr_plot_5_comparison_sorter_weaknesses_thumb.png
+      :img-alt: Sorter Comparison
+      :class-card: gallery-card
+      :text-align: center
+
+Widgets tutorials
+-----------------
+
+The :code:`widgets` module contains several plotting routines (widgets) for visualizing recordings, sorting data, probe layout, and more.
+
+.. grid:: 1 2 2 3
+   :gutter: 2
+
+   .. grid-item-card:: RecordingExtractor Widgets
+      :link-type: ref
+      :link: sphx_glr_tutorials_widgets_plot_1_rec_gallery.py
+      :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_1_rec_gallery_thumb.png
+      :img-alt: Recording Widgets
+      :class-card: gallery-card
+      :text-align: center
+
+   .. grid-item-card:: SortingExtractor Widgets
+      :link-type: ref
+      :link: sphx_glr_tutorials_widgets_plot_2_sort_gallery.py
+      :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_2_sort_gallery_thumb.png
+      :img-alt: Sorting Widgets
+      :class-card: gallery-card
+      :text-align: center
+
+   .. grid-item-card:: Waveforms Widgets
+      :link-type: ref
+      :link: sphx_glr_tutorials_widgets_plot_3_waveforms_gallery.py
+      :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_3_waveforms_gallery_thumb.png
+      :img-alt: Waveforms Widgets
+      :class-card: gallery-card
+      :text-align: center
+
+   .. grid-item-card:: Peaks Widgets
+      :link-type: ref
+      :link: sphx_glr_tutorials_widgets_plot_4_peaks_gallery.py
+      :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_4_peaks_gallery_thumb.png
+      :img-alt: Peaks Widgets
+      :class-card: gallery-card
+      :text-align: center
+
+Download All Examples
+---------------------
+
+- :download:`Download all examples in Python source code </tutorials/tutorials_python.zip>`
+- :download:`Download all examples in Jupyter notebooks </tutorials/tutorials_jupyter.zip>`

src/spikeinterface/core/baserecording.py

@@ -509,6 +509,35 @@ def reset_times(self):
             rs.t_start = None
             rs.sampling_frequency = self.sampling_frequency
 
+    def shift_times(self, shift: int | float, segment_index: int | None = None) -> None:
+        """
+        Shift all times by a scalar value.
+
+        Parameters
+        ----------
+        shift : int | float
+            The shift to apply. If positive, times will be increased by `shift`.
+            e.g. shifting by 1 will be like the recording started 1 second later.
+            If negative, the start time will be decreased i.e. as if the recording
+            started earlier.
+
+        segment_index : int | None
+            The segment on which to shift the times.
+            If `None`, all segments will be shifted.
+        """
+        if segment_index is None:
+            segments_to_shift = range(self.get_num_segments())
+        else:
+            segments_to_shift = (segment_index,)
+
+        for idx in segments_to_shift:
+            rs = self._recording_segments[idx]
+
+            if self.has_time_vector(segment_index=idx):
+                rs.time_vector += shift
+            else:
+                rs.t_start += shift
+
     def sample_index_to_time(self, sample_ind, segment_index=None):
         """
         Transform sample index into time in seconds

src/spikeinterface/core/tests/test_time_handling.py

@@ -15,7 +15,10 @@ class TestTimeHandling:
     is generated on the fly. Both time representations are tested here.
     """
 
-    # Fixtures #####
+    # #########################################################################
+    # Fixtures
+    # #########################################################################
+
     @pytest.fixture(scope="session")
     def time_vector_recording(self):
         """
@@ -95,7 +98,10 @@ def _get_fixture_data(self, request, fixture_name):
         raw_recording, times_recording, all_times = time_recording_fixture
         return (raw_recording, times_recording, all_times)
 
-    # Tests #####
+    # #########################################################################
+    # Tests
+    # #########################################################################
+
     def test_has_time_vector(self, time_vector_recording):
         """
         Test the `has_time_vector` function returns `False` before
@@ -305,7 +311,87 @@ def test_sorting_analyzer_get_durations_no_recording(self, time_vector_recording
 
         assert np.array_equal(sorting_analyzer.get_total_duration(), raw_recording.get_total_duration())
 
-    # Helpers ####
+    @pytest.mark.parametrize("fixture_name", ["time_vector_recording", "t_start_recording"])
+    @pytest.mark.parametrize("shift", [-123.456, 123.456])
+    def test_shift_time_all_segments(self, request, fixture_name, shift):
+        """
+        Shift the times in every segment using the `None` default, then
+        check that every segment of the recording is shifted as expected.
+        """
+        _, times_recording, all_times = self._get_fixture_data(request, fixture_name)
+
+        num_segments, orig_seg_data = self._store_all_times(times_recording)
+
+        times_recording.shift_times(shift)  # use default `segment_index=None`
+
+        for idx in range(num_segments):
+            assert np.allclose(
+                orig_seg_data[idx], times_recording.get_times(segment_index=idx) - shift, rtol=0, atol=1e-8
+            )
+
+    @pytest.mark.parametrize("fixture_name", ["time_vector_recording", "t_start_recording"])
+    @pytest.mark.parametrize("shift", [-123.456, 123.456])
+    def test_shift_times_different_segments(self, request, fixture_name, shift):
+        """
+        Shift each segment separately, and check the shifted segment only
+        is shifted as expected.
+        """
+        _, times_recording, all_times = self._get_fixture_data(request, fixture_name)
+
+        num_segments, orig_seg_data = self._store_all_times(times_recording)
+
+        # For each segment, shift the segment only and check the
+        # times are updated as expected.
+        for idx in range(num_segments):
+
+            scaler = idx + 2
+            times_recording.shift_times(shift * scaler, segment_index=idx)
+
+            assert np.allclose(
+                orig_seg_data[idx], times_recording.get_times(segment_index=idx) - shift * scaler, rtol=0, atol=1e-8
+            )
+
+            # Just do a little check that we are not
+            # accidentally changing some other segments,
+            # which should remain unchanged at this point in the loop.
+            if idx != num_segments - 1:
+                assert np.array_equal(orig_seg_data[idx + 1], times_recording.get_times(segment_index=idx + 1))
+
+    @pytest.mark.parametrize("fixture_name", ["time_vector_recording", "t_start_recording"])
+    def test_save_and_load_time_shift(self, request, fixture_name, tmp_path):
+        """
+        Save the shifted data and check the shift is propagated correctly.
+        """
+        _, times_recording, all_times = self._get_fixture_data(request, fixture_name)
+
+        shift = 100
+        times_recording.shift_times(shift=shift)
+
+        times_recording.save(folder=tmp_path / "my_file")
+
+        loaded_recording = si.load_extractor(tmp_path / "my_file")
+
+        for idx in range(times_recording.get_num_segments()):
+            assert np.array_equal(
+                times_recording.get_times(segment_index=idx), loaded_recording.get_times(segment_index=idx)
+            )
+
+    def _store_all_times(self, recording):
+        """
+        Convenience function to store original times of all segments to a dict.
+        """
+        num_segments = recording.get_num_segments()
+        seg_data = {}
+
+        for idx in range(num_segments):
+            seg_data[idx] = copy.deepcopy(recording.get_times(segment_index=idx))
+
+        return num_segments, seg_data
+
+    # #########################################################################
+    # Helpers
+    # #########################################################################
+
     def _check_times_match(self, recording, all_times):
         """
         For every segment in a recording, check the `get_times()`