Merge pull request #2950 from chrishalcrow/add_colon_spaces

Standardize colon spacing in docstrings

doc/development/development.rst

@@ -152,7 +152,7 @@ for providing parameters, however is a little different. The project prefers the
 
 .. code-block:: bash
 
-    parameter_name: type, default: default_value
+    parameter_name : type, default: default_value
 
 
 This allows users to quickly understand the type of data that should be input into a function as well as whether a default is supplied. A full example would be:
@@ -165,21 +165,22 @@ This allows users to quickly understand the type of data that should be input in
 
         Parameters
         ----------
-        param_a: dict
+        param_a : dict
             A dictionary containing the data
-        param_b: int, default: 5
+        param_b : int, default: 5
             A scaling factor to be applied to the data
-        param_c: "mean" | "median", default: "mean"
+        param_c : "mean" | "median", default: "mean"
             What to calculate on the data
 
         Returns
         -------
-        great_data: dict
+        great_data : dict
             A dictionary of the processed data
         """
 
 
-Note that in this example we demonstrate two other docstring conventions followed by SpikeInterface. First, that all string arguments should be presented
+There should be a space between each parameter and the colon following it. This is neccessary for using the `numpydoc validator <https://numpydoc.readthedocs.io/en/latest/validation.html>`_.
+In the above example we demonstrate two other docstring conventions followed by SpikeInterface. First, that all string arguments should be presented
 with double quotes. This is the same stylistic convention followed by Black and enforced by the pre-commit for the repo. Second, when a parameter is a
 string with a limited number of values (e.g. :code:`mean` and :code:`median`), rather than give the type a value of :code:`str`, please list the possible strings
 so that the user knows what the options are.

src/spikeinterface/comparison/collision.py

@@ -14,7 +14,7 @@ class CollisionGTComparison(GroundTruthComparison):
     This class needs maintenance and need a bit of refactoring.
 
 
-    collision_lag: float
+    collision_lag : float
         Collision lag in ms.
 
     """

src/spikeinterface/comparison/hybrid.py

@@ -26,32 +26,32 @@ class HybridUnitsRecording(InjectTemplatesRecording):
 
     Parameters
     ----------
-    parent_recording: BaseRecording
+    parent_recording : BaseRecording
         Existing recording to add on top of.
-    templates: np.ndarray[n_units, n_samples, n_channels]
+    templates : np.ndarray[n_units, n_samples, n_channels]
         Array containing the templates to inject for all the units.
-    injected_sorting: BaseSorting | None:
+    injected_sorting : BaseSorting | None:
         The sorting for the injected units.
         If None, will be generated using the following parameters.
-    nbefore: list[int] | int | None
+    nbefore : list[int] | int | None
         Where is the center of the template for each unit?
         If None, will default to the highest peak.
-    firing_rate: float
+    firing_rate : float
         The firing rate of the injected units (in Hz).
-    amplitude_factor: np.ndarray | None:
+    amplitude_factor : np.ndarray | None:
         The amplitude factor for each spike.
         If None, will be generated as a gaussian centered at 1.0 and with an std of amplitude_std.
-    amplitude_std: float
+    amplitude_std : float
         The standard deviation of the amplitude (centered at 1.0).
-    refractory_period_ms: float
+    refractory_period_ms : float
         The refractory period of the injected spike train (in ms).
-    injected_sorting_folder: str | Path | None
+    injected_sorting_folder : str | Path | None
         If given, the injected sorting is saved to this folder.
         It must be specified if injected_sorting is None or not serialisable to file.
 
     Returns
     -------
-    hybrid_units_recording: HybridUnitsRecording
+    hybrid_units_recording : HybridUnitsRecording
         The recording containing real and hybrid units.
     """
 
@@ -128,29 +128,29 @@ class HybridSpikesRecording(InjectTemplatesRecording):
 
     Parameters
     ----------
-    wvf_extractor: WaveformExtractor
+    wvf_extractor : WaveformExtractor
         The waveform extractor object of the existing recording.
-    injected_sorting: BaseSorting | None
+    injected_sorting : BaseSorting | None
         Additional spikes to inject.
         If None, will generate it.
-    max_injected_per_unit: int
+    max_injected_per_unit : int
         If injected_sorting=None, the max number of spikes per unit
         that is allowed to be injected.
-    unit_ids: list[int] | None
+    unit_ids : list[int] | None
         unit_ids to take in the wvf_extractor for spikes injection.
-    injected_rate: float
+    injected_rate : float
         If injected_sorting=None, the max fraction of spikes per
         unit that is allowed to be injected.
-    refractory_period_ms: float
+    refractory_period_ms : float
         If injected_sorting=None, the injected spikes need to respect
         this refractory period.
-    injected_sorting_folder: str | Path | None
+    injected_sorting_folder : str | Path | None
         If given, the injected sorting is saved to this folder.
         It must be specified if injected_sorting is None or not serializable to file.
 
     Returns
     -------
-    hybrid_spikes_recording: HybridSpikesRecording:
+    hybrid_spikes_recording : HybridSpikesRecording:
         The recording containing units with real and hybrid spikes.
     """
 

src/spikeinterface/comparison/multicomparisons.py

@@ -25,29 +25,29 @@ class MultiSortingComparison(BaseMultiComparison, MixinSpikeTrainComparison):
 
     Parameters
     ----------
-    sorting_list: list
+    sorting_list : list
         List of sorting extractor objects to be compared
-    name_list: list, default: None
+    name_list : list, default: None
         List of spike sorter names. If not given, sorters are named as "sorter0", "sorter1", "sorter2", etc.
-    delta_time: float, default: 0.4
+    delta_time : float, default: 0.4
         Number of ms to consider coincident spikes
-    match_score: float, default: 0.5
+    match_score : float, default: 0.5
         Minimum agreement score to match units
-    chance_score: float, default: 0.1
+    chance_score : float, default: 0.1
         Minimum agreement score to for a possible match
-    n_jobs: int, default: -1
+    n_jobs : int, default: -1
        Number of cores to use in parallel. Uses all available if -1
-    spiketrain_mode: "union" | "intersection", default: "union"
+    spiketrain_mode : "union" | "intersection", default: "union"
         Mode to extract agreement spike trains:
-            - "union": spike trains are the union between the spike trains of the best matching two sorters
-            - "intersection": spike trains are the intersection between the spike trains of the
+            - "union" : spike trains are the union between the spike trains of the best matching two sorters
+            - "intersection" : spike trains are the intersection between the spike trains of the
                best matching two sorters
-    verbose: bool, default: False
+    verbose : bool, default: False
         if True, output is verbose
 
     Returns
     -------
-    multi_sorting_comparison: MultiSortingComparison
+    multi_sorting_comparison : MultiSortingComparison
         MultiSortingComparison object with the multiple sorter comparison
     """
 
@@ -162,15 +162,15 @@ def get_agreement_sorting(self, minimum_agreement_count=1, minimum_agreement_cou
 
         Parameters
         ----------
-        minimum_agreement_count: int
+        minimum_agreement_count : int
             Minimum number of matches among sorters to include a unit.
-        minimum_agreement_count_only: bool
+        minimum_agreement_count_only : bool
             If True, only units with agreement == "minimum_matching" are included.
             If False, units with an agreement >= "minimum_matching" are included
 
         Returns
         -------
-        agreement_sorting: AgreementSortingExtractor
+        agreement_sorting : AgreementSortingExtractor
             The output AgreementSortingExtractor
         """
         assert minimum_agreement_count > 0, "'minimum_agreement_count' should be greater than 0"
@@ -309,20 +309,20 @@ class MultiTemplateComparison(BaseMultiComparison, MixinTemplateComparison):
 
     Parameters
     ----------
-    waveform_list: list
+    waveform_list : list
         List of waveform extractor objects to be compared
-    name_list: list, default: None
+    name_list : list, default: None
         List of session names. If not given, sorters are named as "sess0", "sess1", "sess2", etc.
-    match_score: float, default: 0.8
+    match_score : float, default: 0.8
         Minimum agreement score to match units
-    chance_score: float, default: 0.3
+    chance_score : float, default: 0.3
         Minimum agreement score to for a possible match
-    verbose: bool, default: False
+    verbose : bool, default: False
         if True, output is verbose
 
     Returns
     -------
-    multi_template_comparison: MultiTemplateComparison
+    multi_template_comparison : MultiTemplateComparison
         MultiTemplateComparison object with the multiple template comparisons
     """
 

src/spikeinterface/comparison/paircomparisons.py

@@ -112,28 +112,28 @@ class SymmetricSortingComparison(BasePairSorterComparison):
 
     Parameters
     ----------
-    sorting1: SortingExtractor
+    sorting1 : SortingExtractor
         The first sorting for the comparison
-    sorting2: SortingExtractor
+    sorting2 : SortingExtractor
         The second sorting for the comparison
-    sorting1_name: str, default: None
+    sorting1_name : str, default: None
         The name of sorter 1
-    sorting2_name: : str, default: None
+    sorting2_name : : str, default: None
         The name of sorter 2
-    delta_time: float, default: 0.4
+    delta_time : float, default: 0.4
         Number of ms to consider coincident spikes
-    match_score: float, default: 0.5
+    match_score : float, default: 0.5
         Minimum agreement score to match units
-    chance_score: float, default: 0.1
+    chance_score : float, default: 0.1
         Minimum agreement score to for a possible match
-    n_jobs: int, default: -1
+    n_jobs : int, default: -1
         Number of cores to use in parallel. Uses all available if -1
-    verbose: bool, default: False
+    verbose : bool, default: False
         If True, output is verbose
 
     Returns
     -------
-    sorting_comparison: SortingComparison
+    sorting_comparison : SortingComparison
         The SortingComparison object
     """
 
@@ -215,44 +215,44 @@ class GroundTruthComparison(BasePairSorterComparison):
 
     Parameters
     ----------
-    gt_sorting: SortingExtractor
+    gt_sorting : SortingExtractor
         The first sorting for the comparison
-    tested_sorting: SortingExtractor
+    tested_sorting : SortingExtractor
         The second sorting for the comparison
-    gt_name: str, default: None
+    gt_name : str, default: None
         The name of sorter 1
-    tested_name: : str, default: None
+    tested_name : : str, default: None
         The name of sorter 2
-    delta_time: float, default: 0.4
+    delta_time : float, default: 0.4
         Number of ms to consider coincident spikes
-    match_score: float, default: 0.5
+    match_score : float, default: 0.5
         Minimum agreement score to match units
-    chance_score: float, default: 0.1
+    chance_score : float, default: 0.1
         Minimum agreement score to for a possible match
-    redundant_score: float, default: 0.2
+    redundant_score : float, default: 0.2
         Agreement score above which units are redundant
-    overmerged_score: float, default: 0.2
+    overmerged_score : float, default: 0.2
         Agreement score above which units can be overmerged
-    well_detected_score: float, default: 0.8
+    well_detected_score : float, default: 0.8
         Agreement score above which units are well detected
-    exhaustive_gt: bool, default: False
+    exhaustive_gt : bool, default: False
         Tell if the ground true is "exhaustive" or not. In other world if the
         GT have all possible units. It allows more performance measurement.
         For instance, MEArec simulated dataset have exhaustive_gt=True
-    match_mode: "hungarian" | "best", default: "hungarian"
+    match_mode : "hungarian" | "best", default: "hungarian"
         The method to match units
-    n_jobs: int, default: -1
+    n_jobs : int, default: -1
         Number of cores to use in parallel. Uses all available if -1
-    compute_labels: bool, default: False
+    compute_labels : bool, default: False
         If True, labels are computed at instantiation
-    compute_misclassifications: bool, default: False
+    compute_misclassifications : bool, default: False
         If True, misclassifications are computed at instantiation
-    verbose: bool, default: False
+    verbose : bool, default: False
         If True, output is verbose
 
     Returns
     -------
-    sorting_comparison: SortingComparison
+    sorting_comparison : SortingComparison
         The SortingComparison object
     """
 
@@ -366,7 +366,7 @@ def get_confusion_matrix(self):
 
         Returns
         -------
-        confusion_matrix: pandas.DataFrame
+        confusion_matrix : pandas.DataFrame
             The confusion matrix
         """
         if self._confusion_matrix is None:
@@ -392,14 +392,14 @@ def get_performance(self, method="by_unit", output="pandas"):
 
         Parameters
         ----------
-        method: "by_unit" | "pooled_with_average", default: "by_unit"
+        method : "by_unit" | "pooled_with_average", default: "by_unit"
             The method to compute performance
-        output: "pandas" | "dict", default: "pandas"
+        output : "pandas" | "dict", default: "pandas"
             The output format
 
         Returns
         -------
-        perf: pandas dataframe/series (or dict)
+        perf : pandas dataframe/series (or dict)
             dataframe/series (based on "output") with performance entries
         """
         import pandas as pd
@@ -478,7 +478,7 @@ def get_well_detected_units(self, well_detected_score=None):
 
         Parameters
         ----------
-        well_detected_score: float, default: None
+        well_detected_score : float, default: None
             The agreement score above which tested units
             are counted as "well detected".
         """
@@ -514,7 +514,7 @@ def get_false_positive_units(self, redundant_score=None):
 
         Parameters
         ----------
-        redundant_score: float, default: None
+        redundant_score : float, default: None
             The agreement score below which tested units
             are counted as "false positive"" (and not "redundant").
         """
@@ -554,7 +554,7 @@ def get_redundant_units(self, redundant_score=None):
 
         Parameters
         ----------
-        redundant_score=None: float, default: None
+        redundant_score=None : float, default: None
             The agreement score above which tested units
             are counted as "redundant" (and not "false positive" ).
         """
@@ -589,7 +589,7 @@ def get_overmerged_units(self, overmerged_score=None):
 
         Parameters
         ----------
-        overmerged_score: float, default: None
+        overmerged_score : float, default: None
             Tested units with 2 or more agreement scores above "overmerged_score"
             are counted as "overmerged".
         """