Merge pull request #3016 from chrishalcrow/docstrings-preprocessing-u…

…pdate

Docstrings preprocessing update, fix PR01 and PR02

src/spikeinterface/preprocessing/astype.py

@@ -14,8 +14,20 @@ class AstypeRecording(BasePreprocessor):
 
     For recording with an unsigned dtype, please use the `unsigned_to_signed` preprocessing function.
 
-    If `round` is True, will round the values to the nearest integer.
-    If `round` is None, will round in the case of float to integer conversion.
+    Parameters
+    ----------
+    dtype : None | str | dtype, default: None
+        dtype of the output recording. If None, takes dtype from input `recording`.
+    recording : Recording
+        The recording extractor to be converted.
+    round : Bool | None, default: None
+        If True, will round the values to the nearest integer using `numpy.round`.
+        If None and dtype is an integer, will round floats to nearest integer.
+
+    Returns
+    -------
+    astype_recording : AstypeRecording
+        The converted recording extractor object
     """
 
     name = "astype"

src/spikeinterface/preprocessing/depth_order.py

@@ -12,7 +12,7 @@ class DepthOrderRecording(ChannelSliceRecording):
 
     Parameters
     ----------
-    recording : BaseRecording
+    parent_recording : BaseRecording
         The recording to re-order.
     channel_ids : list/array or None
         If given, a subset of channels to order locations for

src/spikeinterface/preprocessing/detect_bad_channels.py

@@ -57,29 +57,29 @@ def detect_bad_channels(
         The method to be used for bad channel detection
     std_mad_threshold : float, default: 5
         The standard deviation/mad multiplier threshold
-    psd_hf_threshold (coeherence+psd) : float, default: 0.02
-        An absolute threshold (uV^2/Hz) used as a cutoff for noise channels.
+    psd_hf_threshold : float, default: 0.02
+        For coherence+psd - an absolute threshold (uV^2/Hz) used as a cutoff for noise channels.
         Channels with average power at >80% Nyquist larger than this threshold
         will be labeled as noise
-    dead_channel_threshold (coeherence+psd) : float, default: -0.5
-        Threshold for channel coherence below which channels are labeled as dead
-    noisy_channel_threshold (coeherence+psd) : float, default: 1
+    dead_channel_threshold : float, default: -0.5
+        For coherence+psd - threshold for channel coherence below which channels are labeled as dead
+    noisy_channel_threshold : float, default: 1
         Threshold for channel coherence above which channels are labeled as noisy (together with psd condition)
-    outside_channel_threshold (coeherence+psd) : float, default: -0.75
-        Threshold for channel coherence above which channels at the edge of the recording are marked as outside
+    outside_channel_threshold : float, default: -0.75
+        For coherence+psd - threshold for channel coherence above which channels at the edge of the recording are marked as outside
         of the brain
-    outside_channels_location (coeherence+psd) : "top" | "bottom" | "both", default: "top"
-        Location of the outside channels. If "top", only the channels at the top of the probe can be
+    outside_channels_location : "top" | "bottom" | "both", default: "top"
+        For coherence+psd - location of the outside channels. If "top", only the channels at the top of the probe can be
         marked as outside channels. If "bottom", only the channels at the bottom of the probe can be
         marked as outside channels. If "both", both the channels at the top and bottom of the probe can be
         marked as outside channels
-    n_neighbors (coeherence+psd) : int, default: 11
-        Number of channel neighbors to compute median filter (needs to be odd)
-    nyquist_threshold (coeherence+psd) : float, default: 0.8
-        Frequency with respect to Nyquist (Fn=1) above which the mean of the PSD is calculated and compared
+    n_neighbors : int, default: 11
+        For coeherence+psd - number of channel neighbors to compute median filter (needs to be odd)
+    nyquist_threshold : float, default: 0.8
+        For coherence+psd - frequency with respect to Nyquist (Fn=1) above which the mean of the PSD is calculated and compared
         with psd_hf_threshold
-    direction (coeherence+psd) : "x" | "y" | "z", default: "y"
-        The depth dimension
+    direction : "x" | "y" | "z", default: "y"
+        For coherence+psd - the depth dimension
     highpass_filter_cutoff : float, default: 300
         If the recording is not filtered, the cutoff frequency of the highpass filter
     chunk_duration_s : float, default: 0.5

src/spikeinterface/preprocessing/filter.py

@@ -8,14 +8,16 @@
 from ..core import get_chunk_with_margin
 
 
-_common_filter_docs = """**filter_kwargs : keyword arguments for parallel processing:
-
-            * filter_order : order
-                The order of the filter
-            * filter_mode : "sos or "ba"
-                "sos" is bi quadratic and more stable than ab so thery are prefered.
-            * ftype : str
-                Filter type for iirdesign ("butter" / "cheby1" / ... all possible of scipy.signal.iirdesign)
+_common_filter_docs = """**filter_kwargs : dict
+        Certain keyword arguments for `scipy.signal` filters:
+        filter_order : order
+            The order of the filter
+        filter_mode :  "sos" | "ba", default: "sos"
+            Filter form of the filter coefficients:
+            - second-order sections ("sos")
+            - numerator/denominator : ("ba")
+        ftype : str, default: "butter"
+            Filter type for `scipy.signal.iirfilter` e.g. "butter", "cheby1".
     """
 
 
