refactor: cleanup save functions and add detailed docs

Author: alejoe91

src/spikeinterface/core/base.py

@@ -855,12 +855,6 @@ def save_to_memory(self, sharedmem=True, **save_kwargs) -> "BaseExtractor":
         warnings.warn("save_to_memory() should be save(format='memory')", FutureWarning)
         return self.save(format="memory", sharedmem=sharedmem, **save_kwargs)
 
-        # save_kwargs.pop("format", None)
-
-        # cached = self._save(format="memory", sharedmem=sharedmem, **save_kwargs)
-        # self.copy_metadata(cached)
-        # return cached
-
     def save(self):
         # Need to be implemented in Recording and Sorting
         raise NotImplementedError()
@@ -878,64 +872,18 @@ def save_to_folder(
 
         The 'new' way is :
           * recording.save(format='binary', folder=...)
-          * sorting.save(format='numpy_folder', folder=...)
+          * sorting.save(format='binary', folder=...)
         """
 
         warnings.warn(
             "save_to_folder() should be recording.save(format='binary') "
-            "or sorting.save(format='numpy_folder') "
+            "or sorting.save(format='binary') "
             "This ambiguous method should not be used anymore!!",
             FutureWarning,
         )
         # we keep the default format for recording and sorting like in old version
         return self.save(folder=folder, verbose=verbose, **save_kwargs)
 
-        # if folder is None:
-        #     cache_folder = get_global_tmp_folder()
-        #     if name is None:
-        #         name = "".join(random.choices(string.ascii_uppercase + string.digits, k=8))
-        #         folder = cache_folder / name
-        #         if verbose:
-        #             print(f"Use cache_folder={folder}")
-        #     else:
-        #         folder = cache_folder / name
-        #         if not is_set_global_tmp_folder():
-        #             if verbose:
-        #                 print(f"Use cache_folder={folder}")
-        # else:
-        #     folder = Path(folder)
-        # if overwrite and folder.is_dir():
-        #     import shutil
-
-        #     shutil.rmtree(folder)
-
-        # assert not folder.exists(), f"folder {folder} already exists, choose another name or use overwrite=True"
-        # folder.mkdir(parents=True, exist_ok=False)
-
-        # # dump provenance
-        # provenance_file_path = folder / f"provenance.json"
-        # if self.check_serializability("json"):
-        #     self.dump_to_json(file_path=provenance_file_path, relative_to=folder)
-        # elif self.check_serializability("pickle"):
-        #     provenance_file = folder / f"provenance.pkl"
-        #     self.dump_to_pickle(provenance_file, relative_to=folder)
-        # else:
-        #     warnings.warn("The extractor is not serializable to file. The provenance will not be saved.")
-
-        # # save data (done the subclass)
-        # self.save_metadata_to_folder(folder)
-        # cached = self._save(folder=folder, verbose=verbose, **save_kwargs)
-        # cached.load_metadata_from_folder(folder)
-
-        # # copy properties/
-        # self.copy_metadata(cached)
-
-        # # Dump the extractor to json file
-        # si_folder_path = folder / f"si_folder.json"
-        # cached.dump_to_json(file_path=si_folder_path, relative_to=folder)
-
-        # return cached
-
     def save_to_zarr(
         self,
         name=None,

src/spikeinterface/core/baserecording.py

@@ -320,20 +320,79 @@ def get_shape(self, segment_index: int | None = None) -> tuple[int, ...]:
 
     def save(self, format="binary", verbose: bool = False, **save_kwargs):
         """
-        TODO: each object.save should have extensive docstring with all the options and examples
+        Save a `BaseRecording` object to a specified format:
+
+        * "binary"
+        * "zarr"
+        * "memory"
+
+        Parameters
+        ----------
+        format : str, default: "binary"
+            The format to save the recording in. Options are:
+            - "binary": Saves the recording in binary format.
+            - "zarr": Saves the recording in Zarr format.
+            - "memory": Saves the recording in memory (shared memory or numpy array).
+        verbose : bool, default: False
+            If True, prints additional information during the save process.
+        **save_kwargs : dict
+            Additional keyword arguments specific to the chosen format.
+            All formats support job_kwargs for parallel processing
+            (see `si.get_global_job_kwargs()` for default values).
+
+            * "binary" format:
+                - folder : str or Path
+                    The folder where the binary files will be saved.
+                - overwrite : bool, default: False
+                    If True, existing files in the folder will be overwritten.
+                - dtype : str, optional
+                    The data type to use for saving the recording. If not provided, the recording's dtype
+                    will be used.
+            * "zarr" format:
+                - folder : str or Path
+                    The folder where the Zarr files will be saved.
+                - overwrite: bool, default: False
+                    If True, the folder is removed if it already exists
+                - storage_options: dict or None, default: None
+                    Storage options for zarr `store`. E.g., if "s3://" or "gcs://" they can provide authentication methods, etc.
+                    For cloud storage locations, this should not be None (in case of default values, use an empty dict)
+                - channel_chunk_size: int or None, default: None
+                    Channels per chunk (only for BaseRecording)
+                - compressor: numcodecs.Codec or None, default: None
+                    Global compressor. If None, Blosc-zstd, level 5, with bit shuffle is used
+                - filters: list[numcodecs.Codec] or None, default: None
+                    Global filters for zarr (global)
+                - compressor_by_dataset: dict or None, default: None
+                    Optional compressor per dataset:
+                        - traces
+                        - times
+                    If None, the global compressor is used
+                - filters_by_dataset: dict or None, default: None
+                    Optional filters per dataset:
+                        - traces
+                        - times
+                    If None, the global filters are used
+            * "memory" format:
+                - sharedmem : bool, default: True
+                    If True, the recording is saved in shared memory. If False, it is saved as
+                    a numpy array in memory.
+
+        Returns
+        -------
+        BaseRecording
+            The saved recording object in the specified format.
         """
         kwargs, job_kwargs = split_job_kwargs(save_kwargs)
 
-        # TODO: add overwrite option to binary/zarr save
-
         if format == "binary":
             if "folder" not in kwargs:
                 raise ValueError("Missing folder in recording.save(folder='...')")
 
             from .binaryfolder import BinaryFolderRecording
 
+            folder = kwargs.pop("folder")
             cached = BinaryFolderRecording.write_recording(
-                self, folder=kwargs["folder"], dtype=kwargs.get("dtype", None), **job_kwargs
+                self, folder_path=folder, verbose=verbose, **kwargs, **job_kwargs
             )
 
         elif format == "memory":
@@ -348,49 +407,22 @@ def save(self, format="binary", verbose: bool = False, **save_kwargs):
 
                 cached = NumpyRecording.from_recording(self, with_metadata=True, with_time_vector=True, **job_kwargs)
 
-            # self.copy_metadata(cached)
-
-            # # timestamps are not saved in memory, so we have to set them explicitly
-            # for segment_index in range(self.get_num_segments()):
-            #     if self.has_time_vector(segment_index):
-            #         # the use of get_times is preferred since timestamps are converted to array
-            #         time_vector = self.get_times(segment_index=segment_index)
-            #         cached.set_times(time_vector, segment_index=segment_index)
-
         elif format == "zarr":
             if "folder" not in kwargs:
                 raise ValueError("Missing folder in recording.save(folder='...')")
+            folder_path = kwargs.pop("folder")
 
             from .zarrextractors import ZarrRecordingExtractor
 
-            folder_path = kwargs["folder"]
-            if isinstance(folder_path, Path) and folder_path.suffix != "zarr":
-                # automatically add the zarr suffix
-                folder_path = folder_path.with_suffix(".zarr")
-
-            storage_options = kwargs.pop("storage_options", None)
-            ZarrRecordingExtractor.write_recording(
-                self, folder_path, storage_options, verbose=verbose, **kwargs, **job_kwargs
+            cached = ZarrRecordingExtractor.write_recording(
+                self, folder_path=folder_path, verbose=verbose, **kwargs, **job_kwargs
             )
-            cached = ZarrRecordingExtractor(folder_path, storage_options)
-            # timestamps are saved and restored in zarr, so no need to set them explicitly
 
         else:
             raise ValueError(f"format {format} not supported")
 
         return cached
 
-    def _extra_metadata_from_folder(self, folder):
-        # load probe
-        super()._extra_metadata_from_folder(folder)
-
-        # load time vector if any
-        for segment_index, rs in enumerate(self.segments):
-            time_file = folder / f"times_cached_seg{segment_index}.npy"
-            if time_file.is_file():
-                time_vector = np.load(time_file, mmap_mode="r")
-                rs._time_vector = time_vector
-
     def select_channels(self, channel_ids: list | np.ndarray | tuple) -> "BaseRecording":
         """
         Returns a new recording object with a subset of channels.

src/spikeinterface/core/baserecordingsnippets.py

@@ -320,31 +320,6 @@ def _extra_metadata_copy(self, other):
         if self._probegroup is not None:
             other._probegroup = self._probegroup.copy()
 
-    def _extra_metadata_from_folder(self, folder):
-        # load probe from folder
-        # Note: we don't need any fix for legacy probegroups, since the
-        # set_probegroup() method will handle the device_channel_indices
-        # sorting and global contact order
-        folder = Path(folder)
-        probe_file = folder / "probegroup.json"
-        legacy_probe_file = folder / "probe.json"
-        if probe_file.is_file():
-            probegroup = read_probeinterface(probe_file)
-            self.set_probegroup(probegroup)
-        elif legacy_probe_file.is_file():
-            probegroup = read_probeinterface(legacy_probe_file)
-            self.set_probegroup(probegroup)
-
-        # remove "contact_vector" property if present as it is not needed anymore
-        if "contact_vector" in self.get_property_keys():
-            self.delete_property("contact_vector")
-
-    # def _extra_metadata_to_folder(self, folder):
-    #     # save probe
-    #     if self.has_probe():
-    #         probegroup = self.get_probegroup()
-    #         write_probeinterface(folder / "probegroup.json", probegroup)
-
     def _extra_metadata_from_dict(self, dump_dict):
         # load probe and handle backward-compatibility with legacy "contact_vector"/"location" property
         if "probegroup" in dump_dict:

src/spikeinterface/core/basesnippets.py

@@ -1,15 +1,12 @@
-from .base import BaseSegment
-from .baserecordingsnippets import BaseRecordingSnippets
 import numpy as np
 from warnings import warn
 
 from copy import deepcopy
 
 from pathlib import Path
 
-from .core_tools import save_properties_to_binary_folder
-
-# snippets segments?
+from .base import BaseSegment
+from .baserecordingsnippets import BaseRecordingSnippets
 
 
 class BaseSnippets(BaseRecordingSnippets):
@@ -21,6 +18,12 @@ class BaseSnippets(BaseRecordingSnippets):
     _main_features = []
 
     def __init__(self, sampling_frequency: float, nbefore: int | None, snippet_len: int, channel_ids: list, dtype):
+        warn(
+            "`BaseSnippets` is deprecated and will be removed in version 0.106.0."
+            "Only continuous recordings with `BaseRecording` will be supported.",
+            FutureWarning,
+            stacklevel=2,
+        )
         BaseRecordingSnippets.__init__(
             self, channel_ids=channel_ids, sampling_frequency=sampling_frequency, dtype=dtype
         )
@@ -213,9 +216,11 @@ def _select_segments(self, segment_indices):
 
     def save(self, format="npy", **save_kwargs):
         """
-        At the moment only "npy" and "memory" avaiable:
-        """
+        Save a `BaseSnippets` object to a specified format:
 
+        * "npy"
+        * "memory"
+        """
         if format == "npy":
             from spikeinterface.core.npyfoldersnippets import NpyFolderSnippets
 
@@ -240,14 +245,12 @@ def save(self, format="npy", **save_kwargs):
                 nbefore=self.nbefore,
                 channel_ids=self.channel_ids,
             )
-
+            if self.has_probe():
+                probegroup = self.get_probegroup()
+                cached.set_probegroup(probegroup)
         else:
             raise ValueError(f"format {format} not supported")
 
-        if self.has_probe():
-            probegroup = self.get_probegroup()
-            cached.set_probegroup(probegroup)
-
         return cached
 
     def get_times(self):