MOre docstrings

alejoe91 · alejoe91 · commit 90cb2b12e6d3 · 2024-07-09T13:18:17.000+02:00
diff --git a/src/spikeinterface/core/generate.py b/src/spikeinterface/core/generate.py
@@ -103,11 +103,11 @@ def generate_sorting(
     Parameters
     ----------
     num_units : int, default: 5
-        Number of units
+        Number of units.
     sampling_frequency : float, default: 30000.0
-        The sampling frequency
+        The sampling frequency.
     durations : list, default: [10.325, 3.5]
-        Duration of each segment in s
+        Duration of each segment in s.
     firing_rates : float, default: 3.0
         The firing rate of each unit (in Hz).
     empty_units : list, default: None
@@ -123,12 +123,12 @@ def generate_sorting(
     border_size_samples : int, default: 20
         The size of the border in samples to add border spikes.
     seed : int, default: None
-        The random seed
+        The random seed.
 
     Returns
     -------
     sorting : NumpySorting
-        The sorting object
+        The sorting object.
     """
     seed = _ensure_seed(seed)
     rng = np.random.default_rng(seed)
@@ -187,19 +187,19 @@ def add_synchrony_to_sorting(sorting, sync_event_ratio=0.3, seed=None):
     Parameters
     ----------
     sorting : BaseSorting
-        The sorting object
+        The sorting object.
     sync_event_ratio : float
         The ratio of added synchronous spikes with respect to the total number of spikes.
         E.g., 0.5 means that the final sorting will have 1.5 times number of spikes, and all the extra
         spikes are synchronous (same sample_index), but on different units (not duplicates).
     seed : int, default: None
-        The random seed
+        The random seed.
 
 
     Returns
     -------
     sorting : TransformSorting
-        The sorting object, keeping track of added spikes
+        The sorting object, keeping track of added spikes.
 
     """
     rng = np.random.default_rng(seed)
@@ -249,18 +249,18 @@ def generate_sorting_to_inject(
     Parameters
     ----------
     sorting : BaseSorting
-        The sorting object
+        The sorting object.
     num_samples: list of size num_segments.
         The number of samples in all the segments of the sorting, to generate spike times
-        covering entire the entire duration of the segments
+        covering entire the entire duration of the segments.
     max_injected_per_unit: int, default 1000
-        The maximal number of spikes injected per units
+        The maximal number of spikes injected per units.
     injected_rate: float, default 0.05
-        The rate at which spikes are injected
+        The rate at which spikes are injected.
     refractory_period_ms: float, default 1.5
-        The refractory period that should not be violated while injecting new spikes
+        The refractory period that should not be violated while injecting new spikes.
     seed: int, default None
-        The random seed
+        The random seed.
 
     Returns
     -------
@@ -312,22 +312,22 @@ class TransformSorting(BaseSorting):
     Parameters
     ----------
     sorting : BaseSorting
-        The sorting object
+        The sorting object.
     added_spikes_existing_units : np.array (spike_vector)
-        The spikes that should be added to the sorting object, for existing units
+        The spikes that should be added to the sorting object, for existing units.
     added_spikes_new_units: np.array (spike_vector)
-        The spikes that should be added to the sorting object, for new units
+        The spikes that should be added to the sorting object, for new units.
     new_units_ids: list
-        The unit_ids that should be added if spikes for new units are added
+        The unit_ids that should be added if spikes for new units are added.
     refractory_period_ms : float, default None
         The refractory period violation to prevent duplicates and/or unphysiological addition
         of spikes. Any spike times in added_spikes violating the refractory period will be
-        discarded
+        discarded.
 
     Returns
     -------
     sorting : TransformSorting
-        The sorting object with the added spikes and/or units
+        The sorting object with the added spikes and/or units.
     """
 
     def __init__(
@@ -428,12 +428,14 @@ def add_from_sorting(sorting1: BaseSorting, sorting2: BaseSorting, refractory_pe
 
         Parameters
         ----------
-        sorting1: the first sorting
-        sorting2: the second sorting
+        sorting1: BaseSorting
+            The first sorting.
+        sorting2: BaseSorting
+            The second sorting.
         refractory_period_ms : float, default None
             The refractory period violation to prevent duplicates and/or unphysiological addition
             of spikes. Any spike times in added_spikes violating the refractory period will be
-            discarded
+            discarded.
         """
         assert (
             sorting1.get_sampling_frequency() == sorting2.get_sampling_frequency()
@@ -492,12 +494,14 @@ def add_from_unit_dict(
         Parameters
         ----------
 
-        sorting1: the first sorting
+        sorting1: BaseSorting
+            The first sorting
         dict_list: list of dict
+            A list of dict with unit_ids as keys and spike times as values.
         refractory_period_ms : float, default None
             The refractory period violation to prevent duplicates and/or unphysiological addition
             of spikes. Any spike times in added_spikes violating the refractory period will be
-            discarded
+            discarded.
         """
         sorting2 = NumpySorting.from_unit_dict(units_dict_list, sorting1.get_sampling_frequency())
         sorting = TransformSorting.add_from_sorting(sorting1, sorting2, refractory_period_ms)
@@ -515,18 +519,19 @@ def from_times_labels(
 
         Parameters
         ----------
-        sorting1: the first sorting
+        sorting1: BaseSorting
+            The first sorting
         times_list: list of array (or array)
-            An array of spike times (in frames)
+            An array of spike times (in frames).
         labels_list: list of array (or array)
-            An array of spike labels corresponding to the given times
+            An array of spike labels corresponding to the given times.
         unit_ids: list or None, default: None
             The explicit list of unit_ids that should be extracted from labels_list
-            If None, then it will be np.unique(labels_list)
+            If None, then it will be np.unique(labels_list).
         refractory_period_ms : float, default None
             The refractory period violation to prevent duplicates and/or unphysiological addition
             of spikes. Any spike times in added_spikes violating the refractory period will be
-            discarded
+            discarded.
         """
 
         sorting2 = NumpySorting.from_times_labels(times_list, labels_list, sampling_frequency, unit_ids)
@@ -556,6 +561,16 @@ def clean_refractory_period(self):
 
 
 def create_sorting_npz(num_seg, file_path):
+    """
+    Create a NPZ sorting file.
+
+    Parameters
+    ----------
+    num_seg : int
+        The number of segments.
+    file_path : str | Path
+        The file path to save the NPZ file.
+    """
     # create a NPZ sorting file
     d = {}
     d["unit_ids"] = np.array([0, 1, 2], dtype="int64")
@@ -674,18 +689,18 @@ def synthesize_poisson_spike_vector(
     Parameters
     ----------
     num_units : int, default: 20
-        Number of neuronal units to simulate
+        Number of neuronal units to simulate.
     sampling_frequency : float, default: 30000.0
-        Sampling frequency in Hz
+        Sampling frequency in Hz.
     duration : float, default: 60.0
-        Duration of the simulation in seconds
+        Duration of the simulation in seconds.
     refractory_period_ms : float, default: 4.0
-        Refractory period between spikes in milliseconds
+        Refractory period between spikes in milliseconds.
     firing_rates : float or array_like or tuple, default: 3.0
         Firing rate(s) in Hz. Can be a single value for all units or an array of firing rates with
-        each element being the firing rate for one unit
+        each element being the firing rate for one unit.
     seed : int, default: 0
-        Seed for random number generator
+        Seed for random number generator.
 
     Returns
     -------
@@ -779,27 +794,27 @@ def synthesize_random_firings(
     Parameters
     ----------
     num_units : int
-        number of units
+        Number of units.
     sampling_frequency : float
-        sampling rate
+        Sampling rate.
     duration : float
-        duration of the segment in seconds
+        Duration of the segment in seconds.
     refractory_period_ms: float
-        refractory_period in ms
+        Refractory period in ms.
     firing_rates: float or list[float]
         The firing rate of each unit (in Hz).
         If float, all units will have the same firing rate.
     add_shift_shuffle: bool, default: False
         Optionally add a small shuffle on half of the spikes to make the autocorrelogram less flat.
     seed: int, default: None
-        seed for the generator
+        Seed for the generator.
 
     Returns
     -------
-    times:
-        Concatenated and sorted times vector
-    labels:
-        Concatenated and sorted label vector
+    times: np.array
+        Concatenated and sorted times vector.
+    labels: np.array
+        Concatenated and sorted label vector.
 
     """
 
@@ -883,11 +898,11 @@ def inject_some_duplicate_units(sorting, num=4, max_shift=5, ratio=None, seed=No
     Parameters
     ----------
     sorting :
-        Original sorting
+        Original sorting.
     num : int
-        Number of injected units
+        Number of injected units.
     max_shift : int
-        range of the shift in sample
+        range of the shift in sample.
     ratio: float
         Proportion of original spike in the injected units.
 
@@ -938,8 +953,27 @@ def inject_some_duplicate_units(sorting, num=4, max_shift=5, ratio=None, seed=No
 
 
 def inject_some_split_units(sorting, split_ids: list, num_split=2, output_ids=False, seed=None):
-    """ """
+    """
+    Inject some split units in a sorting.
 
+    Parameters
+    ----------
+    sorting : BaseSorting
+        Original sorting.
+    split_ids : list
+        List of unit_ids to split.
+    num_split : int, default: 2
+        Number of split units.
+    output_ids : bool, default: False
+        If True, return the new unit_ids.
+    seed : int, default: None
+        Random seed.
+
+    Returns
+    -------
+    sorting_with_split : NumpySorting
+        A sorting with split units.
+    """
     unit_ids = sorting.unit_ids
     assert unit_ids.dtype.kind == "i"
 
@@ -989,7 +1023,7 @@ def synthetize_spike_train_bad_isi(duration, baseline_rate, num_violations, viol
     num_violations : int
         Number of contaminating spikes.
     violation_delta : float, default: 1e-5
-        Temporal offset of contaminating spikes (in seconds)
+        Temporal offset of contaminating spikes (in seconds).
 
     Returns
     -------
@@ -1246,7 +1280,7 @@ def generate_recording_by_size(
     num_channels: int
         Number of channels.
     seed : int, default: None
-        The seed for np.random.default_rng
+        The seed for np.random.default_rng.
 
     Returns
     -------
@@ -1646,7 +1680,7 @@ class InjectTemplatesRecording(BaseRecording):
             * (num_units, num_samples, num_channels): standard case
             * (num_units, num_samples, num_channels, upsample_factor): case with oversample template to introduce sampling jitter.
     nbefore: list[int] | int | None, default: None
-        Where is the center of the template for each unit?
+        The number of samples before the peak of the template to align the spike.
         If None, will default to the highest peak.
     amplitude_factor: list[float] | float | None, default: None
         The amplitude of each spike for each unit.
@@ -1661,7 +1695,7 @@ class InjectTemplatesRecording(BaseRecording):
         You can use int for mono-segment objects.
     upsample_vector: np.array or None, default: None.
         When templates is 4d we can simulate a jitter.
-        Optional the upsample_vector is the jitter index with a number per spike in range 0-templates.sahpe[3]
+        Optional the upsample_vector is the jitter index with a number per spike in range 0-templates.shape[3].
 
     Returns
     -------