@@ -39,21 +41,25 @@ class FilterRecording(BasePreprocessor):
         Type of the filter
     margin_ms : float, default: 5.0
         Margin in ms on border to avoid border effect
-    filter_mode : "sos" | "ba", default: "sos"
-        Filter form of the filter coefficients:
-        - second-order sections ("sos")
-        - numerator/denominator : ("ba")
-    coef : array or None, default: None
+    coeff : array | None, default: None
         Filter coefficients in the filter_mode form.
     dtype : dtype or None, default: None
         The dtype of the returned traces. If None, the dtype of the parent recording is used
-    {}
+    add_reflect_padding : Bool, default False
+        If True, uses a left and right margin during calculation.
+    filter_order : order
+        The order of the filter for `scipy.signal.iirfilter`
+    filter_mode :  "sos" | "ba", default: "sos"
+        Filter form of the filter coefficients for `scipy.signal.iirfilter`:
+        - second-order sections ("sos")
+        - numerator/denominator : ("ba")
+    ftype : str, default: "butter"
+        Filter type for `scipy.signal.iirfilter` e.g. "butter", "cheby1".
 
     Returns
     -------
     filter_recording : FilterRecording
         The filtered recording extractor object
-
     """
 
     name = "filter"
@@ -179,6 +185,7 @@ class BandpassFilterRecording(FilterRecording):
     dtype : dtype or None
         The dtype of the returned traces. If None, the dtype of the parent recording is used
     {}
+
     Returns
     -------
     filter_recording : BandpassFilterRecording
@@ -213,6 +220,7 @@ class HighpassFilterRecording(FilterRecording):
     dtype : dtype or None
         The dtype of the returned traces. If None, the dtype of the parent recording is used
     {}
+
     Returns
     -------
     filter_recording : HighpassFilterRecording
@@ -240,7 +248,11 @@ class NotchFilterRecording(BasePreprocessor):
         The target frequency in Hz of the notch filter
     q : int
         The quality factor of the notch filter
-    {}
+    dtype : None | dtype, default: None
+        dtype of recording. If None, will take from `recording`
+    margin_ms : float, default: 5.0
+        Margin in ms on border to avoid border effect
+
     Returns
     -------
     filter_recording : NotchFilterRecording
@@ -284,6 +296,9 @@ def __init__(self, recording, freq=3000, q=30, margin_ms=5.0, dtype=None):
 notch_filter = define_function_from_class(source_class=NotchFilterRecording, name="notch_filter")
 highpass_filter = define_function_from_class(source_class=HighpassFilterRecording, name="highpass_filter")
 
+bandpass_filter.__doc__ = bandpass_filter.__doc__.format(_common_filter_docs)
+highpass_filter.__doc__ = highpass_filter.__doc__.format(_common_filter_docs)
+
 
 def fix_dtype(recording, dtype):
     if dtype is None:

src/spikeinterface/preprocessing/normalize_scale.py

@@ -54,7 +54,7 @@ class NormalizeByQuantileRecording(BasePreprocessor):
         Median for the output distribution
     q1 : float, default: 0.01
         Lower quantile used for measuring the scale
-    q1 : float, default: 0.99
+    q2 : float, default: 0.99
         Upper quantile used for measuring the
     mode : "by_channel" | "pool_channel", default: "by_channel"
         If "by_channel" each channel is rescaled independently.

src/spikeinterface/preprocessing/phase_shift.py

@@ -31,6 +31,9 @@ class PhaseShiftRecording(BasePreprocessor):
     inter_sample_shift : None or numpy array, default: None
         If "inter_sample_shift" is not in recording properties,
         we can externally provide one.
+    dtype : None | str | dtype, default: None
+        Dtype of input and output `recording` objects.
+
 
     Returns
     -------

src/spikeinterface/preprocessing/resample.py

@@ -28,7 +28,7 @@ class ResampleRecording(BasePreprocessor):
         The recording extractor to be re-referenced
     resample_rate : int
         The resampling frequency
-    margin : float, default: 100.0
+    margin_ms : float, default: 100.0
         Margin in ms for computations, will be used to decrease edge effects.
     dtype : dtype or None, default: None
         The dtype of the returned traces. If None, the dtype of the parent recording is used.

src/spikeinterface/preprocessing/silence_periods.py

@@ -25,7 +25,9 @@ class SilencedPeriodsRecording(BasePreprocessor):
         One list per segment of tuples (start_frame, end_frame) to silence
     noise_levels : array
         Noise levels if already computed
-
+    seed : int | None, default: None
+        Random seed for `get_noise_levels` and `NoiseGeneratorRecording`.
+        If none, `get_noise_levels` uses `seed=0` and `NoiseGeneratorRecording` generates a random seed using `numpy.random.default_rng`.
     mode : "zeros" | "noise, default: "zeros"
         Determines what periods are replaced by. Can be one of the following: