neuro_py.detectors

def bimodal_thresh(
    bimodal_data,
    max_thresh=np.inf,
    schmidt=False,
    max_hist_bins=25,
    start_bins=10,
    set_thresh=None,
    nboot=100,
    force_bimodal=False,
):
    """
    BimodalThresh: Find threshold between bimodal data modes (e.g., UP vs DOWN states)
    and return crossing times (UP/DOWN onset/offset times).

    Parameters
    ----------
    bimodal_data : array-like
        Vector of bimodal data
    max_thresh : float, optional
        Maximum threshold value (default: inf)
    schmidt : bool, optional
        Use Schmidt trigger with halfway points between trough and peaks (default: False)
    max_hist_bins : int, optional
        Maximum number of histogram bins to try before giving up (default: 25)
    start_bins : int, optional
        Minimum number of histogram bins for initial histogram (default: 10)
    set_thresh : float, optional
        Manually set your own threshold (default: None)
    nboot : int, optional
        Number of bootstrap iterations for dip test (default: 100)
    force_bimodal : bool, optional
        If True, skip bimodality test and proceed with threshold detection (default: False)

    Returns
    -------
    thresh : float
        Threshold value between modes
    cross : dict
        Dictionary with keys:
        - 'upints': array of UP state intervals [onsets, offsets]
        - 'downints': array of DOWN state intervals [onsets, offsets]
    bihist : dict
        Dictionary with keys:
        - 'bins': bin centers
        - 'hist': counts
    diptest_result : dict
        Dictionary with keys:
        - 'dip': Hartigan's dip test statistic
        - 'p': p-value for bimodal distribution

    Example
    -------
    >>> data = np.concatenate([np.random.normal(0, 1, 1000),
    ...                        np.random.normal(5, 1, 1000)])
    >>> thresh, cross, bihist, diptest_result = bimodal_thresh(data)

    Notes
    -----
    Python translation of BimodalThresh.m from MehrotraLevenstein_2023

    """

    # Initialize
    bimodal_data = np.array(bimodal_data).flatten()
    bimodal_data = bimodal_data[~np.isnan(bimodal_data)]

    # Run Hartigan's dip test for bimodality
    dip_stat, p_value = hartigan_diptest(bimodal_data, n_boot=nboot)
    diptest_result = {"dip": dip_stat, "p": p_value}

    # If not bimodal, return empty (unless forced)
    if p_value > 0.05 and not force_bimodal:
        cross = {"upints": np.array([]), "downints": np.array([])}
        hist_counts, bin_edges = np.histogram(bimodal_data, bins=start_bins)
        bin_centers = (bin_edges[:-1] + bin_edges[1:]) / 2
        bihist = {"hist": hist_counts, "bins": bin_centers}
        return np.nan, cross, bihist, diptest_result

    # Remove data over max threshold
    bimodal_data = bimodal_data[bimodal_data < max_thresh]

    # Find histogram with exactly 2 peaks
    num_peaks = 1
    num_bins = start_bins

    while num_peaks != 2:
        hist_counts, bin_edges = np.histogram(bimodal_data, bins=num_bins)
        bin_centers = (bin_edges[:-1] + bin_edges[1:]) / 2

        # Find peaks (add zeros at edges for edge detection)
        padded_hist = np.concatenate([[0], hist_counts, [0]])
        peaks, _ = find_peaks(padded_hist, distance=1)
        peaks = np.sort(peaks) - 1  # Adjust for padding

        # Keep only top 2 peaks
        if len(peaks) > 2:
            peak_heights = hist_counts[peaks]
            top_2_idx = np.argsort(peak_heights)[-2:]
            peaks = np.sort(peaks[top_2_idx])

        num_peaks = len(peaks)
        num_bins += 1

        if num_bins >= max_hist_bins and set_thresh is None:
            print("Unable to find trough")
            cross = {"upints": np.array([]), "downints": np.array([])}
            bihist = {"hist": hist_counts, "bins": bin_centers}
            return np.nan, cross, bihist, diptest_result

    bihist = {"hist": hist_counts, "bins": bin_centers}

    # Find trough between peaks
    between_peaks = bin_centers[peaks[0] : peaks[1] + 1]
    between_hist = hist_counts[peaks[0] : peaks[1] + 1]

    # Find minimum (trough)
    trough_idx = np.argmin(between_hist)

    if set_thresh is not None:
        thresh = set_thresh
    else:
        thresh = between_peaks[trough_idx]

    # Schmidt trigger: use halfway points between trough and peaks
    if schmidt:
        thresh_up = thresh + 0.5 * (between_peaks[-1] - thresh)
        thresh_down = thresh + 0.5 * (between_peaks[0] - thresh)

        over_up = bimodal_data > thresh_up
        over_down = bimodal_data > thresh_down

        cross_up = np.where(np.diff(over_up.astype(int)) == 1)[0]
        cross_down = np.where(np.diff(over_down.astype(int)) == -1)[0]

        # Check for empty crossings before vstack
        if len(cross_up) == 0 or len(cross_down) == 0:
            cross = {
                "upints": np.array([]).reshape(0, 2),
                "downints": np.array([]).reshape(0, 2),
            }
            return thresh, cross, bihist, diptest_result

        # Delete incomplete (repeat) crossings
        all_crossings = np.vstack(
            [
                np.column_stack([cross_up, np.ones(len(cross_up))]),
                np.column_stack([cross_down, np.zeros(len(cross_down))]),
            ]
        )

        sort_order = np.argsort(all_crossings[:, 0])
        all_crossings = all_crossings[sort_order]

        up_down_switch = np.diff(all_crossings[:, 1])
        same_state = np.where(up_down_switch == 0)[0] + 1
        all_crossings = np.delete(all_crossings, same_state, axis=0)

        cross_up = all_crossings[all_crossings[:, 1] == 1, 0].astype(int)
        cross_down = all_crossings[all_crossings[:, 1] == 0, 0].astype(int)
    else:
        over_ind = bimodal_data > thresh
        cross_up = np.where(np.diff(over_ind.astype(int)) == 1)[0]
        cross_down = np.where(np.diff(over_ind.astype(int)) == -1)[0]

    # If only one crossing, return empty
    if len(cross_up) == 0 or len(cross_down) == 0:
        cross = {
            "upints": np.array([]).reshape(0, 2),
            "downints": np.array([]).reshape(0, 2),
        }
        return thresh, cross, bihist, diptest_result

    # Create interval arrays
    up_for_up = cross_up.copy()
    up_for_down = cross_up.copy()
    down_for_up = cross_down.copy()
    down_for_down = cross_down.copy()

    # Adjust for proper pairing
    if cross_up[0] < cross_down[0]:
        up_for_down = up_for_down[1:]
    if cross_down[-1] > cross_up[-1]:
        down_for_down = down_for_down[:-1]
    if cross_down[0] < cross_up[0]:
        down_for_up = down_for_up[1:]
    if cross_up[-1] > cross_down[-1]:
        up_for_up = up_for_up[:-1]

    # Ensure equal length for pairing
    min_len_up = min(len(up_for_up), len(down_for_up))
    min_len_down = min(len(down_for_down), len(up_for_down))

    # Check if pairing resulted in any valid intervals
    if min_len_up == 0 or min_len_down == 0:
        cross = {
            "upints": np.array([]).reshape(0, 2),
            "downints": np.array([]).reshape(0, 2),
        }
        return thresh, cross, bihist, diptest_result

    upints = np.column_stack([up_for_up[:min_len_up], down_for_up[:min_len_up]])
    downints = np.column_stack(
        [down_for_down[:min_len_down], up_for_down[:min_len_down]]
    )

    cross = {"upints": upints, "downints": downints}

    return thresh, cross, bihist, diptest_result

def detect_sharp_wave_ripples(
    basepath: Optional[str] = None,
    ripple_signal: Optional[np.ndarray] = None,
    fs: Optional[float] = None,
    timestamps: Optional[np.ndarray] = None,
    ripple_channel: Optional[int] = None,
    sharp_wave_signal: Optional[np.ndarray] = None,
    sharp_wave_channel: Optional[int] = None,
    noise_signal: Optional[np.ndarray] = None,
    noise_channel: Optional[int] = None,
    detection_epochs: Optional[Union[nel.EpochArray, np.ndarray]] = None,
    ripple_band: tuple[float, float] = (80.0, 250.0),
    sharp_wave_band: tuple[float, float] = (2.0, 50.0),
    smooth_sigma: float = 0.004,
    sharp_wave_smooth_sigma: float = 0.0,
    low_threshold: float = 1.0,
    high_threshold: float = 2.5,
    sharp_wave_low_threshold: float = 0.4,
    sharp_wave_high_threshold: float = 2.5,
    noise_threshold: Optional[float] = None,
    min_duration: float = 0.015,
    max_duration: float = 0.250,
    sharp_wave_min_duration: float = 0.020,
    sharp_wave_max_duration: float = 0.500,
    min_inter_event_interval: float = 0.025,
    merge_gap: float = 0.001,
    peak_window: float = 0.150,
    boundary_mode: str = "union",
    filter_order: int = 4,
    threshold_mode: str = "global",
    local_window: float = 5.0,
    reject_edge_events: bool = True,
    edge_buffer: Optional[float] = None,
    reject_artifacts: bool = True,
    saturation_fraction: float = 0.05,
    flat_std_threshold: Optional[float] = None,
    sharp_wave_polarity: str = "negative",
    require_sharp_wave: bool = True,
    save_mat: bool = True,
    overwrite: bool = False,
    return_epoch_array: bool = False,
    event_name: str = "ripples",
) -> Union[pd.DataFrame, nel.EpochArray]:
    """
    Detect sharp wave ripple events from a ripple-band LFP channel.

    The detector follows a compact joint SWR workflow by default: detect
    candidate ripple intervals from ripple-band power, require a nearby
    sharp-wave event on a companion low-frequency channel difference, and then
    validate ripple and sharp-wave durations separately before returning final
    events. Set ``require_sharp_wave=False`` to run explicit ripple-only
    detection when no sharp-wave channel is available.

    Parameters
    ----------
    basepath : str, optional
        Session folder used to load LFP data and optionally save a CellExplorer
        event file. Required when ``save_mat=True`` or when ``ripple_signal`` is
        not provided.
    ripple_signal : np.ndarray, optional
        One-dimensional ripple detection signal. If omitted, the signal is loaded
        from ``basepath`` using ``ripple_channel``.
    fs : float, optional
        Sampling rate in Hz. Required when ``ripple_signal`` is provided.
    timestamps : np.ndarray, optional
        Timestamps in seconds for ``ripple_signal``. If omitted, they are inferred
        from ``fs``.
    ripple_channel : int, optional
        Zero-indexed ripple channel. When omitted during file-backed detection, the
        detector tries to infer it from CellExplorer channel tags.
    sharp_wave_signal : np.ndarray, optional
        Optional companion signal used to measure low-frequency sharp-wave
        amplitude at ripple peaks.
    sharp_wave_channel : int, optional
        Zero-indexed sharp-wave channel used when loading from ``basepath``.
    noise_signal : np.ndarray, optional
        Optional ripple-band noise channel. Events are rejected when the noise-band
        power within the event exceeds ``noise_threshold``.
    noise_channel : int, optional
        Zero-indexed noise channel used when loading from ``basepath``.
    detection_epochs : nel.EpochArray or np.ndarray, optional
        Detection intervals in seconds. File-backed detection uses these intervals
        to restrict LFP loading; in-memory detection filters final events to these
        intervals.
    ripple_band : tuple of float, optional
        Ripple passband in Hz.
    sharp_wave_band : tuple of float, optional
        Sharp-wave passband in Hz used for the low-frequency difference signal.
    smooth_sigma : float, optional
        Gaussian smoothing width for the ripple envelope, in seconds.
    sharp_wave_smooth_sigma : float, optional
        Optional Gaussian smoothing width for the sharp-wave difference signal,
        in seconds.
    low_threshold : float, optional
        Lower z-scored ripple-envelope threshold used to mark candidate ripple
        boundaries.
    high_threshold : float, optional
        Peak z-scored ripple-envelope threshold required to accept an event.
    sharp_wave_low_threshold : float, optional
        Lower z-scored sharp-wave threshold used to mark candidate sharp-wave
        boundaries.
    sharp_wave_high_threshold : float, optional
        Peak z-scored sharp-wave threshold required to accept an event.
    noise_threshold : float, optional
        Maximum tolerated z-scored noise envelope for accepted events.
    min_duration : float, optional
        Minimum ripple duration in seconds.
    max_duration : float, optional
        Maximum ripple duration in seconds.
    sharp_wave_min_duration : float, optional
        Minimum sharp-wave duration in seconds.
    sharp_wave_max_duration : float, optional
        Maximum sharp-wave duration in seconds.
    min_inter_event_interval : float, optional
        Minimum time between accepted event peaks in seconds. Stronger events
        are kept first and weaker direct conflicts are removed. Set to 0 to
        disable.
    merge_gap : float, optional
        Merge candidate events separated by less than this gap, in seconds.
    peak_window : float, optional
        Maximum association window around the ripple candidate, in seconds,
        used to find the nearest/overlapping sharp-wave partner.
    boundary_mode : {"sharp_wave", "union"}, optional
        Whether final event boundaries follow the sharp-wave interval or the
        union of ripple and sharp-wave intervals.
    filter_order : int, optional
        Butterworth filter order for ripple-band filtering.
    threshold_mode : {"global", "local"}, optional
        Use global z-scored features or MATLAB-like local median/std validation
        around each candidate event.
    local_window : float, optional
        Half-window in seconds used for local threshold validation when
        ``threshold_mode="local"``.
    reject_edge_events : bool, optional
        If True, reject candidate events too close to signal boundaries.
    edge_buffer : float, optional
        Boundary buffer in seconds. If omitted, uses at least ``peak_window`` and
        uses ``local_window`` when local thresholds are enabled.
    reject_artifacts : bool, optional
        If True, reject event windows with non-finite, saturated, or flat
        required signals.
    saturation_fraction : float, optional
        Maximum tolerated fraction of event-window samples at the local minimum
        or maximum before the window is treated as clipped.
    flat_std_threshold : float, optional
        Minimum allowed event-window standard deviation. Defaults to a
        near-zero variation check.
    sharp_wave_polarity : {"negative", "positive", "both"}, optional
        Polarity of sharp-wave deflections. The default expects downward
        sharp waves and scores them positively. Ripples remain polarity
        independent because they are detected from envelope power.
    require_sharp_wave : bool, optional
        If True, require a sharp-wave signal or inferable sharp-wave channel for
        joint SWR detection. If False, allow ripple-only detection when
        sharp-wave data are unavailable. Ripple-only detections should be
        interpreted cautiously because the sharp-wave criterion helps reject
        ripple-band noise.
    save_mat : bool, optional
        If True and ``basepath`` is provided, save a CellExplorer event file.
        In-memory detections without a ``basepath`` still run normally but do
        not write an event file.
    overwrite : bool, optional
        If False and the target event file already exists, load and return the
        existing file instead of redetecting.
    return_epoch_array : bool, optional
        If True, return the detected events as a ``nel.EpochArray``.
    event_name : str, optional
        Name of the CellExplorer event struct written to disk.

    Returns
    -------
    pandas.DataFrame or nel.EpochArray
        Detected ripple events.

    Examples
    --------
    Detect joint SWRs from a CellExplorer session folder and save the default
    ``*.ripples.events.mat`` file. The ripple, sharp-wave, and noise channels
    are inferred from channel tags when available.

    >>> from neuro_py.detectors.sharp_wave_ripple import detect_sharp_wave_ripples
    >>> ripples = detect_sharp_wave_ripples(
    ...     basepath=r"S:\\data\\HMC\\HMC1\\day8",
    ...     low_threshold=0.75,
    ...     high_threshold=2.5,
    ...     sharp_wave_low_threshold=0.4,
    ...     sharp_wave_high_threshold=2.5,
    ...     overwrite=True,
    ... )

    Restrict detection to a time interval and return only the event table
    without writing a CellExplorer file.

    >>> ripples = detect_sharp_wave_ripples(
    ...     basepath=r"S:\\data\\HMC\\HMC1\\day8",
    ...     detection_epochs=np.array([[250.0, 350.0]]),
    ...     save_mat=False,
    ... )

    Run on in-memory LFP arrays. This is useful for simulations or when data
    have already been loaded by another pipeline.

    >>> ripples = detect_sharp_wave_ripples(
    ...     ripple_signal=ripple_lfp,
    ...     sharp_wave_signal=sharp_wave_lfp,
    ...     fs=1250.0,
    ...     timestamps=timestamps,
    ...     save_mat=False,
    ... )

    If no sharp-wave channel is available, ripple-only detection must be
    requested explicitly.

    >>> ripples = detect_sharp_wave_ripples(
    ...     ripple_signal=ripple_lfp,
    ...     fs=1250.0,
    ...     save_mat=False,
    ...     require_sharp_wave=False,
    ... )
    """
    if basepath is None and ripple_signal is None:
        raise ValueError("Provide either `basepath` or `ripple_signal` for detection.")
    if boundary_mode not in {"sharp_wave", "union"}:
        raise ValueError("`boundary_mode` must be either 'sharp_wave' or 'union'.")
    if threshold_mode not in {"global", "local"}:
        raise ValueError("`threshold_mode` must be either 'global' or 'local'.")
    if sharp_wave_polarity not in {"negative", "positive", "both"}:
        raise ValueError(
            "`sharp_wave_polarity` must be 'negative', 'positive', or 'both'."
        )
    if min_inter_event_interval < 0:
        raise ValueError("`min_inter_event_interval` must be non-negative.")
    if local_window <= 0:
        raise ValueError("`local_window` must be positive.")
    if not 0 < saturation_fraction <= 1:
        raise ValueError("`saturation_fraction` must be in the interval (0, 1].")
    if edge_buffer is not None and edge_buffer < 0:
        raise ValueError("`edge_buffer` must be non-negative.")

    should_save_mat = bool(save_mat and basepath is not None)

    if should_save_mat and not overwrite:
        event_path = os.path.join(
            basepath,
            os.path.basename(basepath) + f".{event_name}.events.mat",
        )
        if os.path.exists(event_path):
            if event_name == "ripples":
                existing = loading.load_ripples_events(basepath)
            else:
                existing = loading.load_events(basepath, event_name, load_pandas=True)
                if existing is None:
                    existing = pd.DataFrame()
                else:
                    existing = existing.rename(
                        columns={"starts": "start", "stops": "stop"}
                    )
            if return_epoch_array:
                if existing.empty:
                    return nel.EpochArray(np.empty((0, 2), dtype=float))
                return nel.EpochArray(existing[["start", "stop"]].to_numpy(dtype=float))
            return existing

    if ripple_signal is None:
        ripple_signal, timestamps, fs, ripple_channel, loaded_signals = _load_signals(
            basepath=basepath,
            ripple_channel=ripple_channel,
            sharp_wave_channel=sharp_wave_channel,
            noise_channel=noise_channel,
            detection_epochs=detection_epochs,
        )
        sharp_wave_signal = loaded_signals["sharp_wave_signal"]
        noise_signal = loaded_signals["noise_signal"]
    else:
        if fs is None:
            raise ValueError("`fs` is required when `ripple_signal` is provided.")
        ripple_signal = np.asarray(ripple_signal, dtype=float)
        if ripple_signal.ndim != 1:
            raise ValueError("`ripple_signal` must be one-dimensional.")
        if timestamps is None:
            timestamps = np.arange(ripple_signal.size, dtype=float) / float(fs)
        else:
            timestamps = np.asarray(timestamps, dtype=float)
        if timestamps.shape[0] != ripple_signal.shape[0]:
            raise ValueError(
                "`timestamps` must have the same length as `ripple_signal`."
            )
        if sharp_wave_signal is not None:
            sharp_wave_signal = np.asarray(sharp_wave_signal, dtype=float)
        if noise_signal is not None:
            noise_signal = np.asarray(noise_signal, dtype=float)

    if require_sharp_wave and sharp_wave_signal is None:
        raise ValueError(
            "Joint SWR detection requires a sharp-wave signal. Pass "
            "`sharp_wave_signal`, provide `sharp_wave_channel`, add a "
            "CellExplorer SharpWave channel tag, or set "
            "`require_sharp_wave=False` for explicit ripple-only detection."
        )

    ripple_filtered, envelope, ripple_phase = _compute_envelope(
        signal_in=ripple_signal,
        fs=float(fs),
        ripple_band=ripple_band,
        smooth_sigma=smooth_sigma,
        filter_order=filter_order,
    )
    power = _zscore(envelope)

    candidate_bounds = _find_true_bounds(power >= low_threshold)
    candidate_bounds = _merge_bounds(
        candidate_bounds,
        gap_samples=max(1, int(round(merge_gap * float(fs)))),
    )

    sharp_wave_trace = None
    sharp_wave_power = None
    sharp_wave_bounds = None
    if sharp_wave_signal is not None:
        sharp_wave_trace, sharp_wave_power = _compute_sharp_wave_difference(
            ripple_signal=ripple_signal,
            sharp_wave_signal=sharp_wave_signal,
            fs=float(fs),
            sharp_wave_band=sharp_wave_band,
            filter_order=filter_order,
            smooth_sigma=sharp_wave_smooth_sigma,
            sharp_wave_polarity=sharp_wave_polarity,
        )
        sharp_wave_bounds = _find_true_bounds(
            sharp_wave_power >= sharp_wave_low_threshold
        )
        sharp_wave_bounds = _merge_bounds(
            sharp_wave_bounds,
            gap_samples=max(1, int(round(merge_gap * float(fs)))),
        )

    noise_power = None
    if noise_signal is not None:
        _, noise_envelope, _ = _compute_envelope(
            signal_in=noise_signal,
            fs=float(fs),
            ripple_band=ripple_band,
            smooth_sigma=smooth_sigma,
            filter_order=filter_order,
        )
        noise_power = _zscore(noise_envelope)

    effective_edge_buffer = peak_window if edge_buffer is None else float(edge_buffer)
    if threshold_mode == "local":
        effective_edge_buffer = max(effective_edge_buffer, float(local_window))

    events = _events_to_dataframe(
        ripple_bounds=candidate_bounds,
        ripple_power=power,
        ripple_envelope=envelope,
        ripple_filtered=ripple_filtered,
        ripple_phase=ripple_phase,
        ripple_signal=ripple_signal,
        timestamps=timestamps,
        fs=float(fs),
        ripple_min_duration=min_duration,
        ripple_max_duration=max_duration,
        ripple_high_threshold=high_threshold,
        ripple_channel=ripple_channel,
        sharp_wave_bounds=sharp_wave_bounds,
        sharp_wave_power=sharp_wave_power,
        sharp_wave_trace=sharp_wave_trace,
        sharp_wave_low_threshold=sharp_wave_low_threshold,
        sharp_wave_high_threshold=sharp_wave_high_threshold,
        sharp_wave_min_duration=sharp_wave_min_duration,
        sharp_wave_max_duration=sharp_wave_max_duration,
        search_window=peak_window,
        boundary_mode=boundary_mode,
        noise_power=noise_power,
        noise_signal=noise_signal,
        noise_threshold=noise_threshold,
        sharp_wave_signal=sharp_wave_signal,
        threshold_mode=threshold_mode,
        local_window=local_window,
        reject_edge_events=reject_edge_events,
        edge_buffer=effective_edge_buffer,
        reject_artifacts=reject_artifacts,
        saturation_fraction=saturation_fraction,
        flat_std_threshold=flat_std_threshold,
    )

    events = _filter_events_to_detection_epochs(events, detection_epochs)
    events = _enforce_min_inter_event_interval(events, min_inter_event_interval)

    if should_save_mat:
        detection_params = {
            "ripple_band": np.asarray(ripple_band, dtype=float),
            "sharp_wave_band": np.asarray(sharp_wave_band, dtype=float),
            "smooth_sigma": float(smooth_sigma),
            "sharp_wave_smooth_sigma": float(sharp_wave_smooth_sigma),
            "low_threshold": float(low_threshold),
            "high_threshold": float(high_threshold),
            "sharp_wave_low_threshold": float(sharp_wave_low_threshold),
            "sharp_wave_high_threshold": float(sharp_wave_high_threshold),
            "noise_threshold": noise_threshold,
            "min_duration": float(min_duration),
            "max_duration": float(max_duration),
            "sharp_wave_min_duration": float(sharp_wave_min_duration),
            "sharp_wave_max_duration": float(sharp_wave_max_duration),
            "min_inter_event_interval": float(min_inter_event_interval),
            "merge_gap": float(merge_gap),
            "peak_window": float(peak_window),
            "boundary_mode": boundary_mode,
            "threshold_mode": threshold_mode,
            "local_window": float(local_window),
            "reject_edge_events": bool(reject_edge_events),
            "edge_buffer": effective_edge_buffer,
            "reject_artifacts": bool(reject_artifacts),
            "saturation_fraction": float(saturation_fraction),
            "flat_std_threshold": flat_std_threshold,
            "sharp_wave_polarity": sharp_wave_polarity,
            "require_sharp_wave": bool(require_sharp_wave),
            "filter_order": int(filter_order),
        }
        if ripple_channel is not None:
            detection_params["channel"] = int(ripple_channel)

        save_ripple_events(
            events=events,
            basepath=basepath,
            detection_name="detect_sharp_wave_ripples",
            detection_params=detection_params,
            ripple_channel=ripple_channel,
            detection_epochs=detection_epochs,
            event_name=event_name,
        )

    if return_epoch_array:
        if events.empty:
            return nel.EpochArray(np.empty((0, 2), dtype=float))
        return nel.EpochArray(events[["start", "stop"]].to_numpy(dtype=float))

    return events