From 400b0b3dde597d4b11ada31dfd87097f1fa81d9a Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 19 Jun 2024 18:34:17 +0200
Subject: [PATCH 01/31] initial copy/paste from dredge

---
 .../sortingcomponents/dredge.py               | 604 ++++++++++++++++++
 .../sortingcomponents/motion_estimation.py    |   3 +
 2 files changed, 607 insertions(+)
 create mode 100644 src/spikeinterface/sortingcomponents/dredge.py

diff --git a/src/spikeinterface/sortingcomponents/dredge.py b/src/spikeinterface/sortingcomponents/dredge.py
new file mode 100644
index 0000000000..fd56715fa9
--- /dev/null
+++ b/src/spikeinterface/sortingcomponents/dredge.py
@@ -0,0 +1,604 @@
+"""
+Re-implementation or copy-paste of DREDge
+https://github.com/evarol/dredge
+
+For historical reason, some function from the DREDge package where implemeneted 
+in spikeinterface in the motion_estimation.py before the DREDge package itself!
+
+Here a copy/paste (and small rewriting) of some functions from DREDge.
+
+The main entry for this function are still:
+
+  * motion = estimate_motion((recording, ..., method='dredge_lfp')
+  * motion = estimate_motion((recording, ..., method='dredge_ap')
+
+but here the original functions from Charlie, Julien and Erdem have been ported for an
+easier maintenance instead of making DREDge a dependency of spikeinterface.
+"""
+
+# TODO
+# discuss the get_windows in dredge
+# remove get_motion_estimate() ???
+
+
+import numpy as np
+
+
+def dredge_online_lfp(
+    lfp_recording,
+    rigid=True,
+    chunk_len_s=10.0,
+    max_disp_um=500,
+    # nonrigid window construction arguments
+    win_shape="gaussian",
+    win_step_um=800,
+    win_scale_um=850,
+    win_margin_um=None,
+    max_dt_s=None,
+    # weighting arguments
+    mincorr=0.8,
+    mincorr_percentile=None,
+    mincorr_percentile_nneighbs=20,
+    soft=False,
+    # low-level arguments
+    thomas_kw=None,
+    xcorr_kw=None,
+    # misc
+    save_full=False,
+    device=None,
+    pbar=True,
+):
+    """Online registration of a preprocessed LFP recording
+
+    Arguments
+    ---------
+    lfp_recording : spikeinterface BaseRecording object
+        Preprocessed LFP recording. The temporal resolution of this recording will
+        be the target resolution of the registration, so definitely use SpikeInterface
+        to resample your recording to, say, 250Hz (or a value you like) rather than
+        estimating motion at the original frequency (which may be high).
+    rigid : boolean, optional
+        If True, window-related arguments are ignored and we do rigid registration
+    chunk_len_s : float
+        Length of chunks (in seconds) that the recording is broken into for online
+        registration. The computational speed of the method is a function of the
+        number of samples this corresponds to, and things can get slow if it is
+        set high enough that the number of samples per chunk is bigger than ~10,000.
+        But, it can't be set too low or the algorithm doesn't have enough data
+        to work with. The default is set assuming sampling rate of 250Hz, leading
+        to 2500 samples per chunk.
+    max_dt_s : float
+        Time-bins farther apart than this value in seconds will not be cross-correlated.
+        Set this to at least `chunk_len_s`.
+    max_disp_um : number, optional
+        This is the ceiling on the possible displacement estimates. It should be
+        set to a number which is larger than the allowed displacement in a single
+        chunk. Setting it as small as possible (while following that rule) can speed
+        things up and improve the result by making it impossible to estimate motion
+        which is too big.
+    win_shape, win_step_um, win_scale_um, win_margin_um : float
+        Nonrigid window-related arguments
+        The depth domain will be broken up into windows with shape controlled by win_shape,
+        spaced by win_step_um at a margin of win_margin_um from the boundary, and with
+        width controlled by win_scale_um.
+    mincorr : float in [0,1]
+        Minimum correlation between pairs of frames such that they will be included
+        in the optimization of the displacement estimates.
+    mincorr_percentile, mincorr_percentile_nneighbs
+        If mincorr_percentile is set to a number in [0, 100], then mincorr will be replaced
+        by this percentile of the correlations of neighbors within mincorr_percentile_nneighbs
+        time bins of each other.
+    device : string or torch.device
+        Controls torch device
+
+    Returns
+    -------
+    me : motion_util.MotionEstimate
+        A motion estimate object. me.displacement is the displacement trace, but this object
+        includes methods for getting the displacement at different times and depths; see
+        the documentation in the motion_util.py file.
+    extra : dict
+        Dict containing extra info for debugging
+    """
+    geom = lfp_recording.get_channel_locations()
+    fs = lfp_recording.get_sampling_frequency()
+    T_total = lfp_recording.get_num_samples()
+    T_chunk = min(int(np.floor(fs * chunk_len_s)), T_total)
+
+    # kwarg defaults and handling
+    # need lfp-specific defaults
+    xcorr_kw = xcorr_kw if xcorr_kw is not None else {}
+    thomas_kw = thomas_kw if thomas_kw is not None else {}
+    full_xcorr_kw = dict(
+        rigid=rigid,
+        bin_um=np.median(np.diff(geom[:, 1])),
+        max_disp_um=max_disp_um,
+        pbar=False,
+        device=device,
+        **xcorr_kw,
+    )
+    threshold_kw = dict(
+        mincorr_percentile_nneighbs=mincorr_percentile_nneighbs,
+        in_place=True,
+        soft=soft,
+        # max_dt_s=weights_kw["max_dt_s"],  # max_dt not implemented for lfp at this point
+        max_dt_s=max_dt_s,
+        bin_s=1 / fs,  # only relevant for max_dt_s
+    )
+
+    # get windows
+    windows, window_centers = get_windows(
+        geom,
+        win_step_um,
+        win_scale_um,
+        spatial_bin_centers=geom[:, 1],
+        margin_um=win_margin_um,
+        win_shape=win_shape,
+        zero_threshold=1e-5,
+        rigid=rigid,
+    )
+    B = len(windows)
+    extra = dict(window_centers=window_centers, windows=windows)
+
+    # -- allocate output and initialize first chunk
+    P_online = np.empty((B, T_total), dtype=np.float32)
+    # below, t0 is start of prev chunk, t1 start of cur chunk, t2 end of cur
+    t0, t1 = 0, T_chunk
+    traces0 = lfp_recording.get_traces(start_frame=t0, end_frame=t1)
+    Ds0, Cs0, max_disp_um = xcorr_windows(
+        traces0.T, windows, geom[:, 1], win_scale_um, **full_xcorr_kw
+    )
+    full_xcorr_kw["max_disp_um"] = max_disp_um
+    Ss0, mincorr0 = threshold_correlation_matrix(
+        Cs0,
+        mincorr=mincorr,
+        mincorr_percentile=mincorr_percentile,
+        **threshold_kw,
+    )
+    if save_full:
+        extra["D"] = [Ds0]
+        extra["C"] = [Cs0]
+        extra["S"] = [Ss0]
+        extra["D01"] = []
+        extra["C01"] = []
+        extra["S01"] = []
+    extra["mincorrs"] = [mincorr0]
+    extra["max_disp_um"] = max_disp_um
+    P_online[:, t0:t1], _ = thomas_solve(Ds0, Ss0, **thomas_kw)
+
+    # -- loop through chunks
+    chunk_starts = range(T_chunk, T_total, T_chunk)
+    if pbar:
+        chunk_starts = trange(
+            T_chunk,
+            T_total,
+            T_chunk,
+            desc=f"Online chunks [{chunk_len_s}s each]",
+        )
+    for t1 in chunk_starts:
+        t2 = min(T_total, t1 + T_chunk)
+        traces1 = lfp_recording.get_traces(start_frame=t1, end_frame=t2)
+
+        # cross-correlations between prev/cur chunks
+        # these are T1, T0 shaped
+        Ds10, Cs10, _ = xcorr_windows(
+            traces1.T,
+            windows,
+            geom[:, 1],
+            win_scale_um,
+            raster_b=traces0.T,
+            **full_xcorr_kw,
+        )
+
+        # cross-correlation in current chunk
+        Ds1, Cs1, _ = xcorr_windows(
+            traces1.T, windows, geom[:, 1], win_scale_um, **full_xcorr_kw
+        )
+        Ss1, mincorr1 = threshold_correlation_matrix(
+            Cs1,
+            mincorr_percentile=mincorr_percentile,
+            mincorr=mincorr,
+            **threshold_kw,
+        )
+        Ss10, _ = threshold_correlation_matrix(
+            Cs10, mincorr=mincorr1, t_offset_bins=T_chunk, **threshold_kw
+        )
+        extra["mincorrs"].append(mincorr1)
+
+        if save_full:
+            extra["D"].append(Ds1)
+            extra["C"].append(Cs1)
+            extra["S"].append(Ss1)
+            extra["D01"].append(Ds10)
+            extra["C01"].append(Cs10)
+            extra["S01"].append(Ss10)
+
+        # solve online problem
+        P_online[:, t1:t2], _ = thomas_solve(
+            Ds1,
+            Ss1,
+            P_prev=P_online[:, t0:t1],
+            Ds_curprev=Ds10,
+            Us_curprev=Ss10,
+            Ds_prevcur=-Ds10.transpose(0, 2, 1),
+            Us_prevcur=Ss10.transpose(0, 2, 1),
+            **thomas_kw,
+        )
+
+        # update loop vars
+        t0, t1 = t1, t2
+        traces0 = traces1
+
+    # -- convert to motion estimate and return
+    me = get_motion_estimate(
+        P_online,
+        time_bin_centers_s=lfp_recording.get_times(0),
+        spatial_bin_centers_um=window_centers,
+    )
+    return me, extra
+
+
+
+# -- functions from dredgelib
+
+
+
+def thomas_solve(
+    Ds,
+    Us,
+    lambda_t=DEFAULT_LAMBDA_T,
+    lambda_s=1.0,
+    eps=DEFAULT_EPS,
+    P_prev=None,
+    Ds_prevcur=None,
+    Us_prevcur=None,
+    Ds_curprev=None,
+    Us_curprev=None,
+    pbar=False,
+    bandwidth=None,
+):
+    """Block tridiagonal algorithm, special cased to our setting
+
+    This code solves for the displacement estimates across the nonrigid windows,
+    given blockwise, pairwise (BxTxT) displacement and weights arrays `Ds` and `Us`.
+
+    If `lambda_t>0`, a temporal prior is applied to "fill the gaps", effectively
+    interpolating through time to avoid artifacts in low-signal areas. Setting this
+    to 0 can lead to numerical warnings and should be done with care.
+
+    If `lambda_s>0`, a spatial prior is applied. This can help fill gaps more
+    meaningfully in the nonrigid case, using information from the neighboring nonrigid
+    windows to inform the estimate in an untrusted region of a given window.
+
+    If arguments `P_prev,Ds_prevcur,Us_prevcur` are supplied, this code handles the
+    online case. The return value will be the new chunk's displacement estimate,
+    solving the online registration problem.
+    """
+    Ds = np.asarray(Ds, dtype=np.float64)
+    Us = np.asarray(Us, dtype=np.float64)
+    online = P_prev is not None
+    online_kw_rhs = online_kw_hess = lambda b: {}
+    if online:
+        assert Ds_prevcur is not None
+        assert Us_prevcur is not None
+        online_kw_rhs = lambda b: dict(  # noqa
+            Pb_prev=P_prev[b].astype(np.float64, copy=False),
+            Db_prevcur=Ds_prevcur[b].astype(np.float64, copy=False),
+            Ub_prevcur=Us_prevcur[b].astype(np.float64, copy=False),
+            Db_curprev=Ds_curprev[b].astype(np.float64, copy=False),
+            Ub_curprev=Us_curprev[b].astype(np.float64, copy=False),
+        )
+        online_kw_hess = lambda b: dict(  # noqa
+            Ub_prevcur=Us_prevcur[b].astype(np.float64, copy=False),
+            Ub_curprev=Us_curprev[b].astype(np.float64, copy=False),
+        )
+
+    B, T, T_ = Ds.shape
+    assert T == T_
+    assert Us.shape == Ds.shape
+
+    # figure out which temporal bins are included in the problem
+    # these are used to figure out where epsilon can be added
+    # for numerical stability without changing the solution
+    had_weights = (Us > 0).any(axis=2)
+    had_weights[~had_weights.any(axis=1)] = 1
+
+    # temporal prior matrix
+    L_t = [laplacian(T, eps=eps, lambd=lambda_t, ridge_mask=w) for w in had_weights]
+    extra = dict(L_t=L_t)
+
+    # just solve independent problems when there's no spatial regularization
+    # not that there's much overhead to the backward pass etc but might as well
+    if B == 1 or lambda_s == 0:
+        P = np.zeros((B, T))
+        extra["HU"] = np.zeros((B, T, T))
+        for b in range(B):
+            P[b], extra["HU"][b] = newton_solve_rigid(
+                Ds[b], Us[b], L_t[b], **online_kw_rhs(b)
+            )
+        return P, extra
+
+    # spatial prior is a sparse, block tridiagonal kronecker product
+    # the first and last diagonal blocks are
+    Lambda_s_diagb = laplacian(T, eps=eps, lambd=lambda_s / 2, ridge_mask=had_weights[0])
+    # and the off-diagonal blocks are
+    Lambda_s_offdiag = laplacian(T, eps=0, lambd=-lambda_s / 2)
+
+    # initialize block-LU stuff and forward variable
+    alpha_hat_b = (
+        L_t[0]
+        + Lambda_s_diagb
+        + neg_hessian_likelihood_term(Us[0], **online_kw_hess(0))
+    )
+    targets = np.c_[
+        Lambda_s_offdiag, newton_rhs(Us[0], Ds[0], **online_kw_rhs(0))
+    ]
+    res = solve(alpha_hat_b, targets, assume_a="pos")
+    assert res.shape == (T, T + 1)
+    gamma_hats = [res[:, :T]]
+    ys = [res[:, T]]
+
+    # forward pass
+    for b in (trange(1, B, desc="Solve") if pbar else range(1, B)):
+        if b < B - 1:
+            Lambda_s_diagb = laplacian(T, eps=eps, lambd=lambda_s, ridge_mask=had_weights[b])
+        else:
+            Lambda_s_diagb = laplacian(T, eps=eps, lambd=lambda_s / 2, ridge_mask=had_weights[b])
+
+        Ab = (
+            L_t[b]
+            + Lambda_s_diagb
+            + neg_hessian_likelihood_term(Us[b], **online_kw_hess(b))
+        )
+        alpha_hat_b = Ab - Lambda_s_offdiag @ gamma_hats[b - 1]
+        targets[:, T] = newton_rhs(Us[b], Ds[b], **online_kw_rhs(b))
+        targets[:, T] -= Lambda_s_offdiag @ ys[b - 1]
+        res = solve(alpha_hat_b, targets)
+        assert res.shape == (T, T + 1)
+        gamma_hats.append(res[:, :T])
+        ys.append(res[:, T])
+
+    # back substitution
+    xs = [None] * B
+    xs[-1] = ys[-1]
+    for b in range(B - 2, -1, -1):
+        xs[b] = ys[b] - gamma_hats[b] @ xs[b + 1]
+
+    # un-vectorize
+    P = np.concatenate(xs).reshape(B, T)
+
+    return P, extra
+
+
+
+def threshold_correlation_matrix(
+    Cs,
+    mincorr=0.0,
+    mincorr_percentile=None,
+    mincorr_percentile_nneighbs=20,
+    max_dt_s=0,
+    in_place=False,
+    bin_s=1,
+    t_offset_bins=None,
+    T=None,
+    soft=True,
+):
+    if mincorr_percentile is not None:
+        diags = [
+            np.diagonal(Cs, offset=j, axis1=1, axis2=2).ravel()
+            for j in range(1, mincorr_percentile_nneighbs)
+        ]
+        mincorr = np.percentile(
+            np.concatenate(diags),
+            mincorr_percentile,
+        )
+
+    # need abs to avoid -0.0s which cause numerical issues
+    if in_place:
+        Ss = Cs
+        if soft:
+            Ss[Ss < mincorr] = 0
+        else:
+            Ss = (Ss >= mincorr).astype(Cs.dtype)
+        np.square(Ss, out=Ss)
+    else:
+        if soft:
+            Ss = np.square((Cs >= mincorr) * Cs)
+        else:
+            Ss = (Cs >= mincorr).astype(Cs.dtype)
+    if (
+        max_dt_s is not None
+        and max_dt_s > 0
+        and T is not None
+        and max_dt_s < T
+    ):
+        tt0 = bin_s * np.arange(T)
+        tt1 = tt0
+        if t_offset_bins:
+            tt1 = tt0 + t_offset_bins
+        dt = tt1[:, None] - tt0[None, :]
+        mask = (np.abs(dt) <= max_dt_s).astype(Ss.dtype)
+        Ss *= mask[None]
+    return Ss, mincorr
+
+
+def xcorr_windows(
+    raster_a,
+    windows,
+    spatial_bin_edges_um,
+    win_scale_um,
+    raster_b=None,
+    rigid=False,
+    bin_um=1,
+    max_disp_um=None,
+    max_dt_bins=None,
+    pbar=True,
+    centered=True,
+    normalized=True,
+    masks=None,
+    device=None,
+):
+    """Main computational function
+
+    Compute pairwise (time x time) maximum cross-correlation and displacement
+    matrices in each nonrigid window.
+    """
+    if device is None:
+        device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+    if max_disp_um is None:
+        if rigid:
+            max_disp_um = int(spatial_bin_edges_um.ptp() // 4)
+        else:
+            max_disp_um = int(win_scale_um // 4)
+
+    max_disp_bins = int(max_disp_um // bin_um)
+    slices = get_window_domains(windows)
+    B, D = windows.shape
+    D_, T0 = raster_a.shape
+    assert D == D_
+
+    # torch versions on device
+    windows_ = torch.as_tensor(windows, dtype=torch.float, device=device)
+    raster_a_ = torch.as_tensor(raster_a, dtype=torch.float, device=device)
+    if raster_b is not None:
+        assert raster_b.shape[0] == D
+        T1 = raster_b.shape[1]
+        raster_b_ = torch.as_tensor(raster_b, dtype=torch.float, device=device)
+    else:
+        T1 = T0
+        raster_b_ = raster_a_
+    if masks is not None:
+        masks = torch.as_tensor(masks, dtype=torch.float, device=device)
+
+    # estimate each window's displacement
+    Ds = np.zeros((B, T0, T1), dtype=np.float32)
+    Cs = np.zeros((B, T0, T1), dtype=np.float32)
+    block_iter = trange(B, desc="Cross correlation") if pbar else range(B)
+    for b in block_iter:
+        window = windows_[b]
+
+        # we search for the template (windowed part of raster a)
+        # within a larger-than-the-window neighborhood in raster b
+        targ_low = slices[b].start - max_disp_bins
+        b_low = max(0, targ_low)
+        targ_high = slices[b].stop + max_disp_bins
+        b_high = min(D, targ_high)
+        padding = max(b_low - targ_low, targ_high - b_high)
+
+        # arithmetic to compute the lags in um corresponding to
+        # corr argmaxes
+        n_left = padding + slices[b].start - b_low
+        n_right = padding + b_high - slices[b].stop
+        poss_disp = -np.arange(-n_left, n_right + 1) * bin_um
+
+        Ds[b], Cs[b] = calc_corr_decent_pair(
+            raster_a_[slices[b]],
+            raster_b_[b_low:b_high],
+            weights=window[slices[b]],
+            masks=None if masks is None else masks[slices[b]],
+            xmasks=None if masks is None else masks[b_low:b_high],
+            disp=padding,
+            possible_displacement=poss_disp,
+            device=device,
+            centered=centered,
+            normalized=normalized,
+            max_dt_bins=max_dt_bins,
+        )
+
+    return Ds, Cs, max_disp_um
+
+
+def calc_corr_decent_pair(
+    raster_a,
+    raster_b,
+    weights=None,
+    masks=None,
+    xmasks=None,
+    disp=None,
+    batch_size=512,
+    normalized=True,
+    centered=True,
+    possible_displacement=None,
+    max_dt_bins=None,
+    device=None,
+):
+    """Weighted pairwise cross-correlation
+
+    Calculate TxT normalized xcorr and best displacement matrices
+    Given a DxT raster, this computes normalized cross correlations for
+    all pairs of time bins at offsets in the range [-disp, disp], by
+    increments of step_size. Then it finds the best one and its
+    corresponding displacement, resulting in two TxT matrices: one for
+    the normxcorrs at the best displacement, and the matrix of the best
+    displacements.
+
+    Arguments
+    ---------
+    raster : DxT array
+    batch_size : int
+        How many raster rows to xcorr against the whole raster
+        at once.
+    step_size : int
+        Displacement increment. Not implemented yet but easy to do.
+    disp : int
+        Maximum displacement
+    device : torch device
+    Returns: D, C: TxT arrays
+    """
+    D, Ta = raster_a.shape
+    D_, Tb = raster_b.shape
+
+    # sensible default: at most half the domain.
+    if disp is None:
+        disp == D // 2
+
+    # range of displacements
+    if D == D_:
+        if possible_displacement is None:
+            possible_displacement = np.arange(-disp, disp + 1)
+    else:
+        assert possible_displacement is not None
+        assert disp is not None
+
+    # pick torch device if unset
+    if device is None:
+        device = (
+            torch.device("cuda")
+            if torch.cuda.is_available()
+            else torch.device("cpu")
+        )
+
+    # process rasters into the tensors we need for conv2ds below
+    # convert to TxD device floats
+    raster_a = torch.as_tensor(raster_a.T, dtype=torch.float32, device=device)
+    # normalize over depth for normalized (uncentered) xcorrs
+    raster_b = torch.as_tensor(raster_b.T, dtype=torch.float32, device=device)
+
+    D = np.zeros((Ta, Tb), dtype=np.float32)
+    C = np.zeros((Ta, Tb), dtype=np.float32)
+    for i in range(0, Ta, batch_size):
+        for j in range(0, Tb, batch_size):
+            dt_bins = min(
+                abs(i - j), abs(i + batch_size - j), abs(i - j - batch_size)
+            )
+            if max_dt_bins and dt_bins > max_dt_bins:
+                continue
+            weights_ = weights
+            if masks is not None:
+                weights_ = masks.T[i : i + batch_size] * weights
+            corr = normxcorr1d(
+                raster_a[i : i + batch_size],
+                raster_b[j : j + batch_size],
+                weights=weights_,
+                xmasks=None if xmasks is None else xmasks.T[j : j + batch_size],
+                padding=disp,
+                normalized=normalized,
+                centered=centered,
+            )
+            max_corr, best_disp_inds = torch.max(corr, dim=2)
+            best_disp = possible_displacement[best_disp_inds.cpu()]
+            D[i : i + batch_size, j : j + batch_size] = best_disp.T
+            C[i : i + batch_size, j : j + batch_size] = max_corr.cpu().T
+
+    return D, C
\ No newline at end of file
diff --git a/src/spikeinterface/sortingcomponents/motion_estimation.py b/src/spikeinterface/sortingcomponents/motion_estimation.py
index 3134d68681..42fd12383d 100644
--- a/src/spikeinterface/sortingcomponents/motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion_estimation.py
@@ -602,7 +602,9 @@ def get_windows(rigid, bin_um, contact_pos, spatial_bin_edges, margin_um, win_st
     Here by default we use gaussian window.
 
     """
+    # TODO remove bin_um
     bin_centers = spatial_bin_edges[:-1] + bin_um / 2.0
+    # bin_centers = 0.5 * (spatial_bin_edges[1:] + spatial_bin_edges[:-1])
     n = bin_centers.size
 
     if rigid:
@@ -611,6 +613,7 @@ def get_windows(rigid, bin_um, contact_pos, spatial_bin_edges, margin_um, win_st
         middle = (spatial_bin_edges[0] + spatial_bin_edges[-1]) / 2.0
         non_rigid_window_centers = np.array([middle])
     else:
+        # TODO put a warning
         assert win_sigma_um >= win_step_um, f"win_sigma_um too low {win_sigma_um} compared to win_step_um {win_step_um}"
 
         min_ = np.min(contact_pos) - margin_um

From ddf094bff9138d373ce70a6698fd449d4a1642ee Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 21 Jun 2024 11:53:09 +0200
Subject: [PATCH 02/31] Move motion files into new motion subfolder

---
 src/spikeinterface/sortingcomponents/motion/__init__.py           | 0
 src/spikeinterface/sortingcomponents/{ => motion}/dredge.py       | 0
 .../sortingcomponents/{ => motion}/motion_estimation.py           | 0
 .../sortingcomponents/{ => motion}/motion_interpolation.py        | 0
 src/spikeinterface/sortingcomponents/{ => motion}/motion_utils.py | 0
 .../{ => motion}/tests/test_motion_estimation.py                  | 0
 .../{ => motion}/tests/test_motion_interpolation.py               | 0
 .../sortingcomponents/{ => motion}/tests/test_motion_utils.py     | 0
 8 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 src/spikeinterface/sortingcomponents/motion/__init__.py
 rename src/spikeinterface/sortingcomponents/{ => motion}/dredge.py (100%)
 rename src/spikeinterface/sortingcomponents/{ => motion}/motion_estimation.py (100%)
 rename src/spikeinterface/sortingcomponents/{ => motion}/motion_interpolation.py (100%)
 rename src/spikeinterface/sortingcomponents/{ => motion}/motion_utils.py (100%)
 rename src/spikeinterface/sortingcomponents/{ => motion}/tests/test_motion_estimation.py (100%)
 rename src/spikeinterface/sortingcomponents/{ => motion}/tests/test_motion_interpolation.py (100%)
 rename src/spikeinterface/sortingcomponents/{ => motion}/tests/test_motion_utils.py (100%)

diff --git a/src/spikeinterface/sortingcomponents/motion/__init__.py b/src/spikeinterface/sortingcomponents/motion/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/src/spikeinterface/sortingcomponents/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/dredge.py
rename to src/spikeinterface/sortingcomponents/motion/dredge.py
diff --git a/src/spikeinterface/sortingcomponents/motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/motion_estimation.py
rename to src/spikeinterface/sortingcomponents/motion/motion_estimation.py
diff --git a/src/spikeinterface/sortingcomponents/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/motion_interpolation.py
rename to src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
diff --git a/src/spikeinterface/sortingcomponents/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/motion_utils.py
rename to src/spikeinterface/sortingcomponents/motion/motion_utils.py
diff --git a/src/spikeinterface/sortingcomponents/tests/test_motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/tests/test_motion_estimation.py
rename to src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
diff --git a/src/spikeinterface/sortingcomponents/tests/test_motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/tests/test_motion_interpolation.py
rename to src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
diff --git a/src/spikeinterface/sortingcomponents/tests/test_motion_utils.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_utils.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/tests/test_motion_utils.py
rename to src/spikeinterface/sortingcomponents/motion/tests/test_motion_utils.py

From a6424f2a1933b58c65878bca7ddd790a4ac78439 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 21 Jun 2024 15:04:58 +0200
Subject: [PATCH 03/31] Reorganize dredge function with already existing

---
 src/spikeinterface/preprocessing/motion.py    |   7 +-
 .../sortingcomponents/motion/__init__.py      |   4 +
 .../sortingcomponents/motion/dredge.py        | 315 ++++++++++++++++--
 .../motion/motion_estimation.py               | 168 ++--------
 .../sortingcomponents/motion/motion_utils.py  | 123 +++++++
 .../motion/tests/test_motion_estimation.py    |  21 +-
 6 files changed, 469 insertions(+), 169 deletions(-)

diff --git a/src/spikeinterface/preprocessing/motion.py b/src/spikeinterface/preprocessing/motion.py
index 8023bd4367..1e825f9c73 100644
--- a/src/spikeinterface/preprocessing/motion.py
+++ b/src/spikeinterface/preprocessing/motion.py
@@ -239,8 +239,8 @@ def correct_motion(
       * :py:func:`~spikeinterface.sortingcomponents.peak_detection.detect_peaks`
       * :py:func:`~spikeinterface.sortingcomponents.peak_selection.select_peaks`
       * :py:func:`~spikeinterface.sortingcomponents.peak_localization.localize_peaks`
-      * :py:func:`~spikeinterface.sortingcomponents.motion_estimation.estimate_motion`
-      * :py:func:`~spikeinterface.sortingcomponents.motion_interpolation.interpolate_motion`
+      * :py:func:`~spikeinterface.sortingcomponents.motion.motion_estimation.estimate_motion`
+      * :py:func:`~spikeinterface.sortingcomponents.motion.motion_interpolation.interpolate_motion`
 
 
     Possible presets : {}
@@ -282,8 +282,7 @@ def correct_motion(
     from spikeinterface.sortingcomponents.peak_detection import detect_peaks, detect_peak_methods
     from spikeinterface.sortingcomponents.peak_selection import select_peaks
     from spikeinterface.sortingcomponents.peak_localization import localize_peaks, localize_peak_methods
-    from spikeinterface.sortingcomponents.motion_estimation import estimate_motion
-    from spikeinterface.sortingcomponents.motion_interpolation import InterpolateMotionRecording
+    from spikeinterface.sortingcomponents.motion import estimate_motion, InterpolateMotionRecording
     from spikeinterface.core.node_pipeline import ExtractDenseWaveforms, run_node_pipeline
 
     # get preset params and update if necessary
diff --git a/src/spikeinterface/sortingcomponents/motion/__init__.py b/src/spikeinterface/sortingcomponents/motion/__init__.py
index e69de29bb2..2a045bd108 100644
--- a/src/spikeinterface/sortingcomponents/motion/__init__.py
+++ b/src/spikeinterface/sortingcomponents/motion/__init__.py
@@ -0,0 +1,4 @@
+from .motion_utils import Motion
+from .motion_estimation import estimate_motion
+from .motion_interpolation import (correct_motion_on_peaks, interpolate_motion_on_traces,
+                                   InterpolateMotionRecording, interpolate_motion)
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index fd56715fa9..b77b87d45a 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -15,15 +15,14 @@
 but here the original functions from Charlie, Julien and Erdem have been ported for an
 easier maintenance instead of making DREDge a dependency of spikeinterface.
 """
+import warnings
 
-# TODO
-# discuss the get_windows in dredge
-# remove get_motion_estimate() ???
-
-
+from tqdm.auto import trange
 import numpy as np
 
 
+from .motion_utils import Motion, get_windows, get_window_domains, scipy_conv1d
+
 def dredge_online_lfp(
     lfp_recording,
     rigid=True,
@@ -34,7 +33,7 @@ def dredge_online_lfp(
     win_step_um=800,
     win_scale_um=850,
     win_margin_um=None,
-    max_dt_s=None,
+    time_horizon_s=None,
     # weighting arguments
     mincorr=0.8,
     mincorr_percentile=None,
@@ -44,7 +43,7 @@ def dredge_online_lfp(
     thomas_kw=None,
     xcorr_kw=None,
     # misc
-    save_full=False,
+    extra_outputs=False,
     device=None,
     pbar=True,
 ):
@@ -67,7 +66,7 @@ def dredge_online_lfp(
         But, it can't be set too low or the algorithm doesn't have enough data
         to work with. The default is set assuming sampling rate of 250Hz, leading
         to 2500 samples per chunk.
-    max_dt_s : float
+    time_horizon_s : float
         Time-bins farther apart than this value in seconds will not be cross-correlated.
         Set this to at least `chunk_len_s`.
     max_disp_um : number, optional
@@ -121,9 +120,9 @@ def dredge_online_lfp(
         mincorr_percentile_nneighbs=mincorr_percentile_nneighbs,
         in_place=True,
         soft=soft,
-        # max_dt_s=weights_kw["max_dt_s"],  # max_dt not implemented for lfp at this point
-        max_dt_s=max_dt_s,
-        bin_s=1 / fs,  # only relevant for max_dt_s
+        # time_horizon_s=weights_kw["time_horizon_s"],  # max_dt not implemented for lfp at this point
+        time_horizon_s=time_horizon_s,
+        bin_s=1 / fs,  # only relevant for time_horizon_s
     )
 
     # get windows
@@ -138,7 +137,9 @@ def dredge_online_lfp(
         rigid=rigid,
     )
     B = len(windows)
-    extra = dict(window_centers=window_centers, windows=windows)
+
+    if extra_outputs:
+        extra = dict(window_centers=window_centers, windows=windows)
 
     # -- allocate output and initialize first chunk
     P_online = np.empty((B, T_total), dtype=np.float32)
@@ -155,7 +156,7 @@ def dredge_online_lfp(
         mincorr_percentile=mincorr_percentile,
         **threshold_kw,
     )
-    if save_full:
+    if extra_outputs:
         extra["D"] = [Ds0]
         extra["C"] = [Cs0]
         extra["S"] = [Ss0]
@@ -205,7 +206,7 @@ def dredge_online_lfp(
         )
         extra["mincorrs"].append(mincorr1)
 
-        if save_full:
+        if extra_outputs:
             extra["D"].append(Ds1)
             extra["C"].append(Cs1)
             extra["S"].append(Ss1)
@@ -230,17 +231,131 @@ def dredge_online_lfp(
         traces0 = traces1
 
     # -- convert to motion estimate and return
-    me = get_motion_estimate(
-        P_online,
-        time_bin_centers_s=lfp_recording.get_times(0),
-        spatial_bin_centers_um=window_centers,
+    motion = Motion(
+        displacement=[P_online],
+        temporal_bins_s=[lfp_recording.get_times(0)],
+        spatial_bin_um=[window_centers]
     )
-    return me, extra
+
+    if extra_outputs:
+        return motion, extra
+    else:
+        return motion
 
 
 
 # -- functions from dredgelib
 
+DEFAULT_LAMBDA_T = 1.0
+DEFAULT_EPS = 1e-3
+
+# -- linear algebra, Newton method solver, block tridiagonal (Thomas) solver
+
+
+def laplacian(n, wink=True, eps=DEFAULT_EPS, lambd=1.0, ridge_mask=None):
+    """Construct a discrete Laplacian operator (plus eps*identity)."""
+    lap = np.zeros((n, n))
+    if ridge_mask is None:
+        diag = lambd + eps
+    else:
+        diag = lambd + eps * ridge_mask
+    np.fill_diagonal(lap, diag)
+    if wink:
+        lap[0, 0] -= 0.5 * lambd
+        lap[-1, -1] -= 0.5 * lambd
+    # fill diagonal using a for loop for space reasons when this is large
+    for i in range(n - 1):
+        lap[i, i + 1] -= 0.5 * lambd
+        lap[i + 1, i] -= 0.5 * lambd
+    return lap
+
+
+
+def neg_hessian_likelihood_term(Ub, Ub_prevcur=None, Ub_curprev=None):
+    """Newton step coefficients
+
+    The negative Hessian of the non-regularized cost function inside a nonrigid block.
+    Together with the term arising from the regularization, this constructs the
+    coefficients matrix in our linear problem.
+    """
+    negHUb = -Ub - Ub.T
+    diagonal_terms = np.diagonal(negHUb) + Ub.sum(1) + Ub.sum(0)
+    if Ub_prevcur is None:
+        np.fill_diagonal(negHUb, diagonal_terms)
+    else:
+        diagonal_terms += Ub_prevcur.sum(0) + Ub_curprev.sum(1)
+        np.fill_diagonal(negHUb, diagonal_terms)
+    return negHUb
+
+
+def newton_rhs(
+    Db,
+    Ub,
+    Pb_prev=None,
+    Db_prevcur=None,
+    Ub_prevcur=None,
+    Db_curprev=None,
+    Ub_curprev=None,
+):
+    """Newton step right hand side
+
+    The gradient at P=0 of the cost function, which is the right hand side of Newton's method.
+    """
+    UDb = Ub * Db
+    grad_at_0 = UDb.sum(1) - UDb.sum(0)
+
+    # batch case
+    if Pb_prev is None:
+        return grad_at_0
+
+    # online case
+    align_term = (Ub_prevcur.T + Ub_curprev) @ Pb_prev
+    rhs = (
+        align_term
+        + grad_at_0
+        + (Ub_curprev * Db_curprev).sum(1)
+        - (Ub_prevcur * Db_prevcur).sum(0)
+    )
+
+    return rhs
+
+
+def newton_solve_rigid(
+    D,
+    U,
+    Sigma0inv,
+    Pb_prev=None,
+    Db_prevcur=None,
+    Ub_prevcur=None,
+    Db_curprev=None,
+    Ub_curprev=None,
+):
+    """Solve the rigid Newton step
+
+    D is TxT displacement, U is TxT subsampling or soft weights matrix.
+    """
+    from scipy.linalg import solve, lstsq
+
+    negHU = neg_hessian_likelihood_term(
+        U,
+        Ub_prevcur=Ub_prevcur,
+        Ub_curprev=Ub_curprev,
+    )
+    targ = newton_rhs(
+        D,
+        U,
+        Pb_prev=Pb_prev,
+        Db_prevcur=Db_prevcur,
+        Ub_prevcur=Ub_prevcur,
+        Db_curprev=Db_curprev,
+        Ub_curprev=Ub_curprev,
+    )
+    try:
+        p = solve(Sigma0inv + negHU, targ, assume_a="pos")
+    except np.linalg.LinAlgError:
+        warnings.warn("Singular problem, using least squares.")
+        p, *_ = lstsq(Sigma0inv + negHU, targ)
+    return p, negHU
 
 
 def thomas_solve(
@@ -274,6 +389,8 @@ def thomas_solve(
     online case. The return value will be the new chunk's displacement estimate,
     solving the online registration problem.
     """
+    from scipy.linalg import solve
+
     Ds = np.asarray(Ds, dtype=np.float64)
     Us = np.asarray(Us, dtype=np.float64)
     online = P_prev is not None
@@ -376,7 +493,7 @@ def threshold_correlation_matrix(
     mincorr=0.0,
     mincorr_percentile=None,
     mincorr_percentile_nneighbs=20,
-    max_dt_s=0,
+    time_horizon_s=0,
     in_place=False,
     bin_s=1,
     t_offset_bins=None,
@@ -407,17 +524,17 @@ def threshold_correlation_matrix(
         else:
             Ss = (Cs >= mincorr).astype(Cs.dtype)
     if (
-        max_dt_s is not None
-        and max_dt_s > 0
+        time_horizon_s is not None
+        and time_horizon_s > 0
         and T is not None
-        and max_dt_s < T
+        and time_horizon_s < T
     ):
         tt0 = bin_s * np.arange(T)
         tt1 = tt0
         if t_offset_bins:
             tt1 = tt0 + t_offset_bins
         dt = tt1[:, None] - tt0[None, :]
-        mask = (np.abs(dt) <= max_dt_s).astype(Ss.dtype)
+        mask = (np.abs(dt) <= time_horizon_s).astype(Ss.dtype)
         Ss *= mask[None]
     return Ss, mincorr
 
@@ -443,6 +560,8 @@ def xcorr_windows(
     Compute pairwise (time x time) maximum cross-correlation and displacement
     matrices in each nonrigid window.
     """
+    import torch
+
     if device is None:
         device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
 
@@ -546,6 +665,8 @@ def calc_corr_decent_pair(
     device : torch device
     Returns: D, C: TxT arrays
     """
+    import torch
+
     D, Ta = raster_a.shape
     D_, Tb = raster_b.shape
 
@@ -601,4 +722,148 @@ def calc_corr_decent_pair(
             D[i : i + batch_size, j : j + batch_size] = best_disp.T
             C[i : i + batch_size, j : j + batch_size] = max_corr.cpu().T
 
-    return D, C
\ No newline at end of file
+    return D, C
+
+
+# TODO charlie sam : at the moment this is a duplicate with small differences see motion_estimate.py same function
+def normxcorr1d(
+    template,
+    x,
+    weights=None,
+    xmasks=None,
+    centered=True,
+    normalized=True,
+    padding="same",
+    conv_engine="torch",
+):
+    """normxcorr1d: Normalized cross-correlation, optionally weighted
+
+    The API is like torch's F.conv1d, except I have accidentally
+    changed the position of input/weights -- template acts like weights,
+    and x acts like input.
+
+    Returns the cross-correlation of `template` and `x` at spatial lags
+    determined by `mode`. Useful for estimating the location of `template`
+    within `x`.
+
+    This might not be the most efficient implementation -- ideas welcome.
+    It uses a direct convolutional translation of the formula
+        corr = (E[XY] - EX EY) / sqrt(var X * var Y)
+
+    This also supports weights! In that case, the usual adaptation of
+    the above formula is made to the weighted case -- and all of the
+    normalizations are done per block in the same way.
+
+    Arguments
+    ---------
+    template : tensor, shape (num_templates, length)
+        The reference template signal
+    x : tensor, 1d shape (length,) or 2d shape (num_inputs, length)
+        The signal in which to find `template`
+    weights : tensor, shape (length,)
+        Will use weighted means, variances, covariances if supplied.
+    centered : bool
+        If true, means will be subtracted (per weighted patch).
+    normalized : bool
+        If true, normalize by the variance (per weighted patch).
+    padding : int, optional
+        How far to look? if unset, we'll use half the length
+    conv_engine : string, one of "torch", "numpy"
+        What library to use for computing cross-correlations.
+        If numpy, falls back to the scipy correlate function.
+
+    Returns
+    -------
+    corr : tensor
+    """
+
+
+    if conv_engine == "torch":
+        import torch
+        import torch.nn.functional as F
+        conv1d = F.conv1d
+        npx = torch
+    elif conv_engine == "numpy":
+        conv1d = scipy_conv1d
+        npx = np
+    else:
+        raise ValueError(f"Unknown conv_engine {conv_engine}")
+
+    x = npx.atleast_2d(x)
+    num_templates, lengtht = template.shape
+    num_inputs, lengthx = x.shape
+
+    # generalize over weighted / unweighted case
+    device_kw = {} if conv_engine == "numpy" else dict(device=x.device)
+    if xmasks is None:
+        onesx = npx.ones((1, 1, lengthx), dtype=x.dtype, **device_kw)
+        wx = x[:, None, :]
+    else:
+        assert xmasks.shape == x.shape
+        onesx = xmasks[:, None, :]
+        wx = x[:, None, :] * onesx
+    no_weights = weights is None
+    if no_weights:
+        weights = npx.ones((1, 1, lengtht), dtype=x.dtype, **device_kw)
+        wt = template[:, None, :]
+    else:
+        if weights.shape == (lengtht,):
+            weights = weights[None, None]
+        elif weights.shape == (num_templates, lengtht):
+            weights = weights[:, None, :]
+        else:
+            assert False
+        wt = template[:, None, :] * weights
+    x = x[:, None, :]
+    template = template[:, None, :]
+
+    # conv1d valid rule:
+    # (B,1,L),(O,1,L)->(B,O,L)
+    # below, we always put x on the LHS, templates on the RHS, so this reads
+    # (num_inputs, 1, lengthx), (num_templates, 1, lengtht) -> (num_inputs, num_templates, length_out)
+
+    # compute expectations
+    # how many points in each window? seems necessary to normalize
+    # for numerical stability.
+    Nx = conv1d(onesx, weights, padding=padding)  # 1,nt,l
+    empty = Nx == 0
+    Nx[empty] = 1
+    if centered:
+        Et = conv1d(onesx, wt, padding=padding)  # 1,nt,l
+        Et /= Nx
+        Ex = conv1d(wx, weights, padding=padding)  # nx,nt,l
+        Ex /= Nx
+
+    # compute (weighted) covariance
+    # important: the formula E[XY] - EX EY is well-suited here,
+    # because the means are naturally subtracted correctly
+    # patch-wise. you couldn't pre-subtract them!
+    cov = conv1d(wx, wt, padding=padding)
+    cov /= Nx
+    if centered:
+        cov -= Ex * Et
+
+    # compute variances for denominator, using var X = E[X^2] - (EX)^2
+    if normalized:
+        var_template = conv1d(
+            onesx, wt * template, padding=padding
+        )
+        var_template /= Nx
+        var_x = conv1d(wx * x, weights, padding=padding)
+        var_x /= Nx
+        if centered:
+            var_template -= npx.square(Et)
+            var_x -= npx.square(Ex)
+
+        # fill in zeros to avoid problems when dividing
+        var_template[var_template <= 0] = 1
+        var_x[var_x <= 0] = 1
+
+    # now find the final normxcorr
+    corr = cov  # renaming for clarity
+    if normalized:
+        corr[torch.broadcast_to(empty, corr.shape)] = 0
+        corr /= npx.sqrt(var_x)
+        corr /= npx.sqrt(var_template)
+
+    return corr
\ No newline at end of file
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
index 42fd12383d..1933239619 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
@@ -4,8 +4,8 @@
 import numpy as np
 
 
-from .motion_utils import Motion
-from .tools import make_multi_method_doc
+from .motion_utils import Motion, get_windows, scipy_conv1d
+from spikeinterface.sortingcomponents.tools import make_multi_method_doc
 
 try:
     import torch
@@ -32,7 +32,7 @@ def estimate_motion(
     speed_threshold=30,
     sigma_smooth_s=None,
     method="decentralized",
-    output_extra_check=False,
+    extra_outputs=False,
     progress_bar=False,
     upsample_to_histogram_bin=False,
     verbose=False,
@@ -90,7 +90,7 @@ def estimate_motion(
     sigma_smooth_s: None or float
         Optional smooting gaussian kernel when not None
 
-    output_extra_check: bool, default: False
+    extra_outputs: bool, default: False
         If True then return an extra dict that contains variables
         to check intermediate steps (motion_histogram, non_rigid_windows, pairwise_displacement)
     upsample_to_histogram_bin: bool or None, default: False
@@ -109,17 +109,17 @@ def estimate_motion(
     -------
     motion: Motion object
         The motion object.
-    extra_check: dict
-        Optional output if `output_extra_check=True`
+    extra: dict
+        Optional output if `extra_outputs=True`
         This dict contain histogram, pairwise_displacement usefull for ploting.
     """
     # TODO handle multi segment one day
     assert recording.get_num_segments() == 1
 
-    if output_extra_check:
-        extra_check = {}
+    if extra_outputs:
+        extra = {}
     else:
-        extra_check = None
+        extra = None
 
     # contact positions
     probe = recording.get_probe()
@@ -131,11 +131,11 @@ def estimate_motion(
 
     # get windows
     non_rigid_windows, non_rigid_window_centers = get_windows(
-        rigid, bin_um, contact_pos, spatial_bin_edges, margin_um, win_step_um, win_sigma_um, win_shape
+        rigid, contact_pos, spatial_bin_edges, margin_um, win_step_um, win_sigma_um, win_shape
     )
 
-    if output_extra_check:
-        extra_check["non_rigid_windows"] = non_rigid_windows
+    if extra_outputs:
+        extra["non_rigid_windows"] = non_rigid_windows
 
     # run method
     method_class = estimate_motion_methods[method]
@@ -150,7 +150,7 @@ def estimate_motion(
         non_rigid_windows,
         verbose,
         progress_bar,
-        extra_check,
+        extra,
         **method_kwargs,
     )
 
@@ -165,8 +165,8 @@ def estimate_motion(
     if upsample_to_histogram_bin is None:
         upsample_to_histogram_bin = not rigid
     if upsample_to_histogram_bin:
-        extra_check["motion_array"] = motion_array
-        extra_check["non_rigid_window_centers"] = non_rigid_window_centers
+        extra["motion_array"] = motion_array
+        extra["non_rigid_window_centers"] = non_rigid_window_centers
         non_rigid_windows = np.array(non_rigid_windows)
         non_rigid_windows /= non_rigid_windows.sum(axis=0, keepdims=True)
         non_rigid_window_centers = spatial_bin_edges[:-1] + bin_um / 2
@@ -175,8 +175,8 @@ def estimate_motion(
     # TODO handle multi segment
     motion = Motion([motion_array], [temporal_bins], non_rigid_window_centers, direction=direction)
 
-    if output_extra_check:
-        return motion, extra_check
+    if extra_outputs:
+        return motion, extra
     else:
         return motion
 
@@ -270,7 +270,7 @@ def run(
         non_rigid_windows,
         verbose,
         progress_bar,
-        extra_check,
+        extra,
         histogram_depth_smooth_um=None,
         histogram_time_smooth_s=None,
         pairwise_displacement_method="conv",
@@ -329,11 +329,11 @@ def run(
             smooth_kernel /= np.sum(smooth_kernel)
             motion_histogram = scipy.signal.fftconvolve(motion_histogram, smooth_kernel[:, None], mode="same", axes=0)
 
-        if extra_check is not None:
-            extra_check["motion_histogram"] = motion_histogram
-            extra_check["pairwise_displacement_list"] = []
-            extra_check["temporal_hist_bin_edges"] = temporal_hist_bin_edges
-            extra_check["spatial_hist_bin_edges"] = spatial_hist_bin_edges
+        if extra is not None:
+            extra["motion_histogram"] = motion_histogram
+            extra["pairwise_displacement_list"] = []
+            extra["temporal_hist_bin_edges"] = temporal_hist_bin_edges
+            extra["spatial_hist_bin_edges"] = spatial_hist_bin_edges
 
         # temporal bins are bin center
         temporal_bins = 0.5 * (temporal_hist_bin_edges[1:] + temporal_hist_bin_edges[:-1])
@@ -378,8 +378,8 @@ def run(
                 all_pairwise_displacements[i] = pairwise_displacement
                 all_pairwise_displacement_weights[i] = pairwise_displacement_weight
 
-            if extra_check is not None:
-                extra_check["pairwise_displacement_list"].append(pairwise_displacement)
+            if extra is not None:
+                extra["pairwise_displacement_list"].append(pairwise_displacement)
 
             if verbose:
                 print(f"Computing global displacement: {i + 1} / {len(non_rigid_windows)}")
@@ -496,7 +496,7 @@ def run(
         non_rigid_windows,
         verbose,
         progress_bar,
-        extra_check,
+        extra,
         num_amp_bins=20,
         num_shifts_global=15,
         num_iterations=10,
@@ -535,12 +535,12 @@ def run(
         # convert to um
         motion = -(shift_indices * bin_um)
 
-        if extra_check:
-            extra_check["motion_histograms"] = motion_histograms
-            extra_check["target_histogram"] = target_histogram
-            extra_check["shift_covs_block"] = shift_covs_block
-            extra_check["temporal_hist_bin_edges"] = temporal_hist_bin_edges
-            extra_check["spatial_hist_bin_edges"] = spatial_hist_bin_edges
+        if extra:
+            extra["motion_histograms"] = motion_histograms
+            extra["target_histogram"] = target_histogram
+            extra["shift_covs_block"] = shift_covs_block
+            extra["temporal_hist_bin_edges"] = temporal_hist_bin_edges
+            extra["spatial_hist_bin_edges"] = spatial_hist_bin_edges
 
         return motion, temporal_bins
 
@@ -564,82 +564,7 @@ def get_spatial_bin_edges(recording, direction, margin_um, bin_um):
     return spatial_bins
 
 
-def get_windows(rigid, bin_um, contact_pos, spatial_bin_edges, margin_um, win_step_um, win_sigma_um, win_shape):
-    """
-    Generate spatial windows (taper) for non-rigid motion.
-    For rigid motion, this is equivalent to have one unique rectangular window that covers the entire probe.
-    The windowing can be gaussian or rectangular.
 
-    Parameters
-    ----------
-    rigid : bool
-        If True, returns a single rectangular window
-    bin_um : float
-        Spatial bin size in um
-    contact_pos : np.ndarray
-        Position of electrodes (num_channels, 2)
-    spatial_bin_edges : np.array
-        The pre-computed spatial bin edges
-    margin_um : float
-        The margin to extend (if positive) or shrink (if negative) the probe dimension to compute windows.=
-    win_step_um : float
-        The steps at which windows are defined
-    win_sigma_um : float
-        Sigma of gaussian window (if win_shape is gaussian)
-    win_shape : float
-        "gaussian" | "rect"
-
-    Returns
-    -------
-    non_rigid_windows : list of 1D arrays
-        The scaling for each window. Each element has num_spatial_bins values
-    non_rigid_window_centers: 1D np.array
-        The center of each window
-
-    Notes
-    -----
-    Note that kilosort2.5 uses overlaping rectangular windows.
-    Here by default we use gaussian window.
-
-    """
-    # TODO remove bin_um
-    bin_centers = spatial_bin_edges[:-1] + bin_um / 2.0
-    # bin_centers = 0.5 * (spatial_bin_edges[1:] + spatial_bin_edges[:-1])
-    n = bin_centers.size
-
-    if rigid:
-        # win_shape = 'rect' is forced
-        non_rigid_windows = [np.ones(n, dtype="float64")]
-        middle = (spatial_bin_edges[0] + spatial_bin_edges[-1]) / 2.0
-        non_rigid_window_centers = np.array([middle])
-    else:
-        # TODO put a warning
-        assert win_sigma_um >= win_step_um, f"win_sigma_um too low {win_sigma_um} compared to win_step_um {win_step_um}"
-
-        min_ = np.min(contact_pos) - margin_um
-        max_ = np.max(contact_pos) + margin_um
-        num_non_rigid_windows = int((max_ - min_) // win_step_um)
-        border = ((max_ - min_) % win_step_um) / 2
-        non_rigid_window_centers = np.arange(num_non_rigid_windows + 1) * win_step_um + min_ + border
-        non_rigid_windows = []
-
-        for win_center in non_rigid_window_centers:
-            if win_shape == "gaussian":
-                win = np.exp(-((bin_centers - win_center) ** 2) / (2 * win_sigma_um**2))
-            elif win_shape == "rect":
-                win = np.abs(bin_centers - win_center) < (win_sigma_um / 2.0)
-                win = win.astype("float64")
-            elif win_shape == "triangle":
-                center_dist = np.abs(bin_centers - win_center)
-                in_window = center_dist <= (win_sigma_um / 2.0)
-                win = -center_dist
-                win[~in_window] = 0
-                win[in_window] -= win[in_window].min()
-                win[in_window] /= win[in_window].max()
-
-            non_rigid_windows.append(win)
-
-    return non_rigid_windows, non_rigid_window_centers
 
 
 def make_2d_motion_histogram(
@@ -1325,6 +1250,9 @@ def iterative_template_registration(
     return optimal_shift_indices, target_spikecount_hist, shift_covs_block
 
 
+# TODO charlie sam : make a unique function for this
+# at the moment this is the legacy one ported in spikeinterface
+# the one in deredge.py is more recent
 def normxcorr1d(
     template,
     x,
@@ -1444,33 +1372,7 @@ def normxcorr1d(
     return corr
 
 
-def scipy_conv1d(input, weights, padding="valid"):
-    """SciPy translation of torch F.conv1d"""
-    from scipy.signal import correlate
-
-    n, c_in, length = input.shape
-    c_out, in_by_groups, kernel_size = weights.shape
-    assert in_by_groups == c_in == 1
-
-    if padding == "same":
-        mode = "same"
-        length_out = length
-    elif padding == "valid":
-        mode = "valid"
-        length_out = length - 2 * (kernel_size // 2)
-    elif isinstance(padding, int):
-        mode = "valid"
-        input = np.pad(input, [*[(0, 0)] * (input.ndim - 1), (padding, padding)])
-        length_out = length - (kernel_size - 1) + 2 * padding
-    else:
-        raise ValueError(f"Unknown 'padding' value of {padding}, 'padding' must be 'same', 'valid' or an integer")
-
-    output = np.zeros((n, c_out, length_out), dtype=input.dtype)
-    for m in range(n):
-        for c in range(c_out):
-            output[m, c] = correlate(input[m, 0], weights[c, 0], mode=mode)
 
-    return output
 
 
 def clean_motion_vector(motion, temporal_bins, bin_duration_s, speed_threshold=30, sigma_smooth_s=None):
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index 26d4b35b1a..30c3deb0ec 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -1,3 +1,4 @@
+import warnings
 import json
 from pathlib import Path
 
@@ -228,3 +229,125 @@ def copy(self):
             self.spatial_bins_um.copy(),
             interpolation_method=self.interpolation_method,
         )
+
+
+
+def get_windows(rigid, contact_pos, spatial_bin_edges, margin_um, win_step_um, win_sigma_um, win_shape,
+                zero_threshold=None):
+    """
+    Generate spatial windows (taper) for non-rigid motion.
+    For rigid motion, this is equivalent to have one unique rectangular window that covers the entire probe.
+    The windowing can be gaussian or rectangular.
+
+    Parameters
+    ----------
+    rigid : bool
+        If True, returns a single rectangular window
+    contact_pos : np.ndarray
+        Position of electrodes (num_channels, 2)
+    spatial_bin_edges : np.array
+        The pre-computed spatial bin edges
+    margin_um : float
+        The margin to extend (if positive) or shrink (if negative) the probe dimension to compute windows.=
+    win_step_um : float
+        The steps at which windows are defined
+    win_sigma_um : float
+        Sigma of gaussian window (if win_shape is gaussian)
+    win_shape : float
+        "gaussian" | "rect"
+
+    Returns
+    -------
+    windows : 2D arrays
+        The scaling for each window. Each element has num_spatial_bins values
+        shape: (num_window, spatial_bins)
+    window_centers: 1D np.array
+        The center of each window
+
+    Notes
+    -----
+    Note that kilosort2.5 uses overlaping rectangular windows.
+    Here by default we use gaussian window.
+
+    """
+    bin_centers = 0.5 * (spatial_bin_edges[1:] + spatial_bin_edges[:-1])
+    n = bin_centers.size
+
+    if rigid:
+        # win_shape = 'rect' is forced
+        windows = [np.ones(n, dtype="float64")]
+        middle = (spatial_bin_edges[0] + spatial_bin_edges[-1]) / 2.0
+        window_centers = np.array([middle])
+    else:
+        if win_sigma_um <= win_step_um/5.:
+            warnings.warn(
+                f"get_windows(): spatial windows are probably not overlaping because {win_sigma_um=} and {win_step_um=}"
+            )
+
+        min_ = np.min(contact_pos) - margin_um
+        max_ = np.max(contact_pos) + margin_um
+        num_windows = int((max_ - min_) // win_step_um)
+        border = ((max_ - min_) % win_step_um) / 2
+        window_centers = np.arange(num_windows + 1) * win_step_um + min_ + border
+        windows = []
+
+        for win_center in window_centers:
+            if win_shape == "gaussian":
+                win = np.exp(-((bin_centers - win_center) ** 2) / (2 * win_sigma_um**2))
+            elif win_shape == "rect":
+                win = np.abs(bin_centers - win_center) < (win_sigma_um / 2.0)
+                win = win.astype("float64")
+            elif win_shape == "triangle":
+                center_dist = np.abs(bin_centers - win_center)
+                in_window = center_dist <= (win_sigma_um / 2.0)
+                win = -center_dist
+                win[~in_window] = 0
+                win[in_window] -= win[in_window].min()
+                win[in_window] /= win[in_window].max()
+            windows.append(win)
+
+    windows = np.array(windows)
+
+    if zero_threshold is not None:
+        windows[windows < zero_threshold] = 0
+        windows /= windows.sum(axis=1, keepdims=True)
+
+    return windows, window_centers
+
+
+def get_window_domains(windows):
+    """Array of windows -> list of slices where window > 0."""
+    slices = []
+    for w in windows:
+        in_window = np.flatnonzero(w)
+        slices.append(slice(in_window[0], in_window[-1] + 1))
+    return slices
+
+
+def scipy_conv1d(input, weights, padding="valid"):
+    """SciPy translation of torch F.conv1d"""
+    from scipy.signal import correlate
+
+    n, c_in, length = input.shape
+    c_out, in_by_groups, kernel_size = weights.shape
+    assert in_by_groups == c_in == 1
+
+    if padding == "same":
+        mode = "same"
+        length_out = length
+    elif padding == "valid":
+        mode = "valid"
+        length_out = length - 2 * (kernel_size // 2)
+    elif isinstance(padding, int):
+        mode = "valid"
+        input = np.pad(input, [*[(0, 0)] * (input.ndim - 1), (padding, padding)])
+        length_out = length - (kernel_size - 1) + 2 * padding
+    else:
+        raise ValueError(f"Unknown 'padding' value of {padding}, 'padding' must be 'same', 'valid' or an integer")
+
+    output = np.zeros((n, c_out, length_out), dtype=input.dtype)
+    for m in range(n):
+        for c in range(c_out):
+            output[m, c] = correlate(input[m, 0], weights[c, 0], mode=mode)
+
+    return output
\ No newline at end of file
diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
index af62ba52ec..7cba0ff6fc 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
@@ -3,7 +3,7 @@
 import numpy as np
 import pytest
 from spikeinterface.core.node_pipeline import ExtractDenseWaveforms
-from spikeinterface.sortingcomponents.motion_estimation import estimate_motion
+from spikeinterface.sortingcomponents.motion import estimate_motion
 from spikeinterface.sortingcomponents.peak_detection import detect_peaks
 from spikeinterface.sortingcomponents.peak_localization import LocalizeCenterOfMass
 from spikeinterface.sortingcomponents.tests.common import make_dataset
@@ -18,12 +18,10 @@
     plt.show()
 
 
-@pytest.fixture(scope="module")
-def setup_module(tmp_path_factory):
-    recording, sorting = make_dataset()
-    cache_folder = tmp_path_factory.mktemp("cache_folder")
+def setup_module(cache_folder):
     cache_folder.mkdir(parents=True, exist_ok=True)
 
+    recording, sorting = make_dataset()
     # detect and localize
     extract_dense_waveforms = ExtractDenseWaveforms(recording, ms_before=0.1, ms_after=0.3, return_output=False)
     pipeline_nodes = [
@@ -49,6 +47,12 @@ def setup_module(tmp_path_factory):
     return recording, sorting, cache_folder
 
 
+@pytest.fixture(scope="module", name="setup_module")
+def setup_module_fixture(tmp_path_factory):
+    cache_folder = tmp_path_factory.mktemp("cache_folder")
+    return setup_module(cache_folder)
+
+
 def test_estimate_motion(setup_module):
     # recording, sorting = make_dataset()
     recording, sorting, cache_folder = setup_module
@@ -215,5 +219,8 @@ def test_estimate_motion(setup_module):
 
 
 if __name__ == "__main__":
-    setup_module()
-    test_estimate_motion()
+    import tempfile
+    with tempfile.TemporaryDirectory() as tmpdirname:
+        cache_folder = Path(tmpdirname)
+    args = setup_module(cache_folder)
+    test_estimate_motion(args)

From cabbbeb26c1f35077f326df9b39fe4984bb11ebc Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 21 Jun 2024 15:06:41 +0200
Subject: [PATCH 04/31] dredge test file

---
 .../sortingcomponents/motion/tests/test_drege.py      | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 src/spikeinterface/sortingcomponents/motion/tests/test_drege.py

diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_drege.py b/src/spikeinterface/sortingcomponents/motion/tests/test_drege.py
new file mode 100644
index 0000000000..218d9036aa
--- /dev/null
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_drege.py
@@ -0,0 +1,11 @@
+import pytest
+
+
+
+
+def test_dredge_online_lfp():
+    pass
+
+
+if __name__ == "__main__":
+    pass

From 00bef349e5cb6f8dabffd3c323fd44262d402670 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 21 Jun 2024 16:33:42 +0200
Subject: [PATCH 05/31] fix

---
 .../sortingcomponents/motion/dredge.py               | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index b77b87d45a..d7825bf4a7 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -127,15 +127,17 @@ def dredge_online_lfp(
 
     # get windows
     windows, window_centers = get_windows(
-        geom,
-        win_step_um,
-        win_scale_um,
-        spatial_bin_centers=geom[:, 1],
+        rigid=rigid, 
+        contact_pos=geom,
+        # TODO check dim and direction and assert unique
+        spatial_bin_edges=geom[:, 1],
         margin_um=win_margin_um,
+        win_step_um=win_step_um,
+        win_sigma_um=win_scale_um,
         win_shape=win_shape,
         zero_threshold=1e-5,
-        rigid=rigid,
     )
+
     B = len(windows)
 
     if extra_outputs:

From 62c75f870487bdf38808be4712b05e3f7e223b20 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 21 Jun 2024 20:18:00 +0200
Subject: [PATCH 06/31] Put spatial_bin_centers in get_windows()

---
 .../sortingcomponents/motion/dredge.py        | 23 +++++++++----------
 .../motion/motion_estimation.py               |  3 ++-
 .../sortingcomponents/motion/motion_utils.py  | 17 +++++++-------
 3 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index d7825bf4a7..6bbf3139e1 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -125,12 +125,14 @@ def dredge_online_lfp(
         bin_s=1 / fs,  # only relevant for time_horizon_s
     )
 
-    # get windows
+    # in LFP bin center are contact position
+    # TODO check dim and direction and assert unique
+    spatial_bin_centers = geom[:, 1]
+
     windows, window_centers = get_windows(
         rigid=rigid, 
         contact_pos=geom,
-        # TODO check dim and direction and assert unique
-        spatial_bin_edges=geom[:, 1],
+        spatial_bin_centers=spatial_bin_centers,
         margin_um=win_margin_um,
         win_step_um=win_step_um,
         win_sigma_um=win_scale_um,
@@ -165,8 +167,9 @@ def dredge_online_lfp(
         extra["D01"] = []
         extra["C01"] = []
         extra["S01"] = []
-    extra["mincorrs"] = [mincorr0]
-    extra["max_disp_um"] = max_disp_um
+        extra["mincorrs"] = [mincorr0]
+        extra["max_disp_um"] = max_disp_um
+
     P_online[:, t0:t1], _ = thomas_solve(Ds0, Ss0, **thomas_kw)
 
     # -- loop through chunks
@@ -206,9 +209,10 @@ def dredge_online_lfp(
         Ss10, _ = threshold_correlation_matrix(
             Cs10, mincorr=mincorr1, t_offset_bins=T_chunk, **threshold_kw
         )
-        extra["mincorrs"].append(mincorr1)
+        
 
         if extra_outputs:
+            extra["mincorrs"].append(mincorr1)
             extra["D"].append(Ds1)
             extra["C"].append(Cs1)
             extra["S"].append(Ss1)
@@ -232,12 +236,7 @@ def dredge_online_lfp(
         t0, t1 = t1, t2
         traces0 = traces1
 
-    # -- convert to motion estimate and return
-    motion = Motion(
-        displacement=[P_online],
-        temporal_bins_s=[lfp_recording.get_times(0)],
-        spatial_bin_um=[window_centers]
-    )
+    motion = Motion([P_online.T], [lfp_recording.get_times(0)], window_centers, direction="y")
 
     if extra_outputs:
         return motion, extra
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
index 1933239619..f0c01a005e 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
@@ -128,10 +128,11 @@ def estimate_motion(
 
     # spatial bins
     spatial_bin_edges = get_spatial_bin_edges(recording, direction, margin_um, bin_um)
+    spatial_bin_centers = 0.5 * (spatial_bin_edges[1:] + spatial_bin_edges[:-1])
 
     # get windows
     non_rigid_windows, non_rigid_window_centers = get_windows(
-        rigid, contact_pos, spatial_bin_edges, margin_um, win_step_um, win_sigma_um, win_shape
+        rigid, contact_pos, spatial_bin_centers, margin_um, win_step_um, win_sigma_um, win_shape
     )
 
     if extra_outputs:
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index 30c3deb0ec..5987a47cd2 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -232,7 +232,7 @@ def copy(self):
 
 
 
-def get_windows(rigid, contact_pos, spatial_bin_edges, margin_um, win_step_um, win_sigma_um, win_shape,
+def get_windows(rigid, contact_pos, spatial_bin_centers, margin_um, win_step_um, win_sigma_um, win_shape,
                 zero_threshold=None):
     """
     Generate spatial windows (taper) for non-rigid motion.
@@ -245,8 +245,8 @@ def get_windows(rigid, contact_pos, spatial_bin_edges, margin_um, win_step_um, w
         If True, returns a single rectangular window
     contact_pos : np.ndarray
         Position of electrodes (num_channels, 2)
-    spatial_bin_edges : np.array
-        The pre-computed spatial bin edges
+    spatial_bin_centers : np.array
+        The pre-computed spatial bin centers
     margin_um : float
         The margin to extend (if positive) or shrink (if negative) the probe dimension to compute windows.=
     win_step_um : float
@@ -270,13 +270,12 @@ def get_windows(rigid, contact_pos, spatial_bin_edges, margin_um, win_step_um, w
     Here by default we use gaussian window.
 
     """
-    bin_centers = 0.5 * (spatial_bin_edges[1:] + spatial_bin_edges[:-1])
-    n = bin_centers.size
+    n = spatial_bin_centers.size
 
     if rigid:
         # win_shape = 'rect' is forced
         windows = [np.ones(n, dtype="float64")]
-        middle = (spatial_bin_edges[0] + spatial_bin_edges[-1]) / 2.0
+        middle = (spatial_bin_centers[0] + spatial_bin_centers[-1]) / 2.0
         window_centers = np.array([middle])
     else:
         if win_sigma_um <= win_step_um/5.:
@@ -293,12 +292,12 @@ def get_windows(rigid, contact_pos, spatial_bin_edges, margin_um, win_step_um, w
 
         for win_center in window_centers:
             if win_shape == "gaussian":
-                win = np.exp(-((bin_centers - win_center) ** 2) / (2 * win_sigma_um**2))
+                win = np.exp(-((spatial_bin_centers - win_center) ** 2) / (2 * win_sigma_um**2))
             elif win_shape == "rect":
-                win = np.abs(bin_centers - win_center) < (win_sigma_um / 2.0)
+                win = np.abs(spatial_bin_centers - win_center) < (win_sigma_um / 2.0)
                 win = win.astype("float64")
             elif win_shape == "triangle":
-                center_dist = np.abs(bin_centers - win_center)
+                center_dist = np.abs(spatial_bin_centers - win_center)
                 in_window = center_dist <= (win_sigma_um / 2.0)
                 win = -center_dist
                 win[~in_window] = 0

From 13c81ac6985a7a5295c7668b6b6053740a4e15e6 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 21 Jun 2024 21:22:08 +0200
Subject: [PATCH 07/31] small fix

---
 src/spikeinterface/sortingcomponents/motion/dredge.py | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 6bbf3139e1..56770dbf63 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -92,10 +92,8 @@ def dredge_online_lfp(
 
     Returns
     -------
-    me : motion_util.MotionEstimate
-        A motion estimate object. me.displacement is the displacement trace, but this object
-        includes methods for getting the displacement at different times and depths; see
-        the documentation in the motion_util.py file.
+    motion : Motion
+        A motion object.
     extra : dict
         Dict containing extra info for debugging
     """
@@ -126,7 +124,7 @@ def dredge_online_lfp(
     )
 
     # in LFP bin center are contact position
-    # TODO check dim and direction and assert unique
+    # TODO sam check dim and direction and assert unique
     spatial_bin_centers = geom[:, 1]
 
     windows, window_centers = get_windows(

From 1ac451cecb24e7f130dad941837f83079e0481de Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 26 Jun 2024 14:18:43 +0200
Subject: [PATCH 08/31] motion_estimation() : refactoring party. Move method
 into separated files. Change, refactor (and rename some) kwargs from common
 to specific methos. Add dredge_lfp class.

---
 src/spikeinterface/preprocessing/motion.py    |   10 +-
 .../tests/test_benchmark_motion_estimation.py |    2 +-
 .../sortingcomponents/motion/__init__.py      |    1 +
 .../sortingcomponents/motion/decentralized.py |  814 ++++++++++
 .../sortingcomponents/motion/dredge.py        |  132 +-
 .../motion/iterative_template.py              |  287 ++++
 .../motion/motion_cleaner.py                  |   73 +
 .../motion/motion_estimation.py               | 1429 +----------------
 .../sortingcomponents/motion/motion_utils.py  |  195 ++-
 .../motion/tests/test_motion_estimation.py    |    4 +-
 .../motion/tests/test_motion_utils.py         |    2 +-
 11 files changed, 1543 insertions(+), 1406 deletions(-)
 create mode 100644 src/spikeinterface/sortingcomponents/motion/decentralized.py
 create mode 100644 src/spikeinterface/sortingcomponents/motion/iterative_template.py
 create mode 100644 src/spikeinterface/sortingcomponents/motion/motion_cleaner.py

diff --git a/src/spikeinterface/preprocessing/motion.py b/src/spikeinterface/preprocessing/motion.py
index 1e825f9c73..ed097d19fc 100644
--- a/src/spikeinterface/preprocessing/motion.py
+++ b/src/spikeinterface/preprocessing/motion.py
@@ -40,10 +40,10 @@
             margin_um=0.0,
             # win_shape="gaussian",
             # win_step_um=50.0,
-            # win_sigma_um=150.0,
+            # win_scale_um=150.0,
             win_shape="gaussian",
             win_step_um=100.0,
-            win_sigma_um=200.0,
+            win_scale_um=200.0,
             histogram_depth_smooth_um=5.0,
             histogram_time_smooth_s=None,
             pairwise_displacement_method="conv",
@@ -99,10 +99,10 @@
             margin_um=0.0,
             # win_shape="gaussian",
             # win_step_um=50.0,
-            # win_sigma_um=150.0,
+            # win_scale_um=150.0,
             win_shape="gaussian",
             win_step_um=100.0,
-            win_sigma_um=200.0,
+            win_scale_um=200.0,
             histogram_depth_smooth_um=5.0,
             histogram_time_smooth_s=None,
             pairwise_displacement_method="conv",
@@ -181,7 +181,7 @@
             bin_duration_s=2.0,
             rigid=False,
             win_step_um=50.0,
-            win_sigma_um=150.0,
+            win_scale_um=150.0,
             margin_um=0,
             win_shape="rect",
         ),
diff --git a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_estimation.py b/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_estimation.py
index 526cc2e92f..56e1c18d62 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_estimation.py
@@ -45,7 +45,7 @@ def test_benchmark_motion_estimaton(create_cache_folder):
                     bin_um=5.0,
                     rigid=False,
                     win_step_um=50.0,
-                    win_sigma_um=200.0,
+                    win_scale_um=200.0,
                 ),
             ),
         )
diff --git a/src/spikeinterface/sortingcomponents/motion/__init__.py b/src/spikeinterface/sortingcomponents/motion/__init__.py
index 2a045bd108..15233efc32 100644
--- a/src/spikeinterface/sortingcomponents/motion/__init__.py
+++ b/src/spikeinterface/sortingcomponents/motion/__init__.py
@@ -2,3 +2,4 @@
 from .motion_estimation import estimate_motion
 from .motion_interpolation import (correct_motion_on_peaks, interpolate_motion_on_traces,
                                    InterpolateMotionRecording, interpolate_motion)
+from .motion_cleaner import clean_motion_vector
diff --git a/src/spikeinterface/sortingcomponents/motion/decentralized.py b/src/spikeinterface/sortingcomponents/motion/decentralized.py
new file mode 100644
index 0000000000..3b8f19cc3e
--- /dev/null
+++ b/src/spikeinterface/sortingcomponents/motion/decentralized.py
@@ -0,0 +1,814 @@
+import numpy as np
+
+from tqdm.auto import tqdm, trange
+
+try:
+    import torch
+    import torch.nn.functional as F
+
+    HAVE_TORCH = True
+except ImportError:
+    HAVE_TORCH = False
+
+from .motion_utils import Motion, get_windows, get_spatial_bin_edges, make_2d_motion_histogram, scipy_conv1d
+
+
+class DecentralizedRegistration:
+    """
+    Method developed by the Paninski's group from Columbia university:
+    Charlie Windolf, Julien Boussard, Erdem Varol, Hyun Dong Lee
+
+    This method is also known as DREDGe, but this implemenation does not use LFP signals.
+
+    Original reference:
+    DECENTRALIZED MOTION INFERENCE AND REGISTRATION OF NEUROPIXEL DATA
+    https://ieeexplore.ieee.org/document/9414145
+    https://proceedings.neurips.cc/paper/2021/hash/b950ea26ca12daae142bd74dba4427c8-Abstract.html
+
+    This code was improved during Spike Sorting NY Hackathon 2022 by Erdem Varol and Charlie Windolf.
+    An additional major improvement can be found in this paper:
+    https://www.biorxiv.org/content/biorxiv/early/2022/12/05/2022.12.04.519043.full.pdf
+
+
+    Here are some various implementations by the original team:
+    https://github.com/int-brain-lab/spikes_localization_registration/blob/main/registration_pipeline/image_based_motion_estimate.py#L211
+    https://github.com/cwindolf/spike-psvae/tree/main/spike_psvae
+    https://github.com/evarol/DREDge
+    """
+
+    name = "decentralized"
+    need_peak_location = True
+    params_doc = """
+    bin_um: float, default: 10
+        Spatial bin size in micrometers
+    hist_margin_um: float, default: 0
+        Margin in um from histogram estimation.
+        Positive margin extrapolate out of the probe the motion.
+        Negative margin crop the motion on the border
+    bin_duration_s: float, default: 2.0
+        Bin duration in second
+    histogram_depth_smooth_um: None or float
+        Optional gaussian smoother on histogram on depth axis.
+        This is given as the sigma of the gaussian in micrometers.
+    histogram_time_smooth_s: None or float
+        Optional gaussian smoother on histogram on time axis.
+        This is given as the sigma of the gaussian in seconds.
+    pairwise_displacement_method: "conv" or "phase_cross_correlation"
+        How to estimate the displacement in the pairwise matrix.
+    max_displacement_um: float
+        Maximum possible displacement in micrometers.
+    weight_scale: "linear" or "exp"
+        For parwaise displacement, how to to rescale the associated weight matrix.
+    error_sigma: float, default: 0.2
+        In case weight_scale="exp" this controls the sigma of the exponential.
+    conv_engine: "numpy" or "torch" or None, default: None
+        In case of pairwise_displacement_method="conv", what library to use to compute
+        the underlying correlation
+    torch_device=None
+        In case of conv_engine="torch", you can control which device (cpu or gpu)
+    batch_size: int
+        Size of batch for the convolution. Increasing this will speed things up dramatically
+        on GPUs and sometimes on CPU as well.
+    corr_threshold: float
+        Minimum correlation between pair of time bins in order for these to be
+        considered when optimizing a global displacment vector to align with
+        the pairwise displacements.
+    time_horizon_s: None or float
+        When not None the parwise discplament matrix is computed in a small time horizon.
+        In short only pair of bins close in time.
+        So the pariwaise matrix is super sparse and have values only the diagonal.
+    convergence_method: "lsmr" | "lsqr_robust" | "gradient_descent", default: "lsqr_robust"
+        Which method to use to compute the global displacement vector from the pairwise matrix.
+    robust_regression_sigma: float
+        Use for convergence_method="lsqr_robust" for iterative selection of the regression.
+    temporal_prior : bool, default: True
+        Ensures continuity across time, unless there is evidence in the recording for jumps.
+    spatial_prior : bool, default: False
+        Ensures continuity across space. Not usually necessary except in recordings with
+        glitches across space.
+    force_spatial_median_continuity: bool, default: False
+        When spatial_prior=False we can optionally apply a median continuity across spatial windows.
+    reference_displacement : string, one of: "mean", "median", "time", "mode_search"
+        Strategy for picking what is considered displacement=0.
+         - "mean" : the mean displacement is subtracted
+         - "median" : the median displacement is subtracted
+         - "time" : the displacement at a given time (in seconds) is subtracted
+         - "mode_search" : an attempt is made to guess the mode. needs work.
+    lsqr_robust_n_iter: int
+        Number of iteration for convergence_method="lsqr_robust".
+    """
+
+    @classmethod
+    def run(
+        cls,
+        recording,
+        peaks,
+        peak_locations,
+        direction,
+        rigid,
+        win_shape,
+        win_step_um,
+        win_scale_um,
+        win_margin_um,
+        verbose,
+        progress_bar,
+        extra,
+        bin_um=10.0,
+        hist_margin_um=0.0,
+        bin_duration_s=2.0,
+        histogram_depth_smooth_um=None,
+        histogram_time_smooth_s=None,
+        pairwise_displacement_method="conv",
+        max_displacement_um=100.0,
+        weight_scale="linear",
+        error_sigma=0.2,
+        conv_engine=None,
+        torch_device=None,
+        batch_size=1,
+        corr_threshold=0.0,
+        time_horizon_s=None,
+        convergence_method="lsqr_robust",
+        soft_weights=False,
+        normalized_xcorr=True,
+        centered_xcorr=True,
+        temporal_prior=True,
+        spatial_prior=False,
+        force_spatial_median_continuity=False,
+        reference_displacement="median",
+        reference_displacement_time_s=0,
+        robust_regression_sigma=2,
+        lsqr_robust_n_iter=20,
+        weight_with_amplitude=False,
+    ):
+        # use torch if installed
+        if conv_engine is None:
+            conv_engine = "torch" if HAVE_TORCH else "numpy"
+
+        dim = ["x", "y", "z"].index(direction)
+        contact_pos = recording.get_channel_locations()[:, dim]
+
+        # spatial histogram bins
+        spatial_bin_edges = get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um)
+        spatial_bin_centers = 0.5 * (spatial_bin_edges[1:] + spatial_bin_edges[:-1])
+
+        # get spatial windows
+        non_rigid_windows, non_rigid_window_centers = get_windows(
+            rigid, contact_pos, spatial_bin_centers, win_margin_um, win_step_um, win_scale_um, win_shape
+        )
+
+        # make 2D histogram raster
+        if verbose:
+            print("Computing motion histogram")
+
+        motion_histogram, temporal_hist_bin_edges, spatial_hist_bin_edges = make_2d_motion_histogram(
+            recording,
+            peaks,
+            peak_locations,
+            direction=direction,
+            bin_duration_s=bin_duration_s,
+            spatial_bin_edges=spatial_bin_edges,
+            weight_with_amplitude=weight_with_amplitude,
+        )
+        import scipy.signal
+
+        if histogram_depth_smooth_um is not None:
+            bins = np.arange(motion_histogram.shape[1]) * bin_um
+            bins = bins - np.mean(bins)
+            smooth_kernel = np.exp(-(bins**2) / (2 * histogram_depth_smooth_um**2))
+            smooth_kernel /= np.sum(smooth_kernel)
+
+            motion_histogram = scipy.signal.fftconvolve(motion_histogram, smooth_kernel[None, :], mode="same", axes=1)
+
+        if histogram_time_smooth_s is not None:
+            bins = np.arange(motion_histogram.shape[0]) * bin_duration_s
+            bins = bins - np.mean(bins)
+            smooth_kernel = np.exp(-(bins**2) / (2 * histogram_time_smooth_s**2))
+            smooth_kernel /= np.sum(smooth_kernel)
+            motion_histogram = scipy.signal.fftconvolve(motion_histogram, smooth_kernel[:, None], mode="same", axes=0)
+
+        if extra is not None:
+            extra["motion_histogram"] = motion_histogram
+            extra["pairwise_displacement_list"] = []
+            extra["temporal_hist_bin_edges"] = temporal_hist_bin_edges
+            extra["spatial_hist_bin_edges"] = spatial_hist_bin_edges
+
+        # temporal bins are bin center
+        temporal_bins = 0.5 * (temporal_hist_bin_edges[1:] + temporal_hist_bin_edges[:-1])
+
+        motion_array = np.zeros((temporal_bins.size, len(non_rigid_windows)), dtype=np.float64)
+        windows_iter = non_rigid_windows
+        if progress_bar:
+            windows_iter = tqdm(windows_iter, desc="windows")
+        if spatial_prior:
+            all_pairwise_displacements = np.empty(
+                (len(non_rigid_windows), temporal_bins.size, temporal_bins.size), dtype=np.float64
+            )
+            all_pairwise_displacement_weights = np.empty(
+                (len(non_rigid_windows), temporal_bins.size, temporal_bins.size), dtype=np.float64
+            )
+        for i, win in enumerate(windows_iter):
+            window_slice = np.flatnonzero(win > 1e-5)
+            window_slice = slice(window_slice[0], window_slice[-1])
+            if verbose:
+                print(f"Computing pairwise displacement: {i + 1} / {len(non_rigid_windows)}")
+
+            pairwise_displacement, pairwise_displacement_weight = compute_pairwise_displacement(
+                motion_histogram[:, window_slice],
+                bin_um,
+                window=win[window_slice],
+                method=pairwise_displacement_method,
+                weight_scale=weight_scale,
+                error_sigma=error_sigma,
+                conv_engine=conv_engine,
+                torch_device=torch_device,
+                batch_size=batch_size,
+                max_displacement_um=max_displacement_um,
+                normalized_xcorr=normalized_xcorr,
+                centered_xcorr=centered_xcorr,
+                corr_threshold=corr_threshold,
+                time_horizon_s=time_horizon_s,
+                bin_duration_s=bin_duration_s,
+                progress_bar=False,
+            )
+
+            if spatial_prior:
+                all_pairwise_displacements[i] = pairwise_displacement
+                all_pairwise_displacement_weights[i] = pairwise_displacement_weight
+
+            if extra is not None:
+                extra["pairwise_displacement_list"].append(pairwise_displacement)
+
+            if verbose:
+                print(f"Computing global displacement: {i + 1} / {len(non_rigid_windows)}")
+
+            # TODO: if spatial_prior, do this after the loop
+            if not spatial_prior:
+                motion_array[:, i] = compute_global_displacement(
+                    pairwise_displacement,
+                    pairwise_displacement_weight=pairwise_displacement_weight,
+                    convergence_method=convergence_method,
+                    robust_regression_sigma=robust_regression_sigma,
+                    lsqr_robust_n_iter=lsqr_robust_n_iter,
+                    temporal_prior=temporal_prior,
+                    spatial_prior=spatial_prior,
+                    soft_weights=soft_weights,
+                    progress_bar=False,
+                )
+
+        if spatial_prior:
+            motion_array = compute_global_displacement(
+                all_pairwise_displacements,
+                pairwise_displacement_weight=all_pairwise_displacement_weights,
+                convergence_method=convergence_method,
+                robust_regression_sigma=robust_regression_sigma,
+                lsqr_robust_n_iter=lsqr_robust_n_iter,
+                temporal_prior=temporal_prior,
+                spatial_prior=spatial_prior,
+                soft_weights=soft_weights,
+                progress_bar=False,
+            )
+        elif len(non_rigid_windows) > 1:
+            # if spatial_prior is False, we still want keep the spatial bins
+            # correctly offset from each other
+            if force_spatial_median_continuity:
+                for i in range(len(non_rigid_windows) - 1):
+                    motion_array[:, i + 1] -= np.median(motion_array[:, i + 1] - motion_array[:, i])
+
+        # try to avoid constant offset
+        # let the user choose how to do this. here are some ideas.
+        # (one can also -= their own number on the result of this function.)
+        if reference_displacement == "mean":
+            motion_array -= motion_array.mean()
+        elif reference_displacement == "median":
+            motion_array -= np.median(motion_array)
+        elif reference_displacement == "time":
+            # reference the motion to 0 at a specific time, independently in each window
+            reference_displacement_bin = np.digitize(reference_displacement_time_s, temporal_hist_bin_edges) - 1
+            motion_array -= motion_array[reference_displacement_bin, :]
+        elif reference_displacement == "mode_search":
+            # just a sketch of an idea
+            # things might want to change, should have a configurable bin size,
+            # should use a call to histogram instead of the loop, ...
+            step_size = 0.1
+            round_mode = np.round  # floor?
+            best_ref = np.median(motion_array)
+            max_zeros = np.sum(round_mode(motion_array - best_ref) == 0)
+            for ref in np.arange(np.floor(motion_array.min()), np.ceil(motion_array.max()), step_size):
+                n_zeros = np.sum(round_mode(motion_array - ref) == 0)
+                if n_zeros > max_zeros:
+                    max_zeros = n_zeros
+                    best_ref = ref
+            motion_array -= best_ref
+
+        # replace nan by zeros
+        np.nan_to_num(motion_array, copy=False)
+
+        motion = Motion([motion_array], [temporal_bins], non_rigid_window_centers, direction=direction)
+
+        return motion
+
+
+def compute_pairwise_displacement(
+    motion_hist,
+    bin_um,
+    method="conv",
+    weight_scale="linear",
+    error_sigma=0.2,
+    conv_engine="numpy",
+    torch_device=None,
+    batch_size=1,
+    max_displacement_um=1500,
+    corr_threshold=0,
+    time_horizon_s=None,
+    normalized_xcorr=True,
+    centered_xcorr=True,
+    bin_duration_s=None,
+    progress_bar=False,
+    window=None,
+):
+    """
+    Compute pairwise displacement
+    """
+    from scipy import linalg
+
+    assert conv_engine in ("torch", "numpy"), f"'conv_engine' must be 'torch' or 'numpy'"
+    size = motion_hist.shape[0]
+    pairwise_displacement = np.zeros((size, size), dtype="float32")
+
+    if time_horizon_s is not None:
+        band_width = int(np.ceil(time_horizon_s / bin_duration_s))
+        if band_width >= size:
+            time_horizon_s = None
+
+    if conv_engine == "torch":
+        if torch_device is None:
+            torch_device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+    if method == "conv":
+        if max_displacement_um is None:
+            n = motion_hist.shape[1] // 2
+        else:
+            n = min(
+                motion_hist.shape[1] // 2,
+                int(np.ceil(max_displacement_um // bin_um)),
+            )
+        possible_displacement = np.arange(-n, n + 1) * bin_um
+
+        xrange = trange if progress_bar else range
+
+        motion_hist_engine = motion_hist
+        window_engine = window
+        if conv_engine == "torch":
+            motion_hist_engine = torch.as_tensor(motion_hist, dtype=torch.float32, device=torch_device)
+            window_engine = torch.as_tensor(window, dtype=torch.float32, device=torch_device)
+
+        pairwise_displacement = np.empty((size, size), dtype=np.float32)
+        correlation = np.empty((size, size), dtype=motion_hist.dtype)
+
+        for i in xrange(0, size, batch_size):
+            corr = normxcorr1d(
+                motion_hist_engine,
+                motion_hist_engine[i : i + batch_size],
+                weights=window_engine,
+                padding=possible_displacement.size // 2,
+                conv_engine=conv_engine,
+                normalized=normalized_xcorr,
+                centered=centered_xcorr,
+            )
+            if conv_engine == "torch":
+                max_corr, best_disp_inds = torch.max(corr, dim=2)
+                best_disp = possible_displacement[best_disp_inds.cpu()]
+                pairwise_displacement[i : i + batch_size] = best_disp
+                correlation[i : i + batch_size] = max_corr.cpu()
+            elif conv_engine == "numpy":
+                best_disp_inds = np.argmax(corr, axis=2)
+                max_corr = np.take_along_axis(corr, best_disp_inds[..., None], 2).squeeze()
+                best_disp = possible_displacement[best_disp_inds]
+                pairwise_displacement[i : i + batch_size] = best_disp
+                correlation[i : i + batch_size] = max_corr
+
+        if corr_threshold is not None and corr_threshold > 0:
+            which = correlation > corr_threshold
+            correlation *= which
+
+    elif method == "phase_cross_correlation":
+        # this 'phase_cross_correlation' is an old idea from Julien/Charlie/Erden that is kept for testing
+        # but this is not very releveant
+        try:
+            import skimage.registration
+        except ImportError:
+            raise ImportError("To use the 'phase_cross_correlation' method install scikit-image")
+
+        errors = np.zeros((size, size), dtype="float32")
+        loop = range(size)
+        if progress_bar:
+            loop = tqdm(loop)
+        for i in loop:
+            for j in range(size):
+                shift, error, diffphase = skimage.registration.phase_cross_correlation(
+                    motion_hist[i, :], motion_hist[j, :]
+                )
+                pairwise_displacement[i, j] = shift * bin_um
+                errors[i, j] = error
+        correlation = 1 - errors
+
+    else:
+        raise ValueError(
+            f"method {method} does not exist for compute_pairwise_displacement. Current possible methods are"
+            f" 'conv' or 'phase_cross_correlation'"
+        )
+
+    if weight_scale == "linear":
+        # between 0 and 1
+        pairwise_displacement_weight = correlation
+    elif weight_scale == "exp":
+        pairwise_displacement_weight = np.exp((correlation - 1) / error_sigma)
+
+    # handle the time horizon by multiplying the weights by a
+    # matrix with the time horizon on its diagonal bands.
+    if method == "conv" and time_horizon_s is not None and time_horizon_s > 0:
+        horizon_matrix = linalg.toeplitz(
+            np.r_[np.ones(band_width, dtype=bool), np.zeros(size - band_width, dtype=bool)]
+        )
+        pairwise_displacement_weight *= horizon_matrix
+
+    return pairwise_displacement, pairwise_displacement_weight
+
+
+
+_possible_convergence_method = ("lsmr", "gradient_descent", "lsqr_robust")
+
+
+def compute_global_displacement(
+    pairwise_displacement,
+    pairwise_displacement_weight=None,
+    sparse_mask=None,
+    temporal_prior=True,
+    spatial_prior=True,
+    soft_weights=False,
+    convergence_method="lsmr",
+    robust_regression_sigma=2,
+    lsqr_robust_n_iter=20,
+    progress_bar=False,
+):
+    """
+    Compute global displacement
+
+    Arguments
+    ---------
+    pairwise_displacement : time x time array
+    pairwise_displacement_weight : time x time array
+    sparse_mask : time x time array
+    convergence_method : str
+        One of "gradient"
+
+    """
+    import scipy
+    from scipy.optimize import minimize
+    from scipy.sparse import csr_matrix
+    from scipy.sparse.linalg import lsqr
+    from scipy.stats import zscore
+
+    if convergence_method == "gradient_descent":
+        size = pairwise_displacement.shape[0]
+
+        D = pairwise_displacement
+        if pairwise_displacement_weight is not None or sparse_mask is not None:
+            # weighted problem
+            if pairwise_displacement_weight is None:
+                pairwise_displacement_weight = np.ones_like(D)
+            if sparse_mask is None:
+                sparse_mask = np.ones_like(D)
+            W = pairwise_displacement_weight * sparse_mask
+
+            I, J = np.nonzero(W > 0)
+            Wij = W[I, J]
+            Dij = D[I, J]
+            W = csr_matrix((Wij, (I, J)), shape=W.shape)
+            WD = csr_matrix((Wij * Dij, (I, J)), shape=W.shape)
+            fixed_terms = (W @ WD).diagonal() - (WD @ W).diagonal()
+            diag_WW = (W @ W).diagonal()
+            Wsq = W.power(2)
+
+            def obj(p):
+                return 0.5 * np.square(Wij * (Dij - (p[I] - p[J]))).sum()
+
+            def jac(p):
+                return fixed_terms - 2 * (Wsq @ p) + 2 * p * diag_WW
+
+        else:
+            # unweighted problem, it's faster when we have no weights
+            fixed_terms = -D.sum(axis=1) + D.sum(axis=0)
+
+            def obj(p):
+                v = np.square((D - (p[:, None] - p[None, :]))).sum()
+                return 0.5 * v
+
+            def jac(p):
+                return fixed_terms + 2 * (size * p - p.sum())
+
+        res = minimize(fun=obj, jac=jac, x0=D.mean(axis=1), method="L-BFGS-B")
+        if not res.success:
+            print("Global displacement gradient descent had an error")
+        displacement = res.x
+
+    elif convergence_method == "lsqr_robust":
+
+        if sparse_mask is not None:
+            I, J = np.nonzero(sparse_mask > 0)
+        elif pairwise_displacement_weight is not None:
+            I, J = pairwise_displacement_weight.nonzero()
+        else:
+            I, J = np.nonzero(np.ones_like(pairwise_displacement, dtype=bool))
+
+        nnz_ones = np.ones(I.shape[0], dtype=pairwise_displacement.dtype)
+
+        if pairwise_displacement_weight is not None:
+            if isinstance(pairwise_displacement_weight, scipy.sparse.csr_matrix):
+                W = np.array(pairwise_displacement_weight[I, J]).T
+            else:
+                W = pairwise_displacement_weight[I, J][:, None]
+        else:
+            W = nnz_ones[:, None]
+        if isinstance(pairwise_displacement, scipy.sparse.csr_matrix):
+            V = np.array(pairwise_displacement[I, J])[0]
+        else:
+            V = pairwise_displacement[I, J]
+        M = csr_matrix((nnz_ones, (range(I.shape[0]), I)), shape=(I.shape[0], pairwise_displacement.shape[0]))
+        N = csr_matrix((nnz_ones, (range(I.shape[0]), J)), shape=(I.shape[0], pairwise_displacement.shape[0]))
+        A = M - N
+        idx = np.ones(A.shape[0], dtype=bool)
+
+        # TODO: this is already soft_weights
+        xrange = trange if progress_bar else range
+        for i in xrange(lsqr_robust_n_iter):
+            p = lsqr(A[idx].multiply(W[idx]), V[idx] * W[idx][:, 0])[0]
+            idx = np.nonzero(np.abs(zscore(A @ p - V)) <= robust_regression_sigma)
+        displacement = p
+
+    elif convergence_method == "lsmr":
+        import gc
+        from scipy import sparse
+
+        D = pairwise_displacement
+
+        # weighted problem
+        if pairwise_displacement_weight is None:
+            pairwise_displacement_weight = np.ones_like(D)
+        if sparse_mask is None:
+            sparse_mask = np.ones_like(D)
+        W = pairwise_displacement_weight * sparse_mask
+        if isinstance(W, scipy.sparse.csr_matrix):
+            W = W.astype(np.float32).toarray()
+            D = D.astype(np.float32).toarray()
+
+        assert D.shape == W.shape
+
+        # first dimension is the windows dim, which could be empty in rigid case
+        # we expand dims so that below we can consider only the nonrigid case
+        if D.ndim == 2:
+            W = W[None]
+            D = D[None]
+        assert D.ndim == W.ndim == 3
+        B, T, T_ = D.shape
+        assert T == T_
+
+        # sparsify the problem
+        # we will make a list of temporal problems and then
+        # stack over the windows axis to finish.
+        # each matrix in coefficients will be (sparse_dim, T)
+        coefficients = []
+        # each vector in targets will be (T,)
+        targets = []
+        # we want to solve for a vector of shape BT, which we will reshape
+        # into a (B, T) matrix.
+        # after the loop below, we will stack a coefts matrix (sparse_dim, B, T)
+        # and a target vector of shape (B, T), both to be vectorized on last two axes,
+        # so that the target p is indexed by i = bT + t (block/window major).
+
+        # calculate coefficients matrices and target vector
+        # this list stores boolean masks corresponding to whether or not each
+        # term comes from the prior or the likelihood. we can trim the likelihood terms,
+        # but not the prior terms, in the trimmed least squares (robust iters) iterations below.
+        cannot_trim = []
+        for Wb, Db in zip(W, D):
+            # indices of active temporal pairs in this window
+            I, J = np.nonzero(Wb > 0)
+            n_sampled = I.size
+
+            # construct Kroneckers and sparse objective in this window
+            pair_weights = np.ones(n_sampled)
+            if soft_weights:
+                pair_weights = Wb[I, J]
+            Mb = sparse.csr_matrix((pair_weights, (range(n_sampled), I)), shape=(n_sampled, T))
+            Nb = sparse.csr_matrix((pair_weights, (range(n_sampled), J)), shape=(n_sampled, T))
+            block_sparse_kron = Mb - Nb
+            block_disp_pairs = pair_weights * Db[I, J]
+            cannot_trim_block = np.ones_like(block_disp_pairs, dtype=bool)
+
+            # add the temporal smoothness prior in this window
+            if temporal_prior:
+                temporal_diff_operator = sparse.diags(
+                    (
+                        np.full(T - 1, -1, dtype=block_sparse_kron.dtype),
+                        np.full(T - 1, 1, dtype=block_sparse_kron.dtype),
+                    ),
+                    offsets=(0, 1),
+                    shape=(T - 1, T),
+                )
+                block_sparse_kron = sparse.vstack(
+                    (block_sparse_kron, temporal_diff_operator),
+                    format="csr",
+                )
+                block_disp_pairs = np.concatenate(
+                    (block_disp_pairs, np.zeros(T - 1)),
+                )
+                cannot_trim_block = np.concatenate(
+                    (cannot_trim_block, np.zeros(T - 1, dtype=bool)),
+                )
+
+            coefficients.append(block_sparse_kron)
+            targets.append(block_disp_pairs)
+            cannot_trim.append(cannot_trim_block)
+        coefficients = sparse.block_diag(coefficients)
+        targets = np.concatenate(targets, axis=0)
+        cannot_trim = np.concatenate(cannot_trim, axis=0)
+
+        # spatial smoothness prior: penalize difference of each block's
+        # displacement with the next.
+        # only if B > 1, and not in the last window.
+        # this is a (BT, BT) sparse matrix D such that:
+        # entry at (i, j) is:
+        #  {   1 if i = j, i.e., i = j = bT + t for b = 0,...,B-2
+        #  {  -1 if i = bT + t and j = (b+1)T + t for b = 0,...,B-2
+        #  {   0 otherwise.
+        # put more simply, the first (B-1)T diagonal entries are 1,
+        # and entries (i, j) such that i = j - T are -1.
+        if B > 1 and spatial_prior:
+            spatial_diff_operator = sparse.diags(
+                (
+                    np.ones((B - 1) * T, dtype=block_sparse_kron.dtype),
+                    np.full((B - 1) * T, -1, dtype=block_sparse_kron.dtype),
+                ),
+                offsets=(0, T),
+                shape=((B - 1) * T, B * T),
+            )
+            coefficients = sparse.vstack((coefficients, spatial_diff_operator))
+            targets = np.concatenate((targets, np.zeros((B - 1) * T, dtype=targets.dtype)))
+            cannot_trim = np.concatenate((cannot_trim, np.zeros((B - 1) * T, dtype=bool)))
+        coefficients = coefficients.tocsr()
+
+        # initialize at the column mean of pairwise displacements (in each window)
+        p0 = D.mean(axis=2).reshape(B * T)
+
+        # use LSMR to solve the whole problem || targets - coefficients @ motion ||^2
+        iters = range(max(1, lsqr_robust_n_iter))
+        if progress_bar and lsqr_robust_n_iter > 1:
+            iters = tqdm(iters, desc="robust lsqr")
+        for it in iters:
+            # trim active set -- start with no trimming
+            idx = slice(None)
+            if it:
+                idx = np.flatnonzero(
+                    cannot_trim | (np.abs(zscore(coefficients @ displacement - targets)) <= robust_regression_sigma)
+                )
+
+            # solve trimmed ols problem
+            displacement, *_ = sparse.linalg.lsmr(coefficients[idx], targets[idx], x0=p0)
+
+            # warm start next iteration
+            p0 = displacement
+            # Cleanup lsmr memory (see https://stackoverflow.com/questions/56147713/memory-leak-in-scipy)
+            # TODO: check if this gets fixed in scipy
+            gc.collect()
+
+        displacement = displacement.reshape(B, T).T
+    else:
+        raise ValueError(
+            f"Method {convergence_method} doesn't exist for compute_global_displacement"
+            f" possible values for 'convergence_method' are {_possible_convergence_method}"
+        )
+
+    return np.squeeze(displacement)
+
+
+# TODO charlie sam : make a unique function for this
+# at the moment this is the legacy one ported in spikeinterface
+# the one in deredge.py is more recent
+def normxcorr1d(
+    template,
+    x,
+    weights=None,
+    centered=True,
+    normalized=True,
+    padding="same",
+    conv_engine="torch",
+):
+    """normxcorr1d: Normalized cross-correlation, optionally weighted
+
+    The API is like torch's F.conv1d, except I have accidentally
+    changed the position of input/weights -- template acts like weights,
+    and x acts like input.
+
+    Returns the cross-correlation of `template` and `x` at spatial lags
+    determined by `mode`. Useful for estimating the location of `template`
+    within `x`.
+
+    This might not be the most efficient implementation -- ideas welcome.
+    It uses a direct convolutional translation of the formula
+        corr = (E[XY] - EX EY) / sqrt(var X * var Y)
+
+    This also supports weights! In that case, the usual adaptation of
+    the above formula is made to the weighted case -- and all of the
+    normalizations are done per block in the same way.
+
+    Parameters
+    ----------
+    template : tensor, shape (num_templates, length)
+        The reference template signal
+    x : tensor, 1d shape (length,) or 2d shape (num_inputs, length)
+        The signal in which to find `template`
+    weights : tensor, shape (length,)
+        Will use weighted means, variances, covariances if supplied.
+    centered : bool
+        If true, means will be subtracted (per weighted patch).
+    normalized : bool
+        If true, normalize by the variance (per weighted patch).
+    padding : str
+        How far to look? if unset, we'll use half the length
+    conv_engine : string, one of "torch", "numpy"
+        What library to use for computing cross-correlations.
+        If numpy, falls back to the scipy correlate function.
+
+    Returns
+    -------
+    corr : tensor
+    """
+    if conv_engine == "torch":
+        assert HAVE_TORCH
+        conv1d = F.conv1d
+        npx = torch
+    elif conv_engine == "numpy":
+        conv1d = scipy_conv1d
+        npx = np
+    else:
+        raise ValueError(f"Unknown conv_engine {conv_engine}. 'conv_engine' must be 'torch' or 'numpy'")
+
+    x = npx.atleast_2d(x)
+    num_templates, length = template.shape
+    num_inputs, length_ = template.shape
+    assert length == length_
+
+    # generalize over weighted / unweighted case
+    device_kw = {} if conv_engine == "numpy" else dict(device=x.device)
+    ones = npx.ones((1, 1, length), dtype=x.dtype, **device_kw)
+    no_weights = weights is None
+    if no_weights:
+        weights = ones
+        wt = template[:, None, :]
+    else:
+        assert weights.shape == (length,)
+        weights = weights[None, None]
+        wt = template[:, None, :] * weights
+
+    # conv1d valid rule:
+    # (B,1,L),(O,1,L)->(B,O,L)
+
+    # compute expectations
+    # how many points in each window? seems necessary to normalize
+    # for numerical stability.
+    N = conv1d(ones, weights, padding=padding)
+    if centered:
+        Et = conv1d(ones, wt, padding=padding)
+        Et /= N
+        Ex = conv1d(x[:, None, :], weights, padding=padding)
+        Ex /= N
+
+    # compute (weighted) covariance
+    # important: the formula E[XY] - EX EY is well-suited here,
+    # because the means are naturally subtracted correctly
+    # patch-wise. you couldn't pre-subtract them!
+    cov = conv1d(x[:, None, :], wt, padding=padding)
+    cov /= N
+    if centered:
+        cov -= Ex * Et
+
+    # compute variances for denominator, using var X = E[X^2] - (EX)^2
+    if normalized:
+        var_template = conv1d(ones, wt * template[:, None, :], padding=padding)
+        var_template /= N
+        var_x = conv1d(npx.square(x)[:, None, :], weights, padding=padding)
+        var_x /= N
+        if centered:
+            var_template -= npx.square(Et)
+            var_x -= npx.square(Ex)
+
+    # now find the final normxcorr
+    corr = cov  # renaming for clarity
+    if normalized:
+        corr /= npx.sqrt(var_x)
+        corr /= npx.sqrt(var_template)
+        # get rid of NaNs in zero-variance areas
+        corr[~npx.isfinite(corr)] = 0
+
+    return corr
\ No newline at end of file
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 56770dbf63..70dfc86107 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -1,5 +1,5 @@
 """
-Re-implementation or copy-paste of DREDge
+Copy-paste and then refactoring of DREDge
 https://github.com/evarol/dredge
 
 For historical reason, some function from the DREDge package where implemeneted 
@@ -10,7 +10,7 @@
 The main entry for this function are still:
 
   * motion = estimate_motion((recording, ..., method='dredge_lfp')
-  * motion = estimate_motion((recording, ..., method='dredge_ap')
+  * motion = estimate_motion((recording, ..., method='dredge_ap') < not Done yet
 
 but here the original functions from Charlie, Julien and Erdem have been ported for an
 easier maintenance instead of making DREDge a dependency of spikeinterface.
@@ -23,16 +23,77 @@
 
 from .motion_utils import Motion, get_windows, get_window_domains, scipy_conv1d
 
+
+# TODO add direction
+
+# simple class wrapper to be compliant with estimate_motion
+class DredgeLfpRegistration:
+    """
+
+    """
+    name = "dredge_lfp"
+    need_peak_location = False
+    params_doc = """
+
+    """
+    @classmethod
+    def run(
+        cls,
+        recording,
+        peaks,
+        peak_locations,
+        direction,
+        rigid,
+        win_shape,
+        win_step_um,
+        win_scale_um,
+        win_margin_um,
+        verbose,
+        progress_bar,
+        extra,
+
+        **method_kwargs,
+    ):
+        # Note peaks and peak_locations are not used and can be None
+
+        outs = dredge_online_lfp(
+            recording,
+            direction=direction,
+            rigid=rigid,
+            win_shape=win_shape,
+            win_step_um=win_step_um,
+            win_scale_um=win_scale_um,
+            win_margin_um=win_margin_um,
+            extra_outputs=(extra is not None),
+            progress_bar=progress_bar,
+            **method_kwargs,
+        )
+
+        if extra is not None:
+            motion, extra_ = outs
+            extra.update(extra_)
+
+        else:
+            motion = outs
+
+
+
+
+
 def dredge_online_lfp(
     lfp_recording,
-    rigid=True,
-    chunk_len_s=10.0,
-    max_disp_um=500,
+    direction='y',
     # nonrigid window construction arguments
+    rigid=True,
     win_shape="gaussian",
     win_step_um=800,
     win_scale_um=850,
     win_margin_um=None,
+    
+    chunk_len_s=10.0,
+    max_disp_um=500,
+    
+    
     time_horizon_s=None,
     # weighting arguments
     mincorr=0.8,
@@ -45,7 +106,7 @@ def dredge_online_lfp(
     # misc
     extra_outputs=False,
     device=None,
-    pbar=True,
+    progress_bar=True,
 ):
     """Online registration of a preprocessed LFP recording
 
@@ -58,6 +119,11 @@ def dredge_online_lfp(
         estimating motion at the original frequency (which may be high).
     rigid : boolean, optional
         If True, window-related arguments are ignored and we do rigid registration
+    win_shape, win_step_um, win_scale_um, win_margin_um : float
+        Nonrigid window-related arguments
+        The depth domain will be broken up into windows with shape controlled by win_shape,
+        spaced by win_step_um at a margin of win_margin_um from the boundary, and with
+        width controlled by win_scale_um.
     chunk_len_s : float
         Length of chunks (in seconds) that the recording is broken into for online
         registration. The computational speed of the method is a function of the
@@ -75,11 +141,6 @@ def dredge_online_lfp(
         chunk. Setting it as small as possible (while following that rule) can speed
         things up and improve the result by making it impossible to estimate motion
         which is too big.
-    win_shape, win_step_um, win_scale_um, win_margin_um : float
-        Nonrigid window-related arguments
-        The depth domain will be broken up into windows with shape controlled by win_shape,
-        spaced by win_step_um at a margin of win_margin_um from the boundary, and with
-        width controlled by win_scale_um.
     mincorr : float in [0,1]
         Minimum correlation between pairs of frames such that they will be included
         in the optimization of the displacement estimates.
@@ -97,7 +158,11 @@ def dredge_online_lfp(
     extra : dict
         Dict containing extra info for debugging
     """
-    geom = lfp_recording.get_channel_locations()
+    dim = ["x", "y", "z"].index(direction)
+    # contact pos is the only on the direction
+    contact_pos = lfp_recording.get_channel_locations()[:, dim]
+
+
     fs = lfp_recording.get_sampling_frequency()
     T_total = lfp_recording.get_num_samples()
     T_chunk = min(int(np.floor(fs * chunk_len_s)), T_total)
@@ -108,9 +173,9 @@ def dredge_online_lfp(
     thomas_kw = thomas_kw if thomas_kw is not None else {}
     full_xcorr_kw = dict(
         rigid=rigid,
-        bin_um=np.median(np.diff(geom[:, 1])),
+        bin_um=np.median(np.diff(contact_pos)),
         max_disp_um=max_disp_um,
-        pbar=False,
+        progress_bar=False,
         device=device,
         **xcorr_kw,
     )
@@ -123,17 +188,28 @@ def dredge_online_lfp(
         bin_s=1 / fs,  # only relevant for time_horizon_s
     )
 
-    # in LFP bin center are contact position
-    # TODO sam check dim and direction and assert unique
-    spatial_bin_centers = geom[:, 1]
+    
+    # here we check that contact positons are unique on the direction
+    if contact_pos.size != np.unique(contact_pos).size:
+        raise ValueError(
+            f"estimate motion with 'dredge_lfp' need channel_positions to be unique in the direction='{direction}'"
+        )
+    if np.any(np.diff(contact_pos) < 0):
+        raise ValueError(
+            f"estimate motion with 'dredge_lfp' need channel_positions to be ordered direction='{direction}'"
+            "please use spikeinterface.preprocessing.depth_order(recording)"
+        )
+
+    # Important detail : in LFP bin center are contact position in the direction
+    spatial_bin_centers = contact_pos
 
     windows, window_centers = get_windows(
         rigid=rigid, 
-        contact_pos=geom,
+        contact_pos=contact_pos,
         spatial_bin_centers=spatial_bin_centers,
-        margin_um=win_margin_um,
+        win_margin_um=win_margin_um,
         win_step_um=win_step_um,
-        win_sigma_um=win_scale_um,
+        win_scale_um=win_scale_um,
         win_shape=win_shape,
         zero_threshold=1e-5,
     )
@@ -149,7 +225,7 @@ def dredge_online_lfp(
     t0, t1 = 0, T_chunk
     traces0 = lfp_recording.get_traces(start_frame=t0, end_frame=t1)
     Ds0, Cs0, max_disp_um = xcorr_windows(
-        traces0.T, windows, geom[:, 1], win_scale_um, **full_xcorr_kw
+        traces0.T, windows, contact_pos, win_scale_um, **full_xcorr_kw
     )
     full_xcorr_kw["max_disp_um"] = max_disp_um
     Ss0, mincorr0 = threshold_correlation_matrix(
@@ -172,7 +248,7 @@ def dredge_online_lfp(
 
     # -- loop through chunks
     chunk_starts = range(T_chunk, T_total, T_chunk)
-    if pbar:
+    if progress_bar:
         chunk_starts = trange(
             T_chunk,
             T_total,
@@ -188,7 +264,7 @@ def dredge_online_lfp(
         Ds10, Cs10, _ = xcorr_windows(
             traces1.T,
             windows,
-            geom[:, 1],
+            contact_pos,
             win_scale_um,
             raster_b=traces0.T,
             **full_xcorr_kw,
@@ -196,7 +272,7 @@ def dredge_online_lfp(
 
         # cross-correlation in current chunk
         Ds1, Cs1, _ = xcorr_windows(
-            traces1.T, windows, geom[:, 1], win_scale_um, **full_xcorr_kw
+            traces1.T, windows, contact_pos, win_scale_um, **full_xcorr_kw
         )
         Ss1, mincorr1 = threshold_correlation_matrix(
             Cs1,
@@ -368,7 +444,7 @@ def thomas_solve(
     Us_prevcur=None,
     Ds_curprev=None,
     Us_curprev=None,
-    pbar=False,
+    progress_bar=False,
     bandwidth=None,
 ):
     """Block tridiagonal algorithm, special cased to our setting
@@ -455,7 +531,7 @@ def thomas_solve(
     ys = [res[:, T]]
 
     # forward pass
-    for b in (trange(1, B, desc="Solve") if pbar else range(1, B)):
+    for b in (trange(1, B, desc="Solve") if progress_bar else range(1, B)):
         if b < B - 1:
             Lambda_s_diagb = laplacian(T, eps=eps, lambd=lambda_s, ridge_mask=had_weights[b])
         else:
@@ -548,7 +624,7 @@ def xcorr_windows(
     bin_um=1,
     max_disp_um=None,
     max_dt_bins=None,
-    pbar=True,
+    progress_bar=True,
     centered=True,
     normalized=True,
     masks=None,
@@ -592,7 +668,7 @@ def xcorr_windows(
     # estimate each window's displacement
     Ds = np.zeros((B, T0, T1), dtype=np.float32)
     Cs = np.zeros((B, T0, T1), dtype=np.float32)
-    block_iter = trange(B, desc="Cross correlation") if pbar else range(B)
+    block_iter = trange(B, desc="Cross correlation") if progress_bar else range(B)
     for b in block_iter:
         window = windows_[b]
 
diff --git a/src/spikeinterface/sortingcomponents/motion/iterative_template.py b/src/spikeinterface/sortingcomponents/motion/iterative_template.py
new file mode 100644
index 0000000000..ab6877adc3
--- /dev/null
+++ b/src/spikeinterface/sortingcomponents/motion/iterative_template.py
@@ -0,0 +1,287 @@
+import numpy as np
+
+from .motion_utils import Motion, get_windows, get_spatial_bin_edges, make_3d_motion_histograms
+
+
+class IterativeTemplateRegistration:
+    """
+    Alignment function implemented by Kilosort2.5 and ported from pykilosort:
+    https://github.com/int-brain-lab/pykilosort/blob/ibl_prod/pykilosort/datashift2.py#L166
+
+    The main difference with respect to the original implementation are:
+     * scipy is used for gaussian smoothing
+     * windowing is implemented as gaussian tapering (instead of rectangular blocks)
+     * the 3d histogram is constructed in less cryptic way
+     * peak_locations are computed outside and so can either center fo mass or monopolar trianglation
+       contrary to kilosort2.5 use exclusively center of mass
+
+    See https://www.science.org/doi/abs/10.1126/science.abf4588?cookieSet=1
+
+    Ported by Alessio Buccino into SpikeInterface
+    """
+
+    name = "iterative_template"
+    need_peak_location = True
+    params_doc = """
+    bin_um: float, default: 10
+        Spatial bin size in micrometers
+    hist_margin_um: float, default: 0
+        Margin in um from histogram estimation.
+        Positive margin extrapolate out of the probe the motion.
+        Negative margin crop the motion on the border
+    bin_duration_s: float, default: 2.0
+        Bin duration in second
+    num_amp_bins: int, default: 20
+        number ob bins in the histogram on the log amplitues dimension
+    num_shifts_global: int, default: 15
+        Number of spatial bin shifts to consider for global alignment
+    num_iterations: int, default: 10
+        Number of iterations for global alignment procedure
+    num_shifts_block: int, default: 5
+        Number of spatial bin shifts to consider for non-rigid alignment
+    smoothing_sigma: float, default: 0.5
+        Sigma of gaussian for covariance matrices smoothing
+    kriging_sigma: float,
+        sigma parameter for kriging_kernel function
+    kriging_p: foat
+        p parameter for kriging_kernel function
+    kriging_d: float
+        d parameter for kriging_kernel function
+    """
+
+    @classmethod
+    def run(
+        cls,
+        recording,
+        peaks,
+        peak_locations,
+        direction,
+        rigid,
+        win_shape,
+        win_step_um,
+        win_scale_um,
+        win_margin_um,
+        verbose,
+        progress_bar,
+        extra,
+        bin_um=10.0,
+        hist_margin_um=0.0,
+        bin_duration_s=2.0,
+        num_amp_bins=20,
+        num_shifts_global=15,
+        num_iterations=10,
+        num_shifts_block=5,
+        smoothing_sigma=0.5,
+        kriging_sigma=1,
+        kriging_p=2,
+        kriging_d=2,
+    ):
+
+        dim = ["x", "y", "z"].index(direction)
+        contact_pos = recording.get_channel_locations()[:, dim]
+
+        # spatial histogram bins
+        spatial_bin_edges = get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um)
+        spatial_bin_centers = 0.5 * (spatial_bin_edges[1:] + spatial_bin_edges[:-1])
+
+        # get spatial windows
+        non_rigid_windows, non_rigid_window_centers = get_windows(
+            rigid, contact_pos, spatial_bin_centers, win_margin_um, win_step_um, win_scale_um, win_shape
+        )
+
+
+        # make a 3D histogram
+        motion_histograms, temporal_hist_bin_edges, spatial_hist_bin_edges = make_3d_motion_histograms(
+            recording,
+            peaks,
+            peak_locations,
+            direction=direction,
+            num_amp_bins=num_amp_bins,
+            bin_duration_s=bin_duration_s,
+            spatial_bin_edges=spatial_bin_edges,
+        )
+        # temporal bins are bin center
+        temporal_bins = temporal_hist_bin_edges[:-1] + bin_duration_s // 2.0
+
+        # do alignment
+        shift_indices, target_histogram, shift_covs_block = iterative_template_registration(
+            motion_histograms,
+            non_rigid_windows=non_rigid_windows,
+            num_shifts_global=num_shifts_global,
+            num_iterations=num_iterations,
+            num_shifts_block=num_shifts_block,
+            smoothing_sigma=smoothing_sigma,
+            kriging_sigma=kriging_sigma,
+            kriging_p=kriging_p,
+            kriging_d=kriging_d,
+        )
+
+        # convert to um
+        motion_array = -(shift_indices * bin_um)
+
+        if extra:
+            extra["non_rigid_windows"] = non_rigid_windows
+            extra["motion_histograms"] = motion_histograms
+            extra["target_histogram"] = target_histogram
+            extra["shift_covs_block"] = shift_covs_block
+            extra["temporal_hist_bin_edges"] = temporal_hist_bin_edges
+            extra["spatial_hist_bin_edges"] = spatial_hist_bin_edges
+
+        # replace nan by zeros
+        np.nan_to_num(motion_array, copy=False)
+
+        motion = Motion([motion_array], [temporal_bins], non_rigid_window_centers, direction=direction)
+
+        return motion
+
+
+
+def iterative_template_registration(
+    spikecounts_hist_images,
+    non_rigid_windows=None,
+    num_shifts_global=15,
+    num_iterations=10,
+    num_shifts_block=5,
+    smoothing_sigma=0.5,
+    kriging_sigma=1,
+    kriging_p=2,
+    kriging_d=2,
+):
+    """
+
+    Parameters
+    ----------
+
+    spikecounts_hist_images : np.ndarray
+        Spike count histogram images (num_temporal_bins, num_spatial_bins, num_amps_bins)
+    non_rigid_windows : list, default: None
+        If num_non_rigid_windows > 1, this argument is required and it is a list of
+        windows to taper spatial bins in different blocks
+    num_shifts_global : int, default: 15
+        Number of spatial bin shifts to consider for global alignment
+    num_iterations : int, default: 10
+        Number of iterations for global alignment procedure
+    num_shifts_block : int, default: 5
+        Number of spatial bin shifts to consider for non-rigid alignment
+    smoothing_sigma : float, default: 0.5
+        Sigma of gaussian for covariance matrices smoothing
+    kriging_sigma : float, default: 1
+        sigma parameter for kriging_kernel function
+    kriging_p : float, default: 2
+        p parameter for kriging_kernel function
+    kriging_d : float, default: 2
+        d parameter for kriging_kernel function
+
+    Returns
+    -------
+    optimal_shift_indices
+        Optimal shifts for each temporal and spatial bin (num_temporal_bins, num_non_rigid_windows)
+    target_spikecount_hist
+        Target histogram used for alignment (num_spatial_bins, num_amps_bins)
+    """
+    from scipy.ndimage import gaussian_filter, gaussian_filter1d
+
+    # F is y bins by amp bins by batches
+    # ysamp are the coordinates of the y bins in um
+    spikecounts_hist_images = spikecounts_hist_images.swapaxes(0, 1).swapaxes(1, 2)
+    num_temporal_bins = spikecounts_hist_images.shape[2]
+
+    # look up and down this many y bins to find best alignment
+    shift_covs = np.zeros((2 * num_shifts_global + 1, num_temporal_bins))
+    shifts = np.arange(-num_shifts_global, num_shifts_global + 1)
+
+    # mean subtraction to compute covariance
+    F = spikecounts_hist_images
+    Fg = F - np.mean(F, axis=0)
+
+    # initialize the target "frame" for alignment with a single sample
+    # here we removed min(299, ...)
+    F0 = Fg[:, :, np.floor(num_temporal_bins / 2).astype("int") - 1]
+    F0 = F0[:, :, np.newaxis]
+
+    # first we do rigid registration by integer shifts
+    # everything is iteratively aligned until most of the shifts become 0.
+    best_shifts = np.zeros((num_iterations, num_temporal_bins))
+    for iteration in range(num_iterations):
+        for t, shift in enumerate(shifts):
+            # for each NEW potential shift, estimate covariance
+            Fs = np.roll(Fg, shift, axis=0)
+            shift_covs[t, :] = np.mean(Fs * F0, axis=(0, 1))
+        if iteration + 1 < num_iterations:
+            # estimate the best shifts
+            imax = np.argmax(shift_covs, axis=0)
+            # align the data by these integer shifts
+            for t, shift in enumerate(shifts):
+                ibest = imax == t
+                Fg[:, :, ibest] = np.roll(Fg[:, :, ibest], shift, axis=0)
+                best_shifts[iteration, ibest] = shift
+            # new target frame based on our current best alignment
+            F0 = np.mean(Fg, axis=2)[:, :, np.newaxis]
+    target_spikecount_hist = F0[:, :, 0]
+
+    # now we figure out how to split the probe into nblocks pieces
+    # if len(non_rigid_windows) = 1, then we're doing rigid registration
+    num_non_rigid_windows = len(non_rigid_windows)
+
+    # for each small block, we only look up and down this many samples to find
+    # nonrigid shift
+    shifts_block = np.arange(-num_shifts_block, num_shifts_block + 1)
+    num_shifts = len(shifts_block)
+    shift_covs_block = np.zeros((2 * num_shifts_block + 1, num_temporal_bins, num_non_rigid_windows))
+
+    # this part determines the up/down covariance for each block without
+    # shifting anything
+    for window_index in range(num_non_rigid_windows):
+        win = non_rigid_windows[window_index]
+        window_slice = np.flatnonzero(win > 1e-5)
+        window_slice = slice(window_slice[0], window_slice[-1])
+        tiled_window = win[window_slice, np.newaxis, np.newaxis]
+        Ftaper = Fg[window_slice] * np.tile(tiled_window, (1,) + Fg.shape[1:])
+        for t, shift in enumerate(shifts_block):
+            Fs = np.roll(Ftaper, shift, axis=0)
+            F0taper = F0[window_slice] * np.tile(tiled_window, (1,) + F0.shape[1:])
+            shift_covs_block[t, :, window_index] = np.mean(Fs * F0taper, axis=(0, 1))
+
+    # gaussian smoothing:
+    # here the original my_conv2_cpu is substituted with scipy gaussian_filters
+    shift_covs_block_smooth = shift_covs_block.copy()
+    shifts_block_up = np.linspace(-num_shifts_block, num_shifts_block, (2 * num_shifts_block * 10) + 1)
+    # 1. 2d smoothing over time and blocks dimensions for each shift
+    for shift_index in range(num_shifts):
+        shift_covs_block_smooth[shift_index, :, :] = gaussian_filter(
+            shift_covs_block_smooth[shift_index, :, :], smoothing_sigma
+        )  # some additional smoothing for robustness, across all dimensions
+    # 2. 1d smoothing over shift dimension for each spatial block
+    for window_index in range(num_non_rigid_windows):
+        shift_covs_block_smooth[:, :, window_index] = gaussian_filter1d(
+            shift_covs_block_smooth[:, :, window_index], smoothing_sigma, axis=0
+        )  # some additional smoothing for robustness, across all dimensions
+    upsample_kernel = kriging_kernel(
+        shifts_block[:, np.newaxis], shifts_block_up[:, np.newaxis], sigma=kriging_sigma, p=kriging_p, d=kriging_d
+    )
+
+    optimal_shift_indices = np.zeros((num_temporal_bins, num_non_rigid_windows))
+    for window_index in range(num_non_rigid_windows):
+        # using the upsampling kernel K, get the upsampled cross-correlation
+        # curves
+        upsampled_cov = upsample_kernel.T @ shift_covs_block_smooth[:, :, window_index]
+
+        # find the max index of these curves
+        imax = np.argmax(upsampled_cov, axis=0)
+
+        # add the value of the shift to the last row of the matrix of shifts
+        # (as if it was the last iteration of the main rigid loop )
+        best_shifts[num_iterations - 1, :] = shifts_block_up[imax]
+
+        # the sum of all the shifts equals the final shifts for this block
+        optimal_shift_indices[:, window_index] = np.sum(best_shifts, axis=0)
+
+    return optimal_shift_indices, target_spikecount_hist, shift_covs_block
+
+
+def kriging_kernel(source_location, target_location, sigma=1, p=2, d=2):
+    from scipy.spatial.distance import cdist
+
+    dist_xy = cdist(source_location, target_location, metric="euclidean")
+    K = np.exp(-((dist_xy / sigma) ** p) / d)
+    return K
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py b/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py
new file mode 100644
index 0000000000..401210e079
--- /dev/null
+++ b/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py
@@ -0,0 +1,73 @@
+import numpy as np
+
+
+
+def clean_motion_vector(motion, temporal_bins, bin_duration_s, speed_threshold=30, sigma_smooth_s=None):
+    """
+    Simple machinery to remove spurious fast bump in the motion vector.
+    Also can applyt a smoothing.
+
+
+    Arguments
+    ---------
+    motion: numpy array 2d
+        Motion estimate in um.
+    temporal_bins: numpy.array 1d
+        temporal bins (bin center)
+    bin_duration_s: float
+        bin duration in second
+    speed_threshold: float (units um/s)
+        Maximum speed treshold between 2 bins allowed.
+        Expressed in um/s
+    sigma_smooth_s: None or float
+        Optional smooting gaussian kernel.
+
+    Returns
+    -------
+    corr : tensor
+
+
+    """
+    motion_clean = motion.copy()
+
+    # STEP 1 :
+    #  * detect long plateau or small peak corssing the speed thresh
+    #  * mask the period and interpolate
+    for i in range(motion.shape[1]):
+        one_motion = motion_clean[:, i]
+        speed = np.diff(one_motion, axis=0) / bin_duration_s
+        (inds,) = np.nonzero(np.abs(speed) > speed_threshold)
+        inds += 1
+        if inds.size % 2 == 1:
+            # more compicated case: number of of inds is odd must remove first or last
+            # take the smallest duration sum
+            inds0 = inds[:-1]
+            inds1 = inds[1:]
+            d0 = np.sum(inds0[1::2] - inds0[::2])
+            d1 = np.sum(inds1[1::2] - inds1[::2])
+            if d0 < d1:
+                inds = inds0
+        mask = np.ones(motion_clean.shape[0], dtype="bool")
+        for i in range(inds.size // 2):
+            mask[inds[i * 2] : inds[i * 2 + 1]] = False
+        import scipy.interpolate
+
+        f = scipy.interpolate.interp1d(temporal_bins[mask], one_motion[mask])
+        one_motion[~mask] = f(temporal_bins[~mask])
+
+    # Step 2 : gaussian smooth
+    if sigma_smooth_s is not None:
+        half_size = motion_clean.shape[0] // 2
+        if motion_clean.shape[0] % 2 == 0:
+            # take care of the shift
+            bins = (np.arange(motion_clean.shape[0]) - half_size + 1) * bin_duration_s
+        else:
+            bins = (np.arange(motion_clean.shape[0]) - half_size) * bin_duration_s
+        smooth_kernel = np.exp(-(bins**2) / (2 * sigma_smooth_s**2))
+        smooth_kernel /= np.sum(smooth_kernel)
+        smooth_kernel = smooth_kernel[:, None]
+        motion_clean = scipy.signal.fftconvolve(motion_clean, smooth_kernel, mode="same", axes=0)
+
+    return motion_clean
+
+
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
index f0c01a005e..7804238024 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
@@ -1,41 +1,36 @@
 from __future__ import annotations
 
-from tqdm.auto import tqdm, trange
+import warnings
 import numpy as np
 
 
-from .motion_utils import Motion, get_windows, scipy_conv1d
+
 from spikeinterface.sortingcomponents.tools import make_multi_method_doc
 
-try:
-    import torch
-    import torch.nn.functional as F
 
-    HAVE_TORCH = True
-except ImportError:
-    HAVE_TORCH = False
+from .motion_utils import Motion, get_windows, get_spatial_bin_edges
+from .decentralized import DecentralizedRegistration
+from .iterative_template import IterativeTemplateRegistration
+from .dredge import DredgeLfpRegistration
 
 
 def estimate_motion(
     recording,
-    peaks,
-    peak_locations,
+    peaks=None,
+    peak_locations=None,
     direction="y",
-    bin_duration_s=10.0,
-    bin_um=10.0,
-    margin_um=0.0,
+    # bin_um=10.0,
+    # hist_margin_um=0.0,
     rigid=False,
     win_shape="gaussian",
     win_step_um=50.0,
-    win_sigma_um=150.0,
-    post_clean=False,
-    speed_threshold=30,
-    sigma_smooth_s=None,
+    win_scale_um=150.0,
+    win_margin_um=0.,
     method="decentralized",
     extra_outputs=False,
     progress_bar=False,
-    upsample_to_histogram_bin=False,
     verbose=False,
+    margin_um=None,
     **method_kwargs,
 ):
     """
@@ -48,57 +43,44 @@ def estimate_motion(
     recording: BaseRecording
         The recording extractor
     peaks: numpy array
-        Peak vector (complex dtype)
+        Peak vector (complex dtype).
+        Needed for decentralized and iterative_template methods.
     peak_locations: numpy array
         Complex dtype with "x", "y", "z" fields
+        Needed for decentralized and iterative_template methods.
+    direction: "x" | "y" | "z", default: "y"
+        Dimension on which the motion is estimated. "y" is depth along the probe.
 
+        
+        
     {method_doc}
 
     **histogram section**
 
-    direction: "x" | "y" | "z", default: "y"
-        Dimension on which the motion is estimated. "y" is depth along the probe.
-    bin_duration_s: float, default: 10
-        Bin duration in second
-    bin_um: float, default: 10
-        Spatial bin size in micrometers
-    margin_um: float, default: 0
-        Margin in um to exclude from histogram estimation and
-        non-rigid smoothing functions to avoid edge effects.
-        Positive margin extrapolate out of the probe the motion.
-        Negative margin crop the motion on the border
 
     **non-rigid section**
 
     rigid : bool, default: False
         Compute rigid (one motion for the entire probe) or non rigid motion
         Rigid computation is equivalent to non-rigid with only one window with rectangular shape.
-    win_shape: "gaussian" | "rect" | "triangle", default: "gaussian"
+    win_shape : "gaussian" | "rect" | "triangle", default: "gaussian"
         The shape of the windows for non rigid.
         When rigid this is force to "rect"
-    win_step_um: float, default: 50
-        Step deteween window
-    win_sigma_um: float, default: 150
-        Sigma of the gaussian window
-
-    **motion cleaning section**
-
-    post_clean: bool, default: False
-        Apply some post cleaning to motion matrix or not
-    speed_threshold: float default: 30.
-        Detect to fast motion bump and remove then with interpolation
-    sigma_smooth_s: None or float
-        Optional smooting gaussian kernel when not None
-
+        Nonrigid window-related arguments
+        The depth domain will be broken up into windows with shape controlled by win_shape,
+        spaced by win_step_um at a margin of win_margin_um from the boundary, and with
+        width controlled by win_scale_um.
+    win_step_um : float, default: 50
+        See win_shape
+    win_scale_um : float, default: 150
+        See win_shape
+    win_margin_um : float, default: 0.
+    See win_shape
+        
+        
     extra_outputs: bool, default: False
         If True then return an extra dict that contains variables
         to check intermediate steps (motion_histogram, non_rigid_windows, pairwise_displacement)
-    upsample_to_histogram_bin: bool or None, default: False
-        If True then upsample the returned motion array to the number of depth bins specified by bin_um.
-        When None:
-          * for non rigid case: then automatically True
-          * for rigid (non_rigid_kwargs=None): automatically False
-        This feature is in fact a bad idea and the interpolation should be done outside using better methods
     progress_bar: bool, default: False
         Display progress bar or not
     verbose: bool, default: False
@@ -113,8 +95,19 @@ def estimate_motion(
         Optional output if `extra_outputs=True`
         This dict contain histogram, pairwise_displacement usefull for ploting.
     """
-    # TODO handle multi segment one day
-    assert recording.get_num_segments() == 1
+
+    if margin_um is not None:
+        warnings.warn("estimate_motion() margin_um has been removed used hist_margin_um or win_margin_um")
+
+
+    # TODO handle multi segment one day : Charlie this is for you
+    assert recording.get_num_segments() == 1, "At the moment estimate_motion handle only unique segment"
+
+    method_class = estimate_motion_methods[method]
+
+    if method_class.need_peak_location:
+        if peaks is None or peak_locations is None:
+            raise ValueError(f"estimate_motion: the method {method} need peaks and peak_locations")
 
     if extra_outputs:
         extra = {}
@@ -122,59 +115,46 @@ def estimate_motion(
         extra = None
 
     # contact positions
-    probe = recording.get_probe()
-    dim = ["x", "y", "z"].index(direction)
-    contact_pos = probe.contact_positions[:, dim]
+    # probe = recording.get_probe()
+    # dim = ["x", "y", "z"].index(direction)
+    # contact_pos = probe.contact_positions[:, dim]
 
-    # spatial bins
-    spatial_bin_edges = get_spatial_bin_edges(recording, direction, margin_um, bin_um)
-    spatial_bin_centers = 0.5 * (spatial_bin_edges[1:] + spatial_bin_edges[:-1])
+    # # spatial histogram bins
+    # spatial_bin_edges = get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um)
+    # spatial_bin_centers = 0.5 * (spatial_bin_edges[1:] + spatial_bin_edges[:-1])
 
-    # get windows
-    non_rigid_windows, non_rigid_window_centers = get_windows(
-        rigid, contact_pos, spatial_bin_centers, margin_um, win_step_um, win_sigma_um, win_shape
-    )
+    # # get spatial windows
+    # non_rigid_windows, non_rigid_window_centers = get_windows(
+    #     rigid, contact_pos, spatial_bin_centers, win_margin_um, win_step_um, win_scale_um, win_shape
+    # )
 
-    if extra_outputs:
-        extra["non_rigid_windows"] = non_rigid_windows
+    # if extra_outputs:
+    #     extra["non_rigid_windows"] = non_rigid_windows
 
     # run method
-    method_class = estimate_motion_methods[method]
-    motion_array, temporal_bins = method_class.run(
+    
+    motion = method_class.run(
         recording,
         peaks,
         peak_locations,
         direction,
-        bin_duration_s,
-        bin_um,
-        spatial_bin_edges,
-        non_rigid_windows,
+
+        # bin_um,
+        # spatial_bin_edges,
+        # non_rigid_windows,
+        rigid,
+        win_shape,
+        win_step_um,
+        win_scale_um,
+        win_margin_um,
+
         verbose,
         progress_bar,
         extra,
         **method_kwargs,
     )
 
-    # replace nan by zeros
-    np.nan_to_num(motion_array, copy=False)
-
-    if post_clean:
-        motion_array = clean_motion_vector(
-            motion_array, temporal_bins, bin_duration_s, speed_threshold=speed_threshold, sigma_smooth_s=sigma_smooth_s
-        )
-
-    if upsample_to_histogram_bin is None:
-        upsample_to_histogram_bin = not rigid
-    if upsample_to_histogram_bin:
-        extra["motion_array"] = motion_array
-        extra["non_rigid_window_centers"] = non_rigid_window_centers
-        non_rigid_windows = np.array(non_rigid_windows)
-        non_rigid_windows /= non_rigid_windows.sum(axis=0, keepdims=True)
-        non_rigid_window_centers = spatial_bin_edges[:-1] + bin_um / 2
-        motion_array = motion_array @ non_rigid_windows
-
-    # TODO handle multi segment
-    motion = Motion([motion_array], [temporal_bins], non_rigid_window_centers, direction=direction)
+    # motion = Motion([motion_array], [temporal_bins], non_rigid_window_centers, direction=direction)
 
     if extra_outputs:
         return motion, extra
@@ -182,1272 +162,7 @@ def estimate_motion(
         return motion
 
 
-class DecentralizedRegistration:
-    """
-    Method developed by the Paninski's group from Columbia university:
-    Charlie Windolf, Julien Boussard, Erdem Varol, Hyun Dong Lee
-
-    This method is also known as DREDGe, but this implemenation does not use LFP signals.
-
-    Original reference:
-    DECENTRALIZED MOTION INFERENCE AND REGISTRATION OF NEUROPIXEL DATA
-    https://ieeexplore.ieee.org/document/9414145
-    https://proceedings.neurips.cc/paper/2021/hash/b950ea26ca12daae142bd74dba4427c8-Abstract.html
-
-    This code was improved during Spike Sorting NY Hackathon 2022 by Erdem Varol and Charlie Windolf.
-    An additional major improvement can be found in this paper:
-    https://www.biorxiv.org/content/biorxiv/early/2022/12/05/2022.12.04.519043.full.pdf
-
-
-    Here are some various implementations by the original team:
-    https://github.com/int-brain-lab/spikes_localization_registration/blob/main/registration_pipeline/image_based_motion_estimate.py#L211
-    https://github.com/cwindolf/spike-psvae/tree/main/spike_psvae
-    https://github.com/evarol/DREDge
-    """
-
-    name = "decentralized"
-    params_doc = """
-    histogram_depth_smooth_um: None or float
-        Optional gaussian smoother on histogram on depth axis.
-        This is given as the sigma of the gaussian in micrometers.
-    histogram_time_smooth_s: None or float
-        Optional gaussian smoother on histogram on time axis.
-        This is given as the sigma of the gaussian in seconds.
-    pairwise_displacement_method: "conv" or "phase_cross_correlation"
-        How to estimate the displacement in the pairwise matrix.
-    max_displacement_um: float
-        Maximum possible displacement in micrometers.
-    weight_scale: "linear" or "exp"
-        For parwaise displacement, how to to rescale the associated weight matrix.
-    error_sigma: float, default: 0.2
-        In case weight_scale="exp" this controls the sigma of the exponential.
-    conv_engine: "numpy" or "torch" or None, default: None
-        In case of pairwise_displacement_method="conv", what library to use to compute
-        the underlying correlation
-    torch_device=None
-        In case of conv_engine="torch", you can control which device (cpu or gpu)
-    batch_size: int
-        Size of batch for the convolution. Increasing this will speed things up dramatically
-        on GPUs and sometimes on CPU as well.
-    corr_threshold: float
-        Minimum correlation between pair of time bins in order for these to be
-        considered when optimizing a global displacment vector to align with
-        the pairwise displacements.
-    time_horizon_s: None or float
-        When not None the parwise discplament matrix is computed in a small time horizon.
-        In short only pair of bins close in time.
-        So the pariwaise matrix is super sparse and have values only the diagonal.
-    convergence_method: "lsmr" | "lsqr_robust" | "gradient_descent", default: "lsqr_robust"
-        Which method to use to compute the global displacement vector from the pairwise matrix.
-    robust_regression_sigma: float
-        Use for convergence_method="lsqr_robust" for iterative selection of the regression.
-    temporal_prior : bool, default: True
-        Ensures continuity across time, unless there is evidence in the recording for jumps.
-    spatial_prior : bool, default: False
-        Ensures continuity across space. Not usually necessary except in recordings with
-        glitches across space.
-    force_spatial_median_continuity: bool, default: False
-        When spatial_prior=False we can optionally apply a median continuity across spatial windows.
-    reference_displacement : string, one of: "mean", "median", "time", "mode_search"
-        Strategy for picking what is considered displacement=0.
-         - "mean" : the mean displacement is subtracted
-         - "median" : the median displacement is subtracted
-         - "time" : the displacement at a given time (in seconds) is subtracted
-         - "mode_search" : an attempt is made to guess the mode. needs work.
-    lsqr_robust_n_iter: int
-        Number of iteration for convergence_method="lsqr_robust".
-    """
-
-    @classmethod
-    def run(
-        cls,
-        recording,
-        peaks,
-        peak_locations,
-        direction,
-        bin_duration_s,
-        bin_um,
-        spatial_bin_edges,
-        non_rigid_windows,
-        verbose,
-        progress_bar,
-        extra,
-        histogram_depth_smooth_um=None,
-        histogram_time_smooth_s=None,
-        pairwise_displacement_method="conv",
-        max_displacement_um=100.0,
-        weight_scale="linear",
-        error_sigma=0.2,
-        conv_engine=None,
-        torch_device=None,
-        batch_size=1,
-        corr_threshold=0.0,
-        time_horizon_s=None,
-        convergence_method="lsqr_robust",
-        soft_weights=False,
-        normalized_xcorr=True,
-        centered_xcorr=True,
-        temporal_prior=True,
-        spatial_prior=False,
-        force_spatial_median_continuity=False,
-        reference_displacement="median",
-        reference_displacement_time_s=0,
-        robust_regression_sigma=2,
-        lsqr_robust_n_iter=20,
-        weight_with_amplitude=False,
-    ):
-        # use torch if installed
-        if conv_engine is None:
-            conv_engine = "torch" if HAVE_TORCH else "numpy"
-
-        # make 2D histogram raster
-        if verbose:
-            print("Computing motion histogram")
-
-        motion_histogram, temporal_hist_bin_edges, spatial_hist_bin_edges = make_2d_motion_histogram(
-            recording,
-            peaks,
-            peak_locations,
-            direction=direction,
-            bin_duration_s=bin_duration_s,
-            spatial_bin_edges=spatial_bin_edges,
-            weight_with_amplitude=weight_with_amplitude,
-        )
-        import scipy.signal
-
-        if histogram_depth_smooth_um is not None:
-            bins = np.arange(motion_histogram.shape[1]) * bin_um
-            bins = bins - np.mean(bins)
-            smooth_kernel = np.exp(-(bins**2) / (2 * histogram_depth_smooth_um**2))
-            smooth_kernel /= np.sum(smooth_kernel)
-
-            motion_histogram = scipy.signal.fftconvolve(motion_histogram, smooth_kernel[None, :], mode="same", axes=1)
-
-        if histogram_time_smooth_s is not None:
-            bins = np.arange(motion_histogram.shape[0]) * bin_duration_s
-            bins = bins - np.mean(bins)
-            smooth_kernel = np.exp(-(bins**2) / (2 * histogram_time_smooth_s**2))
-            smooth_kernel /= np.sum(smooth_kernel)
-            motion_histogram = scipy.signal.fftconvolve(motion_histogram, smooth_kernel[:, None], mode="same", axes=0)
-
-        if extra is not None:
-            extra["motion_histogram"] = motion_histogram
-            extra["pairwise_displacement_list"] = []
-            extra["temporal_hist_bin_edges"] = temporal_hist_bin_edges
-            extra["spatial_hist_bin_edges"] = spatial_hist_bin_edges
-
-        # temporal bins are bin center
-        temporal_bins = 0.5 * (temporal_hist_bin_edges[1:] + temporal_hist_bin_edges[:-1])
-
-        motion = np.zeros((temporal_bins.size, len(non_rigid_windows)), dtype=np.float64)
-        windows_iter = non_rigid_windows
-        if progress_bar:
-            windows_iter = tqdm(windows_iter, desc="windows")
-        if spatial_prior:
-            all_pairwise_displacements = np.empty(
-                (len(non_rigid_windows), temporal_bins.size, temporal_bins.size), dtype=np.float64
-            )
-            all_pairwise_displacement_weights = np.empty(
-                (len(non_rigid_windows), temporal_bins.size, temporal_bins.size), dtype=np.float64
-            )
-        for i, win in enumerate(windows_iter):
-            window_slice = np.flatnonzero(win > 1e-5)
-            window_slice = slice(window_slice[0], window_slice[-1])
-            if verbose:
-                print(f"Computing pairwise displacement: {i + 1} / {len(non_rigid_windows)}")
-
-            pairwise_displacement, pairwise_displacement_weight = compute_pairwise_displacement(
-                motion_histogram[:, window_slice],
-                bin_um,
-                window=win[window_slice],
-                method=pairwise_displacement_method,
-                weight_scale=weight_scale,
-                error_sigma=error_sigma,
-                conv_engine=conv_engine,
-                torch_device=torch_device,
-                batch_size=batch_size,
-                max_displacement_um=max_displacement_um,
-                normalized_xcorr=normalized_xcorr,
-                centered_xcorr=centered_xcorr,
-                corr_threshold=corr_threshold,
-                time_horizon_s=time_horizon_s,
-                bin_duration_s=bin_duration_s,
-                progress_bar=False,
-            )
-
-            if spatial_prior:
-                all_pairwise_displacements[i] = pairwise_displacement
-                all_pairwise_displacement_weights[i] = pairwise_displacement_weight
-
-            if extra is not None:
-                extra["pairwise_displacement_list"].append(pairwise_displacement)
-
-            if verbose:
-                print(f"Computing global displacement: {i + 1} / {len(non_rigid_windows)}")
-
-            # TODO: if spatial_prior, do this after the loop
-            if not spatial_prior:
-                motion[:, i] = compute_global_displacement(
-                    pairwise_displacement,
-                    pairwise_displacement_weight=pairwise_displacement_weight,
-                    convergence_method=convergence_method,
-                    robust_regression_sigma=robust_regression_sigma,
-                    lsqr_robust_n_iter=lsqr_robust_n_iter,
-                    temporal_prior=temporal_prior,
-                    spatial_prior=spatial_prior,
-                    soft_weights=soft_weights,
-                    progress_bar=False,
-                )
-
-        if spatial_prior:
-            motion = compute_global_displacement(
-                all_pairwise_displacements,
-                pairwise_displacement_weight=all_pairwise_displacement_weights,
-                convergence_method=convergence_method,
-                robust_regression_sigma=robust_regression_sigma,
-                lsqr_robust_n_iter=lsqr_robust_n_iter,
-                temporal_prior=temporal_prior,
-                spatial_prior=spatial_prior,
-                soft_weights=soft_weights,
-                progress_bar=False,
-            )
-        elif len(non_rigid_windows) > 1:
-            # if spatial_prior is False, we still want keep the spatial bins
-            # correctly offset from each other
-            if force_spatial_median_continuity:
-                for i in range(len(non_rigid_windows) - 1):
-                    motion[:, i + 1] -= np.median(motion[:, i + 1] - motion[:, i])
-
-        # try to avoid constant offset
-        # let the user choose how to do this. here are some ideas.
-        # (one can also -= their own number on the result of this function.)
-        if reference_displacement == "mean":
-            motion -= motion.mean()
-        elif reference_displacement == "median":
-            motion -= np.median(motion)
-        elif reference_displacement == "time":
-            # reference the motion to 0 at a specific time, independently in each window
-            reference_displacement_bin = np.digitize(reference_displacement_time_s, temporal_hist_bin_edges) - 1
-            motion -= motion[reference_displacement_bin, :]
-        elif reference_displacement == "mode_search":
-            # just a sketch of an idea
-            # things might want to change, should have a configurable bin size,
-            # should use a call to histogram instead of the loop, ...
-            step_size = 0.1
-            round_mode = np.round  # floor?
-            best_ref = np.median(motion)
-            max_zeros = np.sum(round_mode(motion - best_ref) == 0)
-            for ref in np.arange(np.floor(motion.min()), np.ceil(motion.max()), step_size):
-                n_zeros = np.sum(round_mode(motion - ref) == 0)
-                if n_zeros > max_zeros:
-                    max_zeros = n_zeros
-                    best_ref = ref
-            motion -= best_ref
-
-        return motion, temporal_bins
-
-
-class IterativeTemplateRegistration:
-    """
-    Alignment function implemented by Kilosort2.5 and ported from pykilosort:
-    https://github.com/int-brain-lab/pykilosort/blob/ibl_prod/pykilosort/datashift2.py#L166
-
-    The main difference with respect to the original implementation are:
-     * scipy is used for gaussian smoothing
-     * windowing is implemented as gaussian tapering (instead of rectangular blocks)
-     * the 3d histogram is constructed in less cryptic way
-     * peak_locations are computed outside and so can either center fo mass or monopolar trianglation
-       contrary to kilosort2.5 use exclusively center of mass
-
-    See https://www.science.org/doi/abs/10.1126/science.abf4588?cookieSet=1
-
-    Ported by Alessio Buccino into SpikeInterface
-    """
-
-    name = "iterative_template"
-    params_doc = """
-    num_amp_bins: int, default: 20
-        number ob bins in the histogram on the log amplitues dimension
-    num_shifts_global: int, default: 15
-        Number of spatial bin shifts to consider for global alignment
-    num_iterations: int, default: 10
-        Number of iterations for global alignment procedure
-    num_shifts_block: int, default: 5
-        Number of spatial bin shifts to consider for non-rigid alignment
-    smoothing_sigma: float, default: 0.5
-        Sigma of gaussian for covariance matrices smoothing
-    kriging_sigma: float,
-        sigma parameter for kriging_kernel function
-    kriging_p: foat
-        p parameter for kriging_kernel function
-    kriging_d: float
-        d parameter for kriging_kernel function
-    """
-
-    @classmethod
-    def run(
-        cls,
-        recording,
-        peaks,
-        peak_locations,
-        direction,
-        bin_duration_s,
-        bin_um,
-        spatial_bin_edges,
-        non_rigid_windows,
-        verbose,
-        progress_bar,
-        extra,
-        num_amp_bins=20,
-        num_shifts_global=15,
-        num_iterations=10,
-        num_shifts_block=5,
-        smoothing_sigma=0.5,
-        kriging_sigma=1,
-        kriging_p=2,
-        kriging_d=2,
-    ):
-        # make a 3D histogram
-        motion_histograms, temporal_hist_bin_edges, spatial_hist_bin_edges = make_3d_motion_histograms(
-            recording,
-            peaks,
-            peak_locations,
-            direction=direction,
-            num_amp_bins=num_amp_bins,
-            bin_duration_s=bin_duration_s,
-            spatial_bin_edges=spatial_bin_edges,
-        )
-        # temporal bins are bin center
-        temporal_bins = temporal_hist_bin_edges[:-1] + bin_duration_s // 2.0
-
-        # do alignment
-        shift_indices, target_histogram, shift_covs_block = iterative_template_registration(
-            motion_histograms,
-            non_rigid_windows=non_rigid_windows,
-            num_shifts_global=num_shifts_global,
-            num_iterations=num_iterations,
-            num_shifts_block=num_shifts_block,
-            smoothing_sigma=smoothing_sigma,
-            kriging_sigma=kriging_sigma,
-            kriging_p=kriging_p,
-            kriging_d=kriging_d,
-        )
-
-        # convert to um
-        motion = -(shift_indices * bin_um)
-
-        if extra:
-            extra["motion_histograms"] = motion_histograms
-            extra["target_histogram"] = target_histogram
-            extra["shift_covs_block"] = shift_covs_block
-            extra["temporal_hist_bin_edges"] = temporal_hist_bin_edges
-            extra["spatial_hist_bin_edges"] = spatial_hist_bin_edges
-
-        return motion, temporal_bins
-
-
-_methods_list = [DecentralizedRegistration, IterativeTemplateRegistration]
+_methods_list = [DecentralizedRegistration, IterativeTemplateRegistration, DredgeLfpRegistration]
 estimate_motion_methods = {m.name: m for m in _methods_list}
 method_doc = make_multi_method_doc(_methods_list)
 estimate_motion.__doc__ = estimate_motion.__doc__.format(method_doc=method_doc)
-
-
-def get_spatial_bin_edges(recording, direction, margin_um, bin_um):
-    # contact along one axis
-    probe = recording.get_probe()
-    dim = ["x", "y", "z"].index(direction)
-    contact_pos = probe.contact_positions[:, dim]
-
-    min_ = np.min(contact_pos) - margin_um
-    max_ = np.max(contact_pos) + margin_um
-    spatial_bins = np.arange(min_, max_ + bin_um, bin_um)
-
-    return spatial_bins
-
-
-
-
-
-def make_2d_motion_histogram(
-    recording,
-    peaks,
-    peak_locations,
-    weight_with_amplitude=False,
-    direction="y",
-    bin_duration_s=1.0,
-    bin_um=2.0,
-    margin_um=50,
-    spatial_bin_edges=None,
-):
-    """
-    Generate 2d motion histogram in depth and time.
-
-    Parameters
-    ----------
-    recording : BaseRecording
-        The input recording
-    peaks : np.array
-        The peaks array
-    peak_locations : np.array
-        Array with peak locations
-    weight_with_amplitude : bool, default: False
-        If True, motion histogram is weighted by amplitudes
-    direction : "x" | "y" | "z", default: "y"
-        The depth direction
-    bin_duration_s : float, default: 1.0
-        The temporal bin duration in s
-    bin_um : float, default: 2.0
-        The spatial bin size in um. Ignored if spatial_bin_edges is given.
-    margin_um : float, default: 50
-        The margin to add to the minimum and maximum positions before spatial binning.
-        Ignored if spatial_bin_edges is given.
-    spatial_bin_edges : np.array, default: None
-        The pre-computed spatial bin edges
-
-    Returns
-    -------
-    motion_histogram
-        2d np.array with motion histogram (num_temporal_bins, num_spatial_bins)
-    temporal_bin_edges
-        1d array with temporal bin edges
-    spatial_bin_edges
-        1d array with spatial bin edges
-    """
-    n_samples = recording.get_num_samples()
-    mint_s = recording.sample_index_to_time(0)
-    maxt_s = recording.sample_index_to_time(n_samples)
-    temporal_bin_edges = np.arange(mint_s, maxt_s + bin_duration_s, bin_duration_s)
-    if spatial_bin_edges is None:
-        spatial_bin_edges = get_spatial_bin_edges(recording, direction, margin_um, bin_um)
-
-    arr = np.zeros((peaks.size, 2), dtype="float64")
-    arr[:, 0] = recording.sample_index_to_time(peaks["sample_index"])
-    arr[:, 1] = peak_locations[direction]
-
-    if weight_with_amplitude:
-        weights = np.abs(peaks["amplitude"])
-    else:
-        weights = None
-
-    motion_histogram, edges = np.histogramdd(arr, bins=(temporal_bin_edges, spatial_bin_edges), weights=weights)
-
-    # average amplitude in each bin
-    if weight_with_amplitude:
-        bin_counts, _ = np.histogramdd(arr, bins=(temporal_bin_edges, spatial_bin_edges))
-        bin_counts[bin_counts == 0] = 1
-        motion_histogram = motion_histogram / bin_counts
-
-    return motion_histogram, temporal_bin_edges, spatial_bin_edges
-
-
-def make_3d_motion_histograms(
-    recording,
-    peaks,
-    peak_locations,
-    direction="y",
-    bin_duration_s=1.0,
-    bin_um=2.0,
-    margin_um=50,
-    num_amp_bins=20,
-    log_transform=True,
-    spatial_bin_edges=None,
-):
-    """
-    Generate 3d motion histograms in depth, amplitude, and time.
-    This is used by the "iterative_template_registration" (Kilosort2.5) method.
-
-
-    Parameters
-    ----------
-    recording : BaseRecording
-        The input recording
-    peaks : np.array
-        The peaks array
-    peak_locations : np.array
-        Array with peak locations
-    direction : "x" | "y" | "z", default: "y"
-        The depth direction
-    bin_duration_s : float, default: 1.0
-        The temporal bin duration in s.
-    bin_um : float, default: 2.0
-        The spatial bin size in um. Ignored if spatial_bin_edges is given.
-    margin_um : float, default: 50
-        The margin to add to the minimum and maximum positions before spatial binning.
-        Ignored if spatial_bin_edges is given.
-    log_transform : bool, default: True
-        If True, histograms are log-transformed
-    spatial_bin_edges : np.array, default: None
-        The pre-computed spatial bin edges
-
-    Returns
-    -------
-    motion_histograms
-        3d np.array with motion histogram (num_temporal_bins, num_spatial_bins, num_amp_bins)
-    temporal_bin_edges
-        1d array with temporal bin edges
-    spatial_bin_edges
-        1d array with spatial bin edges
-    """
-    n_samples = recording.get_num_samples()
-    mint_s = recording.sample_index_to_time(0)
-    maxt_s = recording.sample_index_to_time(n_samples)
-    temporal_bin_edges = np.arange(mint_s, maxt_s + bin_duration_s, bin_duration_s)
-    if spatial_bin_edges is None:
-        spatial_bin_edges = get_spatial_bin_edges(recording, direction, margin_um, bin_um)
-
-    # pre-compute abs amplitude and ranges for scaling
-    amplitude_bin_edges = np.linspace(0, 1, num_amp_bins + 1)
-    abs_peaks = np.abs(peaks["amplitude"])
-    max_peak_amp = np.max(abs_peaks)
-    min_peak_amp = np.min(abs_peaks)
-    # log amplitudes and scale between 0-1
-    abs_peaks_log_norm = (np.log10(abs_peaks) - np.log10(min_peak_amp)) / (
-        np.log10(max_peak_amp) - np.log10(min_peak_amp)
-    )
-
-    arr = np.zeros((peaks.size, 3), dtype="float64")
-    arr[:, 0] = recording.sample_index_to_time(peaks["sample_index"])
-    arr[:, 1] = peak_locations[direction]
-    arr[:, 2] = abs_peaks_log_norm
-
-    motion_histograms, edges = np.histogramdd(
-        arr,
-        bins=(
-            temporal_bin_edges,
-            spatial_bin_edges,
-            amplitude_bin_edges,
-        ),
-    )
-
-    if log_transform:
-        motion_histograms = np.log2(1 + motion_histograms)
-
-    return motion_histograms, temporal_bin_edges, spatial_bin_edges
-
-
-def compute_pairwise_displacement(
-    motion_hist,
-    bin_um,
-    method="conv",
-    weight_scale="linear",
-    error_sigma=0.2,
-    conv_engine="numpy",
-    torch_device=None,
-    batch_size=1,
-    max_displacement_um=1500,
-    corr_threshold=0,
-    time_horizon_s=None,
-    normalized_xcorr=True,
-    centered_xcorr=True,
-    bin_duration_s=None,
-    progress_bar=False,
-    window=None,
-):
-    """
-    Compute pairwise displacement
-    """
-    from scipy import linalg
-
-    assert conv_engine in ("torch", "numpy"), f"'conv_engine' must be 'torch' or 'numpy'"
-    size = motion_hist.shape[0]
-    pairwise_displacement = np.zeros((size, size), dtype="float32")
-
-    if time_horizon_s is not None:
-        band_width = int(np.ceil(time_horizon_s / bin_duration_s))
-        if band_width >= size:
-            time_horizon_s = None
-
-    if conv_engine == "torch":
-        if torch_device is None:
-            torch_device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
-
-    if method == "conv":
-        if max_displacement_um is None:
-            n = motion_hist.shape[1] // 2
-        else:
-            n = min(
-                motion_hist.shape[1] // 2,
-                int(np.ceil(max_displacement_um // bin_um)),
-            )
-        possible_displacement = np.arange(-n, n + 1) * bin_um
-
-        xrange = trange if progress_bar else range
-
-        motion_hist_engine = motion_hist
-        window_engine = window
-        if conv_engine == "torch":
-            motion_hist_engine = torch.as_tensor(motion_hist, dtype=torch.float32, device=torch_device)
-            window_engine = torch.as_tensor(window, dtype=torch.float32, device=torch_device)
-
-        pairwise_displacement = np.empty((size, size), dtype=np.float32)
-        correlation = np.empty((size, size), dtype=motion_hist.dtype)
-
-        for i in xrange(0, size, batch_size):
-            corr = normxcorr1d(
-                motion_hist_engine,
-                motion_hist_engine[i : i + batch_size],
-                weights=window_engine,
-                padding=possible_displacement.size // 2,
-                conv_engine=conv_engine,
-                normalized=normalized_xcorr,
-                centered=centered_xcorr,
-            )
-            if conv_engine == "torch":
-                max_corr, best_disp_inds = torch.max(corr, dim=2)
-                best_disp = possible_displacement[best_disp_inds.cpu()]
-                pairwise_displacement[i : i + batch_size] = best_disp
-                correlation[i : i + batch_size] = max_corr.cpu()
-            elif conv_engine == "numpy":
-                best_disp_inds = np.argmax(corr, axis=2)
-                max_corr = np.take_along_axis(corr, best_disp_inds[..., None], 2).squeeze()
-                best_disp = possible_displacement[best_disp_inds]
-                pairwise_displacement[i : i + batch_size] = best_disp
-                correlation[i : i + batch_size] = max_corr
-
-        if corr_threshold is not None and corr_threshold > 0:
-            which = correlation > corr_threshold
-            correlation *= which
-
-    elif method == "phase_cross_correlation":
-        # this 'phase_cross_correlation' is an old idea from Julien/Charlie/Erden that is kept for testing
-        # but this is not very releveant
-        try:
-            import skimage.registration
-        except ImportError:
-            raise ImportError("To use the 'phase_cross_correlation' method install scikit-image")
-
-        errors = np.zeros((size, size), dtype="float32")
-        loop = range(size)
-        if progress_bar:
-            loop = tqdm(loop)
-        for i in loop:
-            for j in range(size):
-                shift, error, diffphase = skimage.registration.phase_cross_correlation(
-                    motion_hist[i, :], motion_hist[j, :]
-                )
-                pairwise_displacement[i, j] = shift * bin_um
-                errors[i, j] = error
-        correlation = 1 - errors
-
-    else:
-        raise ValueError(
-            f"method {method} does not exist for compute_pairwise_displacement. Current possible methods are"
-            f" 'conv' or 'phase_cross_correlation'"
-        )
-
-    if weight_scale == "linear":
-        # between 0 and 1
-        pairwise_displacement_weight = correlation
-    elif weight_scale == "exp":
-        pairwise_displacement_weight = np.exp((correlation - 1) / error_sigma)
-
-    # handle the time horizon by multiplying the weights by a
-    # matrix with the time horizon on its diagonal bands.
-    if method == "conv" and time_horizon_s is not None and time_horizon_s > 0:
-        horizon_matrix = linalg.toeplitz(
-            np.r_[np.ones(band_width, dtype=bool), np.zeros(size - band_width, dtype=bool)]
-        )
-        pairwise_displacement_weight *= horizon_matrix
-
-    return pairwise_displacement, pairwise_displacement_weight
-
-
-_possible_convergence_method = ("lsmr", "gradient_descent", "lsqr_robust")
-
-
-def compute_global_displacement(
-    pairwise_displacement,
-    pairwise_displacement_weight=None,
-    sparse_mask=None,
-    temporal_prior=True,
-    spatial_prior=True,
-    soft_weights=False,
-    convergence_method="lsmr",
-    robust_regression_sigma=2,
-    lsqr_robust_n_iter=20,
-    progress_bar=False,
-):
-    """
-    Compute global displacement
-
-    Arguments
-    ---------
-    pairwise_displacement : time x time array
-    pairwise_displacement_weight : time x time array
-    sparse_mask : time x time array
-    convergence_method : str
-        One of "gradient"
-
-    """
-    import scipy
-    from scipy.optimize import minimize
-    from scipy.sparse import csr_matrix
-    from scipy.sparse.linalg import lsqr
-    from scipy.stats import zscore
-
-    if convergence_method == "gradient_descent":
-        size = pairwise_displacement.shape[0]
-
-        D = pairwise_displacement
-        if pairwise_displacement_weight is not None or sparse_mask is not None:
-            # weighted problem
-            if pairwise_displacement_weight is None:
-                pairwise_displacement_weight = np.ones_like(D)
-            if sparse_mask is None:
-                sparse_mask = np.ones_like(D)
-            W = pairwise_displacement_weight * sparse_mask
-
-            I, J = np.nonzero(W > 0)
-            Wij = W[I, J]
-            Dij = D[I, J]
-            W = csr_matrix((Wij, (I, J)), shape=W.shape)
-            WD = csr_matrix((Wij * Dij, (I, J)), shape=W.shape)
-            fixed_terms = (W @ WD).diagonal() - (WD @ W).diagonal()
-            diag_WW = (W @ W).diagonal()
-            Wsq = W.power(2)
-
-            def obj(p):
-                return 0.5 * np.square(Wij * (Dij - (p[I] - p[J]))).sum()
-
-            def jac(p):
-                return fixed_terms - 2 * (Wsq @ p) + 2 * p * diag_WW
-
-        else:
-            # unweighted problem, it's faster when we have no weights
-            fixed_terms = -D.sum(axis=1) + D.sum(axis=0)
-
-            def obj(p):
-                v = np.square((D - (p[:, None] - p[None, :]))).sum()
-                return 0.5 * v
-
-            def jac(p):
-                return fixed_terms + 2 * (size * p - p.sum())
-
-        res = minimize(fun=obj, jac=jac, x0=D.mean(axis=1), method="L-BFGS-B")
-        if not res.success:
-            print("Global displacement gradient descent had an error")
-        displacement = res.x
-
-    elif convergence_method == "lsqr_robust":
-
-        if sparse_mask is not None:
-            I, J = np.nonzero(sparse_mask > 0)
-        elif pairwise_displacement_weight is not None:
-            I, J = pairwise_displacement_weight.nonzero()
-        else:
-            I, J = np.nonzero(np.ones_like(pairwise_displacement, dtype=bool))
-
-        nnz_ones = np.ones(I.shape[0], dtype=pairwise_displacement.dtype)
-
-        if pairwise_displacement_weight is not None:
-            if isinstance(pairwise_displacement_weight, scipy.sparse.csr_matrix):
-                W = np.array(pairwise_displacement_weight[I, J]).T
-            else:
-                W = pairwise_displacement_weight[I, J][:, None]
-        else:
-            W = nnz_ones[:, None]
-        if isinstance(pairwise_displacement, scipy.sparse.csr_matrix):
-            V = np.array(pairwise_displacement[I, J])[0]
-        else:
-            V = pairwise_displacement[I, J]
-        M = csr_matrix((nnz_ones, (range(I.shape[0]), I)), shape=(I.shape[0], pairwise_displacement.shape[0]))
-        N = csr_matrix((nnz_ones, (range(I.shape[0]), J)), shape=(I.shape[0], pairwise_displacement.shape[0]))
-        A = M - N
-        idx = np.ones(A.shape[0], dtype=bool)
-
-        # TODO: this is already soft_weights
-        xrange = trange if progress_bar else range
-        for i in xrange(lsqr_robust_n_iter):
-            p = lsqr(A[idx].multiply(W[idx]), V[idx] * W[idx][:, 0])[0]
-            idx = np.nonzero(np.abs(zscore(A @ p - V)) <= robust_regression_sigma)
-        displacement = p
-
-    elif convergence_method == "lsmr":
-        import gc
-        from scipy import sparse
-
-        D = pairwise_displacement
-
-        # weighted problem
-        if pairwise_displacement_weight is None:
-            pairwise_displacement_weight = np.ones_like(D)
-        if sparse_mask is None:
-            sparse_mask = np.ones_like(D)
-        W = pairwise_displacement_weight * sparse_mask
-        if isinstance(W, scipy.sparse.csr_matrix):
-            W = W.astype(np.float32).toarray()
-            D = D.astype(np.float32).toarray()
-
-        assert D.shape == W.shape
-
-        # first dimension is the windows dim, which could be empty in rigid case
-        # we expand dims so that below we can consider only the nonrigid case
-        if D.ndim == 2:
-            W = W[None]
-            D = D[None]
-        assert D.ndim == W.ndim == 3
-        B, T, T_ = D.shape
-        assert T == T_
-
-        # sparsify the problem
-        # we will make a list of temporal problems and then
-        # stack over the windows axis to finish.
-        # each matrix in coefficients will be (sparse_dim, T)
-        coefficients = []
-        # each vector in targets will be (T,)
-        targets = []
-        # we want to solve for a vector of shape BT, which we will reshape
-        # into a (B, T) matrix.
-        # after the loop below, we will stack a coefts matrix (sparse_dim, B, T)
-        # and a target vector of shape (B, T), both to be vectorized on last two axes,
-        # so that the target p is indexed by i = bT + t (block/window major).
-
-        # calculate coefficients matrices and target vector
-        # this list stores boolean masks corresponding to whether or not each
-        # term comes from the prior or the likelihood. we can trim the likelihood terms,
-        # but not the prior terms, in the trimmed least squares (robust iters) iterations below.
-        cannot_trim = []
-        for Wb, Db in zip(W, D):
-            # indices of active temporal pairs in this window
-            I, J = np.nonzero(Wb > 0)
-            n_sampled = I.size
-
-            # construct Kroneckers and sparse objective in this window
-            pair_weights = np.ones(n_sampled)
-            if soft_weights:
-                pair_weights = Wb[I, J]
-            Mb = sparse.csr_matrix((pair_weights, (range(n_sampled), I)), shape=(n_sampled, T))
-            Nb = sparse.csr_matrix((pair_weights, (range(n_sampled), J)), shape=(n_sampled, T))
-            block_sparse_kron = Mb - Nb
-            block_disp_pairs = pair_weights * Db[I, J]
-            cannot_trim_block = np.ones_like(block_disp_pairs, dtype=bool)
-
-            # add the temporal smoothness prior in this window
-            if temporal_prior:
-                temporal_diff_operator = sparse.diags(
-                    (
-                        np.full(T - 1, -1, dtype=block_sparse_kron.dtype),
-                        np.full(T - 1, 1, dtype=block_sparse_kron.dtype),
-                    ),
-                    offsets=(0, 1),
-                    shape=(T - 1, T),
-                )
-                block_sparse_kron = sparse.vstack(
-                    (block_sparse_kron, temporal_diff_operator),
-                    format="csr",
-                )
-                block_disp_pairs = np.concatenate(
-                    (block_disp_pairs, np.zeros(T - 1)),
-                )
-                cannot_trim_block = np.concatenate(
-                    (cannot_trim_block, np.zeros(T - 1, dtype=bool)),
-                )
-
-            coefficients.append(block_sparse_kron)
-            targets.append(block_disp_pairs)
-            cannot_trim.append(cannot_trim_block)
-        coefficients = sparse.block_diag(coefficients)
-        targets = np.concatenate(targets, axis=0)
-        cannot_trim = np.concatenate(cannot_trim, axis=0)
-
-        # spatial smoothness prior: penalize difference of each block's
-        # displacement with the next.
-        # only if B > 1, and not in the last window.
-        # this is a (BT, BT) sparse matrix D such that:
-        # entry at (i, j) is:
-        #  {   1 if i = j, i.e., i = j = bT + t for b = 0,...,B-2
-        #  {  -1 if i = bT + t and j = (b+1)T + t for b = 0,...,B-2
-        #  {   0 otherwise.
-        # put more simply, the first (B-1)T diagonal entries are 1,
-        # and entries (i, j) such that i = j - T are -1.
-        if B > 1 and spatial_prior:
-            spatial_diff_operator = sparse.diags(
-                (
-                    np.ones((B - 1) * T, dtype=block_sparse_kron.dtype),
-                    np.full((B - 1) * T, -1, dtype=block_sparse_kron.dtype),
-                ),
-                offsets=(0, T),
-                shape=((B - 1) * T, B * T),
-            )
-            coefficients = sparse.vstack((coefficients, spatial_diff_operator))
-            targets = np.concatenate((targets, np.zeros((B - 1) * T, dtype=targets.dtype)))
-            cannot_trim = np.concatenate((cannot_trim, np.zeros((B - 1) * T, dtype=bool)))
-        coefficients = coefficients.tocsr()
-
-        # initialize at the column mean of pairwise displacements (in each window)
-        p0 = D.mean(axis=2).reshape(B * T)
-
-        # use LSMR to solve the whole problem || targets - coefficients @ motion ||^2
-        iters = range(max(1, lsqr_robust_n_iter))
-        if progress_bar and lsqr_robust_n_iter > 1:
-            iters = tqdm(iters, desc="robust lsqr")
-        for it in iters:
-            # trim active set -- start with no trimming
-            idx = slice(None)
-            if it:
-                idx = np.flatnonzero(
-                    cannot_trim | (np.abs(zscore(coefficients @ displacement - targets)) <= robust_regression_sigma)
-                )
-
-            # solve trimmed ols problem
-            displacement, *_ = sparse.linalg.lsmr(coefficients[idx], targets[idx], x0=p0)
-
-            # warm start next iteration
-            p0 = displacement
-            # Cleanup lsmr memory (see https://stackoverflow.com/questions/56147713/memory-leak-in-scipy)
-            # TODO: check if this gets fixed in scipy
-            gc.collect()
-
-        displacement = displacement.reshape(B, T).T
-    else:
-        raise ValueError(
-            f"Method {convergence_method} doesn't exist for compute_global_displacement"
-            f" possible values for 'convergence_method' are {_possible_convergence_method}"
-        )
-
-    return np.squeeze(displacement)
-
-
-def iterative_template_registration(
-    spikecounts_hist_images,
-    non_rigid_windows=None,
-    num_shifts_global=15,
-    num_iterations=10,
-    num_shifts_block=5,
-    smoothing_sigma=0.5,
-    kriging_sigma=1,
-    kriging_p=2,
-    kriging_d=2,
-):
-    """
-
-    Parameters
-    ----------
-
-    spikecounts_hist_images : np.ndarray
-        Spike count histogram images (num_temporal_bins, num_spatial_bins, num_amps_bins)
-    non_rigid_windows : list, default: None
-        If num_non_rigid_windows > 1, this argument is required and it is a list of
-        windows to taper spatial bins in different blocks
-    num_shifts_global : int, default: 15
-        Number of spatial bin shifts to consider for global alignment
-    num_iterations : int, default: 10
-        Number of iterations for global alignment procedure
-    num_shifts_block : int, default: 5
-        Number of spatial bin shifts to consider for non-rigid alignment
-    smoothing_sigma : float, default: 0.5
-        Sigma of gaussian for covariance matrices smoothing
-    kriging_sigma : float, default: 1
-        sigma parameter for kriging_kernel function
-    kriging_p : float, default: 2
-        p parameter for kriging_kernel function
-    kriging_d : float, default: 2
-        d parameter for kriging_kernel function
-
-    Returns
-    -------
-    optimal_shift_indices
-        Optimal shifts for each temporal and spatial bin (num_temporal_bins, num_non_rigid_windows)
-    target_spikecount_hist
-        Target histogram used for alignment (num_spatial_bins, num_amps_bins)
-    """
-    from scipy.ndimage import gaussian_filter, gaussian_filter1d
-
-    # F is y bins by amp bins by batches
-    # ysamp are the coordinates of the y bins in um
-    spikecounts_hist_images = spikecounts_hist_images.swapaxes(0, 1).swapaxes(1, 2)
-    num_temporal_bins = spikecounts_hist_images.shape[2]
-
-    # look up and down this many y bins to find best alignment
-    shift_covs = np.zeros((2 * num_shifts_global + 1, num_temporal_bins))
-    shifts = np.arange(-num_shifts_global, num_shifts_global + 1)
-
-    # mean subtraction to compute covariance
-    F = spikecounts_hist_images
-    Fg = F - np.mean(F, axis=0)
-
-    # initialize the target "frame" for alignment with a single sample
-    # here we removed min(299, ...)
-    F0 = Fg[:, :, np.floor(num_temporal_bins / 2).astype("int") - 1]
-    F0 = F0[:, :, np.newaxis]
-
-    # first we do rigid registration by integer shifts
-    # everything is iteratively aligned until most of the shifts become 0.
-    best_shifts = np.zeros((num_iterations, num_temporal_bins))
-    for iteration in range(num_iterations):
-        for t, shift in enumerate(shifts):
-            # for each NEW potential shift, estimate covariance
-            Fs = np.roll(Fg, shift, axis=0)
-            shift_covs[t, :] = np.mean(Fs * F0, axis=(0, 1))
-        if iteration + 1 < num_iterations:
-            # estimate the best shifts
-            imax = np.argmax(shift_covs, axis=0)
-            # align the data by these integer shifts
-            for t, shift in enumerate(shifts):
-                ibest = imax == t
-                Fg[:, :, ibest] = np.roll(Fg[:, :, ibest], shift, axis=0)
-                best_shifts[iteration, ibest] = shift
-            # new target frame based on our current best alignment
-            F0 = np.mean(Fg, axis=2)[:, :, np.newaxis]
-    target_spikecount_hist = F0[:, :, 0]
-
-    # now we figure out how to split the probe into nblocks pieces
-    # if len(non_rigid_windows) = 1, then we're doing rigid registration
-    num_non_rigid_windows = len(non_rigid_windows)
-
-    # for each small block, we only look up and down this many samples to find
-    # nonrigid shift
-    shifts_block = np.arange(-num_shifts_block, num_shifts_block + 1)
-    num_shifts = len(shifts_block)
-    shift_covs_block = np.zeros((2 * num_shifts_block + 1, num_temporal_bins, num_non_rigid_windows))
-
-    # this part determines the up/down covariance for each block without
-    # shifting anything
-    for window_index in range(num_non_rigid_windows):
-        win = non_rigid_windows[window_index]
-        window_slice = np.flatnonzero(win > 1e-5)
-        window_slice = slice(window_slice[0], window_slice[-1])
-        tiled_window = win[window_slice, np.newaxis, np.newaxis]
-        Ftaper = Fg[window_slice] * np.tile(tiled_window, (1,) + Fg.shape[1:])
-        for t, shift in enumerate(shifts_block):
-            Fs = np.roll(Ftaper, shift, axis=0)
-            F0taper = F0[window_slice] * np.tile(tiled_window, (1,) + F0.shape[1:])
-            shift_covs_block[t, :, window_index] = np.mean(Fs * F0taper, axis=(0, 1))
-
-    # gaussian smoothing:
-    # here the original my_conv2_cpu is substituted with scipy gaussian_filters
-    shift_covs_block_smooth = shift_covs_block.copy()
-    shifts_block_up = np.linspace(-num_shifts_block, num_shifts_block, (2 * num_shifts_block * 10) + 1)
-    # 1. 2d smoothing over time and blocks dimensions for each shift
-    for shift_index in range(num_shifts):
-        shift_covs_block_smooth[shift_index, :, :] = gaussian_filter(
-            shift_covs_block_smooth[shift_index, :, :], smoothing_sigma
-        )  # some additional smoothing for robustness, across all dimensions
-    # 2. 1d smoothing over shift dimension for each spatial block
-    for window_index in range(num_non_rigid_windows):
-        shift_covs_block_smooth[:, :, window_index] = gaussian_filter1d(
-            shift_covs_block_smooth[:, :, window_index], smoothing_sigma, axis=0
-        )  # some additional smoothing for robustness, across all dimensions
-    upsample_kernel = kriging_kernel(
-        shifts_block[:, np.newaxis], shifts_block_up[:, np.newaxis], sigma=kriging_sigma, p=kriging_p, d=kriging_d
-    )
-
-    optimal_shift_indices = np.zeros((num_temporal_bins, num_non_rigid_windows))
-    for window_index in range(num_non_rigid_windows):
-        # using the upsampling kernel K, get the upsampled cross-correlation
-        # curves
-        upsampled_cov = upsample_kernel.T @ shift_covs_block_smooth[:, :, window_index]
-
-        # find the max index of these curves
-        imax = np.argmax(upsampled_cov, axis=0)
-
-        # add the value of the shift to the last row of the matrix of shifts
-        # (as if it was the last iteration of the main rigid loop )
-        best_shifts[num_iterations - 1, :] = shifts_block_up[imax]
-
-        # the sum of all the shifts equals the final shifts for this block
-        optimal_shift_indices[:, window_index] = np.sum(best_shifts, axis=0)
-
-    return optimal_shift_indices, target_spikecount_hist, shift_covs_block
-
-
-# TODO charlie sam : make a unique function for this
-# at the moment this is the legacy one ported in spikeinterface
-# the one in deredge.py is more recent
-def normxcorr1d(
-    template,
-    x,
-    weights=None,
-    centered=True,
-    normalized=True,
-    padding="same",
-    conv_engine="torch",
-):
-    """normxcorr1d: Normalized cross-correlation, optionally weighted
-
-    The API is like torch's F.conv1d, except I have accidentally
-    changed the position of input/weights -- template acts like weights,
-    and x acts like input.
-
-    Returns the cross-correlation of `template` and `x` at spatial lags
-    determined by `mode`. Useful for estimating the location of `template`
-    within `x`.
-
-    This might not be the most efficient implementation -- ideas welcome.
-    It uses a direct convolutional translation of the formula
-        corr = (E[XY] - EX EY) / sqrt(var X * var Y)
-
-    This also supports weights! In that case, the usual adaptation of
-    the above formula is made to the weighted case -- and all of the
-    normalizations are done per block in the same way.
-
-    Parameters
-    ----------
-    template : tensor, shape (num_templates, length)
-        The reference template signal
-    x : tensor, 1d shape (length,) or 2d shape (num_inputs, length)
-        The signal in which to find `template`
-    weights : tensor, shape (length,)
-        Will use weighted means, variances, covariances if supplied.
-    centered : bool
-        If true, means will be subtracted (per weighted patch).
-    normalized : bool
-        If true, normalize by the variance (per weighted patch).
-    padding : str
-        How far to look? if unset, we'll use half the length
-    conv_engine : string, one of "torch", "numpy"
-        What library to use for computing cross-correlations.
-        If numpy, falls back to the scipy correlate function.
-
-    Returns
-    -------
-    corr : tensor
-    """
-    if conv_engine == "torch":
-        assert HAVE_TORCH
-        conv1d = F.conv1d
-        npx = torch
-    elif conv_engine == "numpy":
-        conv1d = scipy_conv1d
-        npx = np
-    else:
-        raise ValueError(f"Unknown conv_engine {conv_engine}. 'conv_engine' must be 'torch' or 'numpy'")
-
-    x = npx.atleast_2d(x)
-    num_templates, length = template.shape
-    num_inputs, length_ = template.shape
-    assert length == length_
-
-    # generalize over weighted / unweighted case
-    device_kw = {} if conv_engine == "numpy" else dict(device=x.device)
-    ones = npx.ones((1, 1, length), dtype=x.dtype, **device_kw)
-    no_weights = weights is None
-    if no_weights:
-        weights = ones
-        wt = template[:, None, :]
-    else:
-        assert weights.shape == (length,)
-        weights = weights[None, None]
-        wt = template[:, None, :] * weights
-
-    # conv1d valid rule:
-    # (B,1,L),(O,1,L)->(B,O,L)
-
-    # compute expectations
-    # how many points in each window? seems necessary to normalize
-    # for numerical stability.
-    N = conv1d(ones, weights, padding=padding)
-    if centered:
-        Et = conv1d(ones, wt, padding=padding)
-        Et /= N
-        Ex = conv1d(x[:, None, :], weights, padding=padding)
-        Ex /= N
-
-    # compute (weighted) covariance
-    # important: the formula E[XY] - EX EY is well-suited here,
-    # because the means are naturally subtracted correctly
-    # patch-wise. you couldn't pre-subtract them!
-    cov = conv1d(x[:, None, :], wt, padding=padding)
-    cov /= N
-    if centered:
-        cov -= Ex * Et
-
-    # compute variances for denominator, using var X = E[X^2] - (EX)^2
-    if normalized:
-        var_template = conv1d(ones, wt * template[:, None, :], padding=padding)
-        var_template /= N
-        var_x = conv1d(npx.square(x)[:, None, :], weights, padding=padding)
-        var_x /= N
-        if centered:
-            var_template -= npx.square(Et)
-            var_x -= npx.square(Ex)
-
-    # now find the final normxcorr
-    corr = cov  # renaming for clarity
-    if normalized:
-        corr /= npx.sqrt(var_x)
-        corr /= npx.sqrt(var_template)
-        # get rid of NaNs in zero-variance areas
-        corr[~npx.isfinite(corr)] = 0
-
-    return corr
-
-
-
-
-
-def clean_motion_vector(motion, temporal_bins, bin_duration_s, speed_threshold=30, sigma_smooth_s=None):
-    """
-    Simple machinery to remove spurious fast bump in the motion vector.
-    Also can applyt a smoothing.
-
-
-    Arguments
-    ---------
-    motion: numpy array 2d
-        Motion estimate in um.
-    temporal_bins: numpy.array 1d
-        temporal bins (bin center)
-    bin_duration_s: float
-        bin duration in second
-    speed_threshold: float (units um/s)
-        Maximum speed treshold between 2 bins allowed.
-        Expressed in um/s
-    sigma_smooth_s: None or float
-        Optional smooting gaussian kernel.
-
-    Returns
-    -------
-    corr : tensor
-
-
-    """
-    motion_clean = motion.copy()
-
-    # STEP 1 :
-    #  * detect long plateau or small peak corssing the speed thresh
-    #  * mask the period and interpolate
-    for i in range(motion.shape[1]):
-        one_motion = motion_clean[:, i]
-        speed = np.diff(one_motion, axis=0) / bin_duration_s
-        (inds,) = np.nonzero(np.abs(speed) > speed_threshold)
-        inds += 1
-        if inds.size % 2 == 1:
-            # more compicated case: number of of inds is odd must remove first or last
-            # take the smallest duration sum
-            inds0 = inds[:-1]
-            inds1 = inds[1:]
-            d0 = np.sum(inds0[1::2] - inds0[::2])
-            d1 = np.sum(inds1[1::2] - inds1[::2])
-            if d0 < d1:
-                inds = inds0
-        mask = np.ones(motion_clean.shape[0], dtype="bool")
-        for i in range(inds.size // 2):
-            mask[inds[i * 2] : inds[i * 2 + 1]] = False
-        import scipy.interpolate
-
-        f = scipy.interpolate.interp1d(temporal_bins[mask], one_motion[mask])
-        one_motion[~mask] = f(temporal_bins[~mask])
-
-    # Step 2 : gaussian smooth
-    if sigma_smooth_s is not None:
-        half_size = motion_clean.shape[0] // 2
-        if motion_clean.shape[0] % 2 == 0:
-            # take care of the shift
-            bins = (np.arange(motion_clean.shape[0]) - half_size + 1) * bin_duration_s
-        else:
-            bins = (np.arange(motion_clean.shape[0]) - half_size) * bin_duration_s
-        smooth_kernel = np.exp(-(bins**2) / (2 * sigma_smooth_s**2))
-        smooth_kernel /= np.sum(smooth_kernel)
-        smooth_kernel = smooth_kernel[:, None]
-        motion_clean = scipy.signal.fftconvolve(motion_clean, smooth_kernel, mode="same", axes=0)
-
-    return motion_clean
-
-
-def kriging_kernel(source_location, target_location, sigma=1, p=2, d=2):
-    from scipy.spatial.distance import cdist
-
-    dist_xy = cdist(source_location, target_location, metric="euclidean")
-    K = np.exp(-((dist_xy / sigma) ** p) / d)
-    return K
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index 5987a47cd2..d9c0bedb24 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -232,7 +232,7 @@ def copy(self):
 
 
 
-def get_windows(rigid, contact_pos, spatial_bin_centers, margin_um, win_step_um, win_sigma_um, win_shape,
+def get_windows(rigid, contact_pos, spatial_bin_centers, win_margin_um, win_step_um, win_scale_um, win_shape,
                 zero_threshold=None):
     """
     Generate spatial windows (taper) for non-rigid motion.
@@ -244,14 +244,14 @@ def get_windows(rigid, contact_pos, spatial_bin_centers, margin_um, win_step_um,
     rigid : bool
         If True, returns a single rectangular window
     contact_pos : np.ndarray
-        Position of electrodes (num_channels, 2)
+        Position of electrodes of the corection direction shape=(num_channels, )
     spatial_bin_centers : np.array
         The pre-computed spatial bin centers
-    margin_um : float
+    win_margin_um : float
         The margin to extend (if positive) or shrink (if negative) the probe dimension to compute windows.=
     win_step_um : float
         The steps at which windows are defined
-    win_sigma_um : float
+    win_scale_um : float
         Sigma of gaussian window (if win_shape is gaussian)
     win_shape : float
         "gaussian" | "rect"
@@ -278,13 +278,13 @@ def get_windows(rigid, contact_pos, spatial_bin_centers, margin_um, win_step_um,
         middle = (spatial_bin_centers[0] + spatial_bin_centers[-1]) / 2.0
         window_centers = np.array([middle])
     else:
-        if win_sigma_um <= win_step_um/5.:
+        if win_scale_um <= win_step_um/5.:
             warnings.warn(
-                f"get_windows(): spatial windows are probably not overlaping because {win_sigma_um=} and {win_step_um=}"
+                f"get_windows(): spatial windows are probably not overlaping because {win_scale_um=} and {win_step_um=}"
             )
 
-        min_ = np.min(contact_pos) - margin_um
-        max_ = np.max(contact_pos) + margin_um
+        min_ = np.min(contact_pos) - win_margin_um
+        max_ = np.max(contact_pos) + win_margin_um
         num_windows = int((max_ - min_) // win_step_um)
         border = ((max_ - min_) % win_step_um) / 2
         window_centers = np.arange(num_windows + 1) * win_step_um + min_ + border
@@ -292,13 +292,13 @@ def get_windows(rigid, contact_pos, spatial_bin_centers, margin_um, win_step_um,
 
         for win_center in window_centers:
             if win_shape == "gaussian":
-                win = np.exp(-((spatial_bin_centers - win_center) ** 2) / (2 * win_sigma_um**2))
+                win = np.exp(-((spatial_bin_centers - win_center) ** 2) / (2 * win_scale_um**2))
             elif win_shape == "rect":
-                win = np.abs(spatial_bin_centers - win_center) < (win_sigma_um / 2.0)
+                win = np.abs(spatial_bin_centers - win_center) < (win_scale_um / 2.0)
                 win = win.astype("float64")
             elif win_shape == "triangle":
                 center_dist = np.abs(spatial_bin_centers - win_center)
-                in_window = center_dist <= (win_sigma_um / 2.0)
+                in_window = center_dist <= (win_scale_um / 2.0)
                 win = -center_dist
                 win[~in_window] = 0
                 win[in_window] -= win[in_window].min()
@@ -349,4 +349,175 @@ def scipy_conv1d(input, weights, padding="valid"):
         for c in range(c_out):
             output[m, c] = correlate(input[m, 0], weights[c, 0], mode=mode)
 
-    return output
\ No newline at end of file
+    return output
+
+
+def get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um):
+    # contact along one axis
+    probe = recording.get_probe()
+    dim = ["x", "y", "z"].index(direction)
+    contact_pos = probe.contact_positions[:, dim]
+
+    min_ = np.min(contact_pos) - hist_margin_um
+    max_ = np.max(contact_pos) + hist_margin_um
+    spatial_bins = np.arange(min_, max_ + bin_um, bin_um)
+
+    return spatial_bins
+
+
+
+def make_2d_motion_histogram(
+    recording,
+    peaks,
+    peak_locations,
+    weight_with_amplitude=False,
+    direction="y",
+    bin_duration_s=1.0,
+    bin_um=2.0,
+    hist_margin_um=50,
+    spatial_bin_edges=None,
+):
+    """
+    Generate 2d motion histogram in depth and time.
+
+    Parameters
+    ----------
+    recording : BaseRecording
+        The input recording
+    peaks : np.array
+        The peaks array
+    peak_locations : np.array
+        Array with peak locations
+    weight_with_amplitude : bool, default: False
+        If True, motion histogram is weighted by amplitudes
+    direction : "x" | "y" | "z", default: "y"
+        The depth direction
+    bin_duration_s : float, default: 1.0
+        The temporal bin duration in s
+    bin_um : float, default: 2.0
+        The spatial bin size in um. Ignored if spatial_bin_edges is given.
+    hist_margin_um : float, default: 50
+        The margin to add to the minimum and maximum positions before spatial binning.
+        Ignored if spatial_bin_edges is given.
+    spatial_bin_edges : np.array, default: None
+        The pre-computed spatial bin edges
+
+    Returns
+    -------
+    motion_histogram
+        2d np.array with motion histogram (num_temporal_bins, num_spatial_bins)
+    temporal_bin_edges
+        1d array with temporal bin edges
+    spatial_bin_edges
+        1d array with spatial bin edges
+    """
+    n_samples = recording.get_num_samples()
+    mint_s = recording.sample_index_to_time(0)
+    maxt_s = recording.sample_index_to_time(n_samples)
+    temporal_bin_edges = np.arange(mint_s, maxt_s + bin_duration_s, bin_duration_s)
+    if spatial_bin_edges is None:
+        spatial_bin_edges = get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um)
+
+    arr = np.zeros((peaks.size, 2), dtype="float64")
+    arr[:, 0] = recording.sample_index_to_time(peaks["sample_index"])
+    arr[:, 1] = peak_locations[direction]
+
+    if weight_with_amplitude:
+        weights = np.abs(peaks["amplitude"])
+    else:
+        weights = None
+
+    motion_histogram, edges = np.histogramdd(arr, bins=(temporal_bin_edges, spatial_bin_edges), weights=weights)
+
+    # average amplitude in each bin
+    if weight_with_amplitude:
+        bin_counts, _ = np.histogramdd(arr, bins=(temporal_bin_edges, spatial_bin_edges))
+        bin_counts[bin_counts == 0] = 1
+        motion_histogram = motion_histogram / bin_counts
+
+    return motion_histogram, temporal_bin_edges, spatial_bin_edges
+
+
+def make_3d_motion_histograms(
+    recording,
+    peaks,
+    peak_locations,
+    direction="y",
+    bin_duration_s=1.0,
+    bin_um=2.0,
+    hist_margin_um=50,
+    num_amp_bins=20,
+    log_transform=True,
+    spatial_bin_edges=None,
+):
+    """
+    Generate 3d motion histograms in depth, amplitude, and time.
+    This is used by the "iterative_template_registration" (Kilosort2.5) method.
+
+
+    Parameters
+    ----------
+    recording : BaseRecording
+        The input recording
+    peaks : np.array
+        The peaks array
+    peak_locations : np.array
+        Array with peak locations
+    direction : "x" | "y" | "z", default: "y"
+        The depth direction
+    bin_duration_s : float, default: 1.0
+        The temporal bin duration in s.
+    bin_um : float, default: 2.0
+        The spatial bin size in um. Ignored if spatial_bin_edges is given.
+    hist_margin_um : float, default: 50
+        The margin to add to the minimum and maximum positions before spatial binning.
+        Ignored if spatial_bin_edges is given.
+    log_transform : bool, default: True
+        If True, histograms are log-transformed
+    spatial_bin_edges : np.array, default: None
+        The pre-computed spatial bin edges
+
+    Returns
+    -------
+    motion_histograms
+        3d np.array with motion histogram (num_temporal_bins, num_spatial_bins, num_amp_bins)
+    temporal_bin_edges
+        1d array with temporal bin edges
+    spatial_bin_edges
+        1d array with spatial bin edges
+    """
+    n_samples = recording.get_num_samples()
+    mint_s = recording.sample_index_to_time(0)
+    maxt_s = recording.sample_index_to_time(n_samples)
+    temporal_bin_edges = np.arange(mint_s, maxt_s + bin_duration_s, bin_duration_s)
+    if spatial_bin_edges is None:
+        spatial_bin_edges = get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um)
+
+    # pre-compute abs amplitude and ranges for scaling
+    amplitude_bin_edges = np.linspace(0, 1, num_amp_bins + 1)
+    abs_peaks = np.abs(peaks["amplitude"])
+    max_peak_amp = np.max(abs_peaks)
+    min_peak_amp = np.min(abs_peaks)
+    # log amplitudes and scale between 0-1
+    abs_peaks_log_norm = (np.log10(abs_peaks) - np.log10(min_peak_amp)) / (
+        np.log10(max_peak_amp) - np.log10(min_peak_amp)
+    )
+
+    arr = np.zeros((peaks.size, 3), dtype="float64")
+    arr[:, 0] = recording.sample_index_to_time(peaks["sample_index"])
+    arr[:, 1] = peak_locations[direction]
+    arr[:, 2] = abs_peaks_log_norm
+
+    motion_histograms, edges = np.histogramdd(
+        arr,
+        bins=(
+            temporal_bin_edges,
+            spatial_bin_edges,
+            amplitude_bin_edges,
+        ),
+    )
+
+    if log_transform:
+        motion_histograms = np.log2(1 + motion_histograms)
+
+    return motion_histograms, temporal_bin_edges, spatial_bin_edges
diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
index 7cba0ff6fc..c626de527f 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
@@ -153,11 +153,11 @@ def test_estimate_motion(setup_module):
             bin_duration_s=1.0,
             bin_um=10.0,
             margin_um=5,
-            output_extra_check=True,
+            extra_outputs=True,
         )
         kwargs.update(cases_kwargs)
 
-        motion, extra_check = estimate_motion(recording, peaks, peak_locations, **kwargs)
+        motion, extra = estimate_motion(recording, peaks, peak_locations, **kwargs)
         motions[name] = motion
 
         if cases_kwargs["rigid"]:
diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_utils.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_utils.py
index 0b67be39c0..73c469c955 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_utils.py
@@ -4,7 +4,7 @@
 
 import numpy as np
 import pytest
-from spikeinterface.sortingcomponents.motion_utils import Motion
+from spikeinterface.sortingcomponents.motion.motion_utils import Motion
 from spikeinterface.generation import make_one_displacement_vector
 
 if hasattr(pytest, "global_test_folder"):

From 532ea488d7bd8bd22058d64e74a8c6c0027fca79 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 26 Jun 2024 22:55:48 +0200
Subject: [PATCH 09/31] start porting dredge_ap

---
 .../sortingcomponents/motion/decentralized.py |  18 +-
 .../sortingcomponents/motion/dredge.py        | 451 +++++++++++++++++-
 .../motion/motion_estimation.py               |   4 +-
 .../sortingcomponents/motion/motion_utils.py  |  16 +
 4 files changed, 466 insertions(+), 23 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/decentralized.py b/src/spikeinterface/sortingcomponents/motion/decentralized.py
index 3b8f19cc3e..9a76b94d20 100644
--- a/src/spikeinterface/sortingcomponents/motion/decentralized.py
+++ b/src/spikeinterface/sortingcomponents/motion/decentralized.py
@@ -168,23 +168,9 @@ def run(
             bin_duration_s=bin_duration_s,
             spatial_bin_edges=spatial_bin_edges,
             weight_with_amplitude=weight_with_amplitude,
+            depth_smooth_um=histogram_depth_smooth_um,
+            time_smooth_s=histogram_time_smooth_s,
         )
-        import scipy.signal
-
-        if histogram_depth_smooth_um is not None:
-            bins = np.arange(motion_histogram.shape[1]) * bin_um
-            bins = bins - np.mean(bins)
-            smooth_kernel = np.exp(-(bins**2) / (2 * histogram_depth_smooth_um**2))
-            smooth_kernel /= np.sum(smooth_kernel)
-
-            motion_histogram = scipy.signal.fftconvolve(motion_histogram, smooth_kernel[None, :], mode="same", axes=1)
-
-        if histogram_time_smooth_s is not None:
-            bins = np.arange(motion_histogram.shape[0]) * bin_duration_s
-            bins = bins - np.mean(bins)
-            smooth_kernel = np.exp(-(bins**2) / (2 * histogram_time_smooth_s**2))
-            smooth_kernel /= np.sum(smooth_kernel)
-            motion_histogram = scipy.signal.fftconvolve(motion_histogram, smooth_kernel[:, None], mode="same", axes=0)
 
         if extra is not None:
             extra["motion_histogram"] = motion_histogram
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 70dfc86107..60d93f355c 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -14,17 +14,318 @@
 
 but here the original functions from Charlie, Julien and Erdem have been ported for an
 easier maintenance instead of making DREDge a dependency of spikeinterface.
+
+Some renaming has been done. Small details has been added.
+But this code is very similar to the original code.
+2 classes has been added : DredgeApRegistration and DredgeLfpRegistration
+but the original function dredge_ap() and dredge_online_lfp() can be used directly.
+
 """
 import warnings
 
 from tqdm.auto import trange
 import numpy as np
 
+import gc
 
 from .motion_utils import Motion, get_windows, get_window_domains, scipy_conv1d
 
 
-# TODO add direction
+# to discuss
+# margin
+# xcorr new function
+# which dataset band usefull for ?
+# dredge_ap
+# use patient 2
+
+# todo use gaussian_filter1d in historgam 2d
+# put smotthing inside the histogram function
+# put the log for weight inhitstogram
+
+
+# simple class wrapper to be compliant with estimate_motion
+class DredgeApRegistration:
+    """
+
+    """
+    name = "dredge_ap"
+    need_peak_location = True
+    params_doc = """
+
+    """
+    @classmethod
+    def run(
+        cls,
+        recording,
+        peaks,
+        peak_locations,
+        direction,
+        rigid,
+        win_shape,
+        win_step_um,
+        win_scale_um,
+        win_margin_um,
+        verbose,
+        progress_bar,
+        extra,
+        **method_kwargs,
+    ):
+        dim = ["x", "y", "z"].index(direction)
+        peak_amplitudes = peaks["amplitude"]
+        peak_depths = peak_locations[direction]
+        peak_times = recording.sample_index_to_time(peaks["sample_index"])
+
+
+        outs = dredge_ap(
+            peak_amplitudes,
+            peak_depths,
+            peak_times,
+            direction=direction,
+            rigid=rigid,
+            win_shape=win_shape,
+            win_step_um=win_step_um,
+            win_scale_um=win_scale_um,
+            win_margin_um=win_margin_um,
+            extra_outputs=(extra is not None),
+            progress_bar=progress_bar,
+            **method_kwargs,
+        )
+
+        if extra is not None:
+            motion, extra_ = outs
+            extra.update(extra_)
+        else:
+            motion = outs
+        return motion
+
+# @TODO : Charlie I started very small refactoring, I let you continue
+def dredge_ap(
+    amps,
+    depths_um,
+    times_s,
+    direction="y",
+    rigid=False,
+    # nonrigid window construction arguments
+    win_shape="gaussian",
+    win_step_um=400,
+    win_scale_um=450,
+    win_margin_um=None,
+    bin_um=1.0,
+    bin_s=1.0,
+    max_disp_um=None,
+    time_horizon_s=1000,
+    mincorr=0.1,
+    # weights arguments
+    do_window_weights=True,
+    weights_threshold_low=0.2,
+    weights_threshold_high=0.2,
+    mincorr_percentile=None,
+    mincorr_percentile_nneighbs=None,
+    # raster arguments
+    amp_scale_fn=None,
+    post_transform=np.log1p,
+    gaussian_smoothing_sigma_um=1,
+    gaussian_smoothing_sigma_s=1,
+    avg_in_bin=False,
+    count_masked_correlation=False,
+    count_bins=401,
+    count_bin_min=2,
+    # low-level keyword args
+    thomas_kw=None,
+    xcorr_kw=None,
+    # misc
+    device=None,
+    progress_bar=True,
+    extra_outputs=False,
+    precomputed_D_C_maxdisp=None,
+):
+    """Estimate motion from spikes
+
+    Spikes located at depths specified in `depths` along the probe, occurring at times in
+    seconds specified in `times` with amplitudes `amps` are used to create a 2d image of
+    the spiking activity. This image is cross-correlated with itself to produce a displacement
+    matrix (or several, one for each nonrigid window). This matrix is used to solve for a
+    motion estimate.
+
+    Arguments
+    ---------
+    amps : np.array of shape (n_spikes,)
+    depths: np.array of shape (n_spikes,)
+    times : np.array of shape (n_spikes,)
+        The amplitudes, depths (microns) and times (seconds) of input
+        spike events.
+    direction : "x" | "y", default "y"
+        Dimension on which the motion is estimated. "y" is depth along the probe.
+    rigid : bool, default=False
+        If True, ignore the nonrigid window args (win_shape, win_step_um, win_scale_um,
+        win_margin_um) and do rigid registration (equivalent to one flat window, which
+        is how it's implemented).
+    win_shape : str, default="gaussian"
+        Nonrigid window shape
+    win_step_um : float
+        Spacing between nonrigid window centers in microns
+    win_scale_um : float
+        Controls the width of nonrigid windows centers
+    win_margin_um : float
+        Distance of nonrigid windows centers from the probe boundary (-1000 means there will
+        be no window center within 1000um of the edge of the probe)
+    bin_um: float
+    bin_s : float
+        The size of the bins along depth in microns and along time in seconds.
+        The returned object's .displacement array will respect these bins.
+        Increasing these can lead to more stable estimates and faster runtimes
+        at the cost of spatial and/or temporal resolution.
+    max_disp_um : float
+        Maximum possible displacement in microns. If you can guess a number which is larger
+        than the largest displacement possible in your recording across a span of `time_horizon_s`
+        seconds, setting this value to that number can stabilize the result and speed up
+        the algorithm (since it can do less cross-correlating).
+        By default, this is set to win-scale_um / 4, or 112.5 microns. Which can be a bit
+        large!
+    time_horizon_s : float
+        "Time horizon" parameter, in seconds. Time bins separated by more seconds than this
+        will not be cross-correlated. So, if your data has nonstationarities or changes which
+        could lead to bad cross-correlations at some timescale, it can help to input that
+        value here. If this is too small, it can make the motion estimation unstable.
+    mincorr : float, between 0 and 1
+        Correlation threshold. Pairs of frames whose maximal cross correlation value is smaller
+        than this threshold will be ignored when solving for the global displacement estimate.
+    thomas_kw, xcorr_kw, raster_kw, weights_kw
+        These dictionaries allow setting parameters for fine control over the registration
+    device : str or torch.device
+        What torch device to run on? E.g., "cpu" or "cuda" or "cuda:1".
+
+    Returns
+    -------
+    motion_est : a motion_util.MotionEstimate object
+        This has a .displacement attribute which is the displacement estimate in a
+        (num_nonrigid_blocks, num_time_bins) array. It also has properties describing
+        the time and spatial bins, and methods for getting the displacement at a particular
+        time and depth. See the documentation of these classes in motion_util.py.
+    extra : dict
+        This has extra info about what happened during registration, including the nonrigid
+        windows if one wants to visualize them. Set `extra_outputs` to also save displacement
+        and correlation matrices.
+    """
+    thomas_kw = thomas_kw if thomas_kw is not None else {}
+    xcorr_kw = xcorr_kw if xcorr_kw is not None else {}
+    if time_horizon_s:
+        xcorr_kw["max_dt_bins"] = np.ceil(time_horizon_s / bin_s)
+    raster_kw = dict(
+        amp_scale_fn=amp_scale_fn,
+        post_transform=post_transform,
+        gaussian_smoothing_sigma_um=gaussian_smoothing_sigma_um,
+        gaussian_smoothing_sigma_s=gaussian_smoothing_sigma_s,
+        bin_s=bin_s,
+        bin_um=bin_um,
+        avg_in_bin=avg_in_bin,
+        return_counts=count_masked_correlation,
+        count_bins=count_bins,
+        count_bin_min=count_bin_min,
+    )
+    weights_kw = dict(
+        mincorr=mincorr,
+        time_horizon_s=time_horizon_s,
+        do_window_weights=do_window_weights,
+        weights_threshold_low=weights_threshold_low,
+        weights_threshold_high=weights_threshold_high,
+    )
+
+    # this will store return values other than the MotionEstimate
+    extra = {}
+
+    # TODO charlie switch this to make_2d_motion_histogram after having putting more option
+    raster_res = spike_raster(
+        amps,
+        depths_um,
+        times_s,
+        **raster_kw,
+    )
+    if count_masked_correlation:
+        raster, spatial_bin_edges_um, time_bin_edges_s, counts = raster_res
+    else:
+        raster, spatial_bin_edges_um, time_bin_edges_s = raster_res
+    windows, window_centers = get_windows(
+        # pseudo geom to fool spikeinterface
+        np.c_[np.zeros_like(spatial_bin_edges_um), spatial_bin_edges_um],
+        win_step_um,
+        win_scale_um,
+        spatial_bin_edges=spatial_bin_edges_um,
+        margin_um=-win_scale_um / 2 if win_margin_um is None else win_margin_um,
+        win_shape=win_shape,
+        zero_threshold=1e-5,
+        rigid=rigid,
+    )
+    if extra_outputs and count_masked_correlation:
+        extra["counts"] = counts
+
+    # cross-correlate to get D and C
+    if precomputed_D_C_maxdisp is None:
+        Ds, Cs, max_disp_um = xcorr_windows(
+            raster,
+            windows,
+            spatial_bin_edges_um,
+            win_scale_um,
+            rigid=rigid,
+            bin_um=bin_um,
+            max_disp_um=max_disp_um,
+            progress_bar=progress_bar,
+            device=device,
+            masks=(counts > 0) if count_masked_correlation else None,
+            **xcorr_kw,
+        )
+    else:
+        Ds, Cs, max_disp_um = precomputed_D_C_maxdisp
+
+    # turn Cs into weights
+    Us, wextra = weight_correlation_matrix(
+        Ds,
+        Cs,
+        windows,
+        raster,
+        spatial_bin_edges_um,
+        time_bin_edges_s,
+        raster_kw,
+        lambda_t=thomas_kw.get("lambda_t", DEFAULT_LAMBDA_T),
+        eps=thomas_kw.get("eps", DEFAULT_EPS),
+        progress_bar=progress_bar,
+        in_place=not extra_outputs,
+        **weights_kw,
+    )
+    extra.update({k: wextra[k] for k in wextra if k not in ("S", "U")})
+    if extra_outputs:
+        extra.update({k: wextra[k] for k in wextra if k in ("S", "U")})
+    del wextra
+    if extra_outputs:
+        extra["D"] = Ds
+        extra["C"] = Cs
+    del Cs
+
+    # @charlie : is this needed ?
+    gc.collect()
+
+    # solve for P
+    # now we can do our tridiag solve
+    displacement, textra = thomas_solve(Ds, Us, progress_bar=progress_bar, **thomas_kw)
+    if extra_outputs:
+        extra.update(textra)
+    del textra
+
+    if extra_outputs:
+        extra["windows"] = windows
+        extra["window_centers"] = window_centers
+        extra["max_disp_um"] = max_disp_um
+
+    time_bin_centers = 0.5 * (time_bin_edges_s[1:] + time_bin_edges_s[:-1])
+    spatial_bin_centers_um = 0.5 * (spatial_bin_edges_um[1:] + spatial_bin_edges_um[:-1])
+    
+    motion = Motion([displacement], [time_bin_centers], spatial_bin_centers_um, direction=direction)
+
+    if extra_outputs:
+        return motion, extra
+    else:
+        return motion
+
 
 # simple class wrapper to be compliant with estimate_motion
 class DredgeLfpRegistration:
@@ -72,10 +373,9 @@ def run(
         if extra is not None:
             motion, extra_ = outs
             extra.update(extra_)
-
         else:
             motion = outs
-
+        return motion
 
 
 
@@ -117,6 +417,8 @@ def dredge_online_lfp(
         be the target resolution of the registration, so definitely use SpikeInterface
         to resample your recording to, say, 250Hz (or a value you like) rather than
         estimating motion at the original frequency (which may be high).
+    direction : "x" | "y", default "y"
+        Dimension on which the motion is estimated. "y" is depth along the probe.
     rigid : boolean, optional
         If True, window-related arguments are ignored and we do rigid registration
     win_shape, win_step_um, win_scale_um, win_margin_um : float
@@ -310,7 +612,7 @@ def dredge_online_lfp(
         t0, t1 = t1, t2
         traces0 = traces1
 
-    motion = Motion([P_online.T], [lfp_recording.get_times(0)], window_centers, direction="y")
+    motion = Motion([P_online.T], [lfp_recording.get_times(0)], window_centers, direction=direction)
 
     if extra_outputs:
         return motion, extra
@@ -941,4 +1243,143 @@ def normxcorr1d(
         corr /= npx.sqrt(var_x)
         corr /= npx.sqrt(var_template)
 
-    return corr
\ No newline at end of file
+    return corr
+
+
+def get_weights(
+    Ds,
+    Ss,
+    Sigma0inv_t,
+    windows,
+    raster,
+    dbe,
+    tbe,
+    raster_kw,
+    weights_threshold_low=0.0,
+    weights_threshold_high=np.inf,
+    progress_bar=False,
+):
+    """Compute per-time-bin weighting for each nonrigid window"""
+    # determine window-weighted raster "heat" in each nonrigid window
+    # as a function of time
+    assert windows.shape[1] == dbe.size - 1
+    weights = []
+    p_inds = []
+    for b in range((len(Ds))):
+        ilow, ihigh = np.flatnonzero(windows[b])[[0, -1]]
+        ihigh += 1
+        window_sliced = windows[b, ilow:ihigh]
+        weights.append(window_sliced @ raster[ilow:ihigh])
+    weights_orig = np.array(weights)
+
+    scale_fn = raster_kw["post_transform"] or raster_kw["amp_scale_fn"]
+    if isinstance(weights_threshold_low, tuple):
+        nspikes_threshold_low, amp_threshold_low = weights_threshold_low
+        unif = np.full_like(windows[0], 1 / len(windows[0]))
+        weights_threshold_low = (
+            scale_fn(amp_threshold_low)
+            * windows
+            @ (nspikes_threshold_low * unif)
+        )
+        weights_threshold_low = weights_threshold_low[:, None]
+    if isinstance(weights_threshold_high, tuple):
+        nspikes_threshold_high, amp_threshold_high = weights_threshold_high
+        unif = np.full_like(windows[0], 1 / len(windows[0]))
+        weights_threshold_high = (
+            scale_fn(amp_threshold_high)
+            * windows
+            @ (nspikes_threshold_high * unif)
+        )
+        weights_threshold_high = weights_threshold_high[:, None]
+    weights_thresh = weights_orig.copy()
+    weights_thresh[weights_orig < weights_threshold_low] = 0
+    weights_thresh[weights_orig > weights_threshold_high] = np.inf
+
+    return weights, weights_thresh, p_inds
+
+def weight_correlation_matrix(
+    Ds,
+    Cs,
+    windows,
+    raster,
+    depth_bin_edges,
+    time_bin_edges,
+    raster_kw,
+    mincorr=0.0,
+    mincorr_percentile=None,
+    mincorr_percentile_nneighbs=20,
+    max_dt_s=None,
+    lambda_t=DEFAULT_LAMBDA_T,
+    eps=DEFAULT_EPS,
+    do_window_weights=True,
+    weights_threshold_low=0.0,
+    weights_threshold_high=np.inf,
+    progress_bar=True,
+    in_place=False,
+):
+    """Transform the correlation matrix into the weights used in optimization."""
+    extra = {}
+
+    Ds = np.asarray(Ds)
+    Cs = np.asarray(Cs)
+    if Ds.ndim == 2:
+        Ds = Ds[None]
+        Cs = Cs[None]
+    B, T, T_ = Ds.shape
+    assert T == T_
+    assert Ds.shape == Cs.shape
+    extra = {}
+
+    Ss, mincorr = threshold_correlation_matrix(
+        Cs,
+        mincorr=mincorr,
+        mincorr_percentile=mincorr_percentile,
+        mincorr_percentile_nneighbs=mincorr_percentile_nneighbs,
+        max_dt_s=max_dt_s,
+        bin_s=time_bin_edges[1] - time_bin_edges[0],
+        T=T,
+        in_place=in_place,
+    )
+    extra["S"] = Ss
+    extra["mincorr"] = mincorr
+
+    if not do_window_weights:
+        return Ss, extra
+
+    # get weights
+    L_t = lambda_t * laplacian(T, eps=max(1e-5, eps))
+    weights_orig, weights_thresh, Pind = get_weights(
+        Ds,
+        Ss,
+        L_t,
+        windows,
+        raster,
+        depth_bin_edges,
+        time_bin_edges,
+        raster_kw,
+        weights_threshold_low=weights_threshold_low,
+        weights_threshold_high=weights_threshold_high,
+        progress_bar=progress_bar,
+    )
+    extra["weights_orig"] = weights_orig
+    extra["weights_thresh"] = weights_thresh
+    extra["Pind"] = Pind
+
+    # update noise model. we deliberately divide by zero and inf here.
+    Us = Ss if in_place else np.zeros_like(Ss)
+    with np.errstate(divide="ignore"):
+        # low mem impl of U = abs(1/(1/weights_thresh+1/weights_thresh'+1/S))
+        np.reciprocal(Ss, out=Us)
+        invW = 1.0 / weights_thresh
+        Us += invW[:, :, None]
+        Us += invW[:, None, :]
+        np.reciprocal(Us, out=Us)
+        # handles possible -0s that cause issues elsewhere
+        np.abs(Us, out=Us)
+        # more readable equivalent:
+        # for b in range(B):
+        #     invWbtt = invW[b, :, None] + invW[b, None, :]
+        #     Us[b] = np.abs(1.0 / (invWbtt + 1.0 / Ss[b]))
+    extra["U"] = Us
+
+    return Us, extra
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
index 7804238024..b6fa344def 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
@@ -11,7 +11,7 @@
 from .motion_utils import Motion, get_windows, get_spatial_bin_edges
 from .decentralized import DecentralizedRegistration
 from .iterative_template import IterativeTemplateRegistration
-from .dredge import DredgeLfpRegistration
+from .dredge import DredgeLfpRegistration, DredgeApRegistration
 
 
 def estimate_motion(
@@ -162,7 +162,7 @@ def estimate_motion(
         return motion
 
 
-_methods_list = [DecentralizedRegistration, IterativeTemplateRegistration, DredgeLfpRegistration]
+_methods_list = [DecentralizedRegistration, IterativeTemplateRegistration, DredgeLfpRegistration, DredgeApRegistration]
 estimate_motion_methods = {m.name: m for m in _methods_list}
 method_doc = make_multi_method_doc(_methods_list)
 estimate_motion.__doc__ = estimate_motion.__doc__.format(method_doc=method_doc)
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index d9c0bedb24..44bf3eb3ad 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -376,6 +376,8 @@ def make_2d_motion_histogram(
     bin_um=2.0,
     hist_margin_um=50,
     spatial_bin_edges=None,
+    depth_smooth_um=None,
+    time_smooth_s=None,
 ):
     """
     Generate 2d motion histogram in depth and time.
@@ -401,6 +403,12 @@ def make_2d_motion_histogram(
         Ignored if spatial_bin_edges is given.
     spatial_bin_edges : np.array, default: None
         The pre-computed spatial bin edges
+    depth_smooth_um: None or float
+        Optional gaussian smoother on histogram on depth axis.
+        This is given as the sigma of the gaussian in micrometers.
+    time_smooth_s: None or float
+        Optional gaussian smoother on histogram on time axis.
+        This is given as the sigma of the gaussian in seconds.
 
     Returns
     -------
@@ -435,6 +443,14 @@ def make_2d_motion_histogram(
         bin_counts[bin_counts == 0] = 1
         motion_histogram = motion_histogram / bin_counts
 
+    from scipy.ndimage import gaussian_filter1d
+
+    if depth_smooth_um is not None:
+        motion_histogram = gaussian_filter1d(motion_histogram, depth_smooth_um / bin_um, axis=1, mode="constant")
+
+    if time_smooth_s is not None:
+        motion_histogram = gaussian_filter1d(motion_histogram, time_smooth_s / bin_duration_s, axis=0, mode="constant")
+
     return motion_histogram, temporal_bin_edges, spatial_bin_edges
 
 

From c2f5289efecbdc2128b6c48feaefac028bdff8fd Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 26 Jun 2024 23:03:33 +0200
Subject: [PATCH 10/31] important comments

---
 src/spikeinterface/sortingcomponents/motion/dredge.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 60d93f355c..817f34f88f 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -245,6 +245,8 @@ def dredge_ap(
         raster, spatial_bin_edges_um, time_bin_edges_s, counts = raster_res
     else:
         raster, spatial_bin_edges_um, time_bin_edges_s = raster_res
+    
+    # TODO Sam I did not yet change parameters here with the get_windows API
     windows, window_centers = get_windows(
         # pseudo geom to fool spikeinterface
         np.c_[np.zeros_like(spatial_bin_edges_um), spatial_bin_edges_um],

From cab6646e7edacf091ec1396744a1e122ae8499cf Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Thu, 27 Jun 2024 12:18:31 +0200
Subject: [PATCH 11/31] wip dredge_ap

---
 .../sortingcomponents/motion/decentralized.py |   4 +-
 .../sortingcomponents/motion/dredge.py        | 139 ++++++++++++------
 .../sortingcomponents/motion/motion_utils.py  |  14 +-
 3 files changed, 102 insertions(+), 55 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/decentralized.py b/src/spikeinterface/sortingcomponents/motion/decentralized.py
index 9a76b94d20..baf0fae1f2 100644
--- a/src/spikeinterface/sortingcomponents/motion/decentralized.py
+++ b/src/spikeinterface/sortingcomponents/motion/decentralized.py
@@ -145,7 +145,7 @@ def run(
             conv_engine = "torch" if HAVE_TORCH else "numpy"
 
         dim = ["x", "y", "z"].index(direction)
-        contact_pos = recording.get_channel_locations()[:, dim]
+        contact_depth = recording.get_channel_locations()[:, dim]
 
         # spatial histogram bins
         spatial_bin_edges = get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um)
@@ -153,7 +153,7 @@ def run(
 
         # get spatial windows
         non_rigid_windows, non_rigid_window_centers = get_windows(
-            rigid, contact_pos, spatial_bin_centers, win_margin_um, win_step_um, win_scale_um, win_shape
+            rigid, contact_depth, spatial_bin_centers, win_margin_um, win_step_um, win_scale_um, win_shape
         )
 
         # make 2D histogram raster
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 817f34f88f..779b236d77 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -28,7 +28,7 @@
 
 import gc
 
-from .motion_utils import Motion, get_windows, get_window_domains, scipy_conv1d
+from .motion_utils import Motion, get_windows, get_window_domains, scipy_conv1d, make_2d_motion_histogram
 
 
 # to discuss
@@ -70,16 +70,12 @@ def run(
         extra,
         **method_kwargs,
     ):
-        dim = ["x", "y", "z"].index(direction)
-        peak_amplitudes = peaks["amplitude"]
-        peak_depths = peak_locations[direction]
-        peak_times = recording.sample_index_to_time(peaks["sample_index"])
 
 
         outs = dredge_ap(
-            peak_amplitudes,
-            peak_depths,
-            peak_times,
+            recording,
+            peaks,
+            peak_locations,
             direction=direction,
             rigid=rigid,
             win_shape=win_shape,
@@ -100,9 +96,9 @@ def run(
 
 # @TODO : Charlie I started very small refactoring, I let you continue
 def dredge_ap(
-    amps,
-    depths_um,
-    times_s,
+    recording,
+    peaks,
+    peak_locations,
     direction="y",
     rigid=False,
     # nonrigid window construction arguments
@@ -113,7 +109,7 @@ def dredge_ap(
     bin_um=1.0,
     bin_s=1.0,
     max_disp_um=None,
-    time_horizon_s=1000,
+    time_horizon_s=1000.,
     mincorr=0.1,
     # weights arguments
     do_window_weights=True,
@@ -149,6 +145,8 @@ def dredge_ap(
 
     Arguments
     ---------
+    recording : Recording
+        The recording
     amps : np.array of shape (n_spikes,)
     depths: np.array of shape (n_spikes,)
     times : np.array of shape (n_spikes,)
@@ -207,10 +205,22 @@ def dredge_ap(
         windows if one wants to visualize them. Set `extra_outputs` to also save displacement
         and correlation matrices.
     """
+
+    dim = ["x", "y", "z"].index(direction)
+    # @charlie: I removed amps/depths_um/times_s from the signature
+    # preaks and peak_locations are more SI compatible
+    # the way to get then
+    amps = peak_amplitudes = peaks["amplitude"]
+    depths_um = peak_depths = peak_locations[direction]
+    times_s = peak_times = recording.sample_index_to_time(peaks["sample_index"])
+
+
+
     thomas_kw = thomas_kw if thomas_kw is not None else {}
     xcorr_kw = xcorr_kw if xcorr_kw is not None else {}
     if time_horizon_s:
         xcorr_kw["max_dt_bins"] = np.ceil(time_horizon_s / bin_s)
+    
     raster_kw = dict(
         amp_scale_fn=amp_scale_fn,
         post_transform=post_transform,
@@ -234,33 +244,70 @@ def dredge_ap(
     # this will store return values other than the MotionEstimate
     extra = {}
 
-    # TODO charlie switch this to make_2d_motion_histogram after having putting more option
-    raster_res = spike_raster(
-        amps,
-        depths_um,
-        times_s,
-        **raster_kw,
+
+
+    # TODO charlie I switch this to make_2d_motion_histogram
+    # but we need to add all options from the original spike_raster()
+
+    # raster_res = spike_raster(
+    #     amps,
+    #     depths_um,
+    #     times_s,
+    #     **raster_kw,
+    # )
+    # if count_masked_correlation:
+    #     raster, spatial_bin_edges_um, time_bin_edges_s, counts = raster_res
+    # else:
+    #     raster, spatial_bin_edges_um, time_bin_edges_s = raster_res
+    
+    motion_histogram, time_bin_edges_s, spatial_bin_edges_um = make_2d_motion_histogram(
+        recording,
+        peaks,
+        peak_locations,
+        weight_with_amplitude=False,
+        direction="y",
+        bin_duration_s=1.0,
+        bin_um=2.0,
+        hist_margin_um=50,
+        spatial_bin_edges=None,
+        depth_smooth_um=None,
+        time_smooth_s=None,
     )
-    if count_masked_correlation:
-        raster, spatial_bin_edges_um, time_bin_edges_s, counts = raster_res
-    else:
-        raster, spatial_bin_edges_um, time_bin_edges_s = raster_res
+    raster = motion_histogram.T
+
+
+    # TODO @charlie check that we are doing the same thing
+    # windows, window_centers = get_windows(
+    #     np.c_[np.zeros_like(spatial_bin_edges_um), spatial_bin_edges_um],
+    #     win_step_um,
+    #     win_scale_um,
+    #     spatial_bin_edges=spatial_bin_edges_um,
+    #     margin_um=-win_scale_um / 2 if win_margin_um is None else win_margin_um,
+    #     win_shape=win_shape,
+    #     zero_threshold=1e-5,
+    #     rigid=rigid,
+    # )
+
+    dim = ["x", "y", "z"].index(direction)
+    contact_depth = recording.get_channel_locations()[:, dim]
+    spatial_bin_centers = 0.5 * (spatial_bin_edges_um[1:] + spatial_bin_edges_um[:-1])
     
-    # TODO Sam I did not yet change parameters here with the get_windows API
     windows, window_centers = get_windows(
-        # pseudo geom to fool spikeinterface
-        np.c_[np.zeros_like(spatial_bin_edges_um), spatial_bin_edges_um],
+        rigid,
+        contact_depth,
+        spatial_bin_centers,
+        win_margin_um,
         win_step_um,
         win_scale_um,
-        spatial_bin_edges=spatial_bin_edges_um,
-        margin_um=-win_scale_um / 2 if win_margin_um is None else win_margin_um,
-        win_shape=win_shape,
+        win_shape,
         zero_threshold=1e-5,
-        rigid=rigid,
     )
-    if extra_outputs and count_masked_correlation:
-        extra["counts"] = counts
 
+    # TODO charlie : put back the count
+    # if extra_outputs and count_masked_correlation:
+    #     extra["counts"] = counts
+
+    
     # cross-correlate to get D and C
     if precomputed_D_C_maxdisp is None:
         Ds, Cs, max_disp_um = xcorr_windows(
@@ -273,7 +320,8 @@ def dredge_ap(
             max_disp_um=max_disp_um,
             progress_bar=progress_bar,
             device=device,
-            masks=(counts > 0) if count_masked_correlation else None,
+            # TODO charlie : put back the count for the mask
+            # masks=(counts > 0) if count_masked_correlation else None,
             **xcorr_kw,
         )
     else:
@@ -319,9 +367,7 @@ def dredge_ap(
         extra["max_disp_um"] = max_disp_um
 
     time_bin_centers = 0.5 * (time_bin_edges_s[1:] + time_bin_edges_s[:-1])
-    spatial_bin_centers_um = 0.5 * (spatial_bin_edges_um[1:] + spatial_bin_edges_um[:-1])
-    
-    motion = Motion([displacement], [time_bin_centers], spatial_bin_centers_um, direction=direction)
+    motion = Motion([displacement.T], [time_bin_centers], window_centers, direction=direction)
 
     if extra_outputs:
         return motion, extra
@@ -464,7 +510,7 @@ def dredge_online_lfp(
     """
     dim = ["x", "y", "z"].index(direction)
     # contact pos is the only on the direction
-    contact_pos = lfp_recording.get_channel_locations()[:, dim]
+    contact_depth = lfp_recording.get_channel_locations()[:, dim]
 
 
     fs = lfp_recording.get_sampling_frequency()
@@ -477,7 +523,7 @@ def dredge_online_lfp(
     thomas_kw = thomas_kw if thomas_kw is not None else {}
     full_xcorr_kw = dict(
         rigid=rigid,
-        bin_um=np.median(np.diff(contact_pos)),
+        bin_um=np.median(np.diff(contact_depth)),
         max_disp_um=max_disp_um,
         progress_bar=False,
         device=device,
@@ -494,22 +540,22 @@ def dredge_online_lfp(
 
     
     # here we check that contact positons are unique on the direction
-    if contact_pos.size != np.unique(contact_pos).size:
+    if contact_depth.size != np.unique(contact_depth).size:
         raise ValueError(
             f"estimate motion with 'dredge_lfp' need channel_positions to be unique in the direction='{direction}'"
         )
-    if np.any(np.diff(contact_pos) < 0):
+    if np.any(np.diff(contact_depth) < 0):
         raise ValueError(
             f"estimate motion with 'dredge_lfp' need channel_positions to be ordered direction='{direction}'"
             "please use spikeinterface.preprocessing.depth_order(recording)"
         )
 
     # Important detail : in LFP bin center are contact position in the direction
-    spatial_bin_centers = contact_pos
+    spatial_bin_centers = contact_depth
 
     windows, window_centers = get_windows(
         rigid=rigid, 
-        contact_pos=contact_pos,
+        contact_depth=contact_depth,
         spatial_bin_centers=spatial_bin_centers,
         win_margin_um=win_margin_um,
         win_step_um=win_step_um,
@@ -529,7 +575,7 @@ def dredge_online_lfp(
     t0, t1 = 0, T_chunk
     traces0 = lfp_recording.get_traces(start_frame=t0, end_frame=t1)
     Ds0, Cs0, max_disp_um = xcorr_windows(
-        traces0.T, windows, contact_pos, win_scale_um, **full_xcorr_kw
+        traces0.T, windows, contact_depth, win_scale_um, **full_xcorr_kw
     )
     full_xcorr_kw["max_disp_um"] = max_disp_um
     Ss0, mincorr0 = threshold_correlation_matrix(
@@ -568,7 +614,7 @@ def dredge_online_lfp(
         Ds10, Cs10, _ = xcorr_windows(
             traces1.T,
             windows,
-            contact_pos,
+            contact_depth,
             win_scale_um,
             raster_b=traces0.T,
             **full_xcorr_kw,
@@ -576,7 +622,7 @@ def dredge_online_lfp(
 
         # cross-correlation in current chunk
         Ds1, Cs1, _ = xcorr_windows(
-            traces1.T, windows, contact_pos, win_scale_um, **full_xcorr_kw
+            traces1.T, windows, contact_depth, win_scale_um, **full_xcorr_kw
         )
         Ss1, mincorr1 = threshold_correlation_matrix(
             Cs1,
@@ -954,6 +1000,7 @@ def xcorr_windows(
     slices = get_window_domains(windows)
     B, D = windows.shape
     D_, T0 = raster_a.shape
+
     assert D == D_
 
     # torch versions on device
@@ -1310,7 +1357,7 @@ def weight_correlation_matrix(
     mincorr=0.0,
     mincorr_percentile=None,
     mincorr_percentile_nneighbs=20,
-    max_dt_s=None,
+    time_horizon_s=None,
     lambda_t=DEFAULT_LAMBDA_T,
     eps=DEFAULT_EPS,
     do_window_weights=True,
@@ -1337,7 +1384,7 @@ def weight_correlation_matrix(
         mincorr=mincorr,
         mincorr_percentile=mincorr_percentile,
         mincorr_percentile_nneighbs=mincorr_percentile_nneighbs,
-        max_dt_s=max_dt_s,
+        time_horizon_s=time_horizon_s,
         bin_s=time_bin_edges[1] - time_bin_edges[0],
         T=T,
         in_place=in_place,
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index 44bf3eb3ad..3fb0f8505a 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -232,7 +232,7 @@ def copy(self):
 
 
 
-def get_windows(rigid, contact_pos, spatial_bin_centers, win_margin_um, win_step_um, win_scale_um, win_shape,
+def get_windows(rigid, contact_depth, spatial_bin_centers, win_margin_um, win_step_um, win_scale_um, win_shape,
                 zero_threshold=None):
     """
     Generate spatial windows (taper) for non-rigid motion.
@@ -243,7 +243,7 @@ def get_windows(rigid, contact_pos, spatial_bin_centers, win_margin_um, win_step
     ----------
     rigid : bool
         If True, returns a single rectangular window
-    contact_pos : np.ndarray
+    contact_depth : np.ndarray
         Position of electrodes of the corection direction shape=(num_channels, )
     spatial_bin_centers : np.array
         The pre-computed spatial bin centers
@@ -283,8 +283,8 @@ def get_windows(rigid, contact_pos, spatial_bin_centers, win_margin_um, win_step
                 f"get_windows(): spatial windows are probably not overlaping because {win_scale_um=} and {win_step_um=}"
             )
 
-        min_ = np.min(contact_pos) - win_margin_um
-        max_ = np.max(contact_pos) + win_margin_um
+        min_ = np.min(contact_depth) - win_margin_um
+        max_ = np.max(contact_depth) + win_margin_um
         num_windows = int((max_ - min_) // win_step_um)
         border = ((max_ - min_) % win_step_um) / 2
         window_centers = np.arange(num_windows + 1) * win_step_um + min_ + border
@@ -356,10 +356,10 @@ def get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um):
     # contact along one axis
     probe = recording.get_probe()
     dim = ["x", "y", "z"].index(direction)
-    contact_pos = probe.contact_positions[:, dim]
+    contact_depth = probe.contact_positions[:, dim]
 
-    min_ = np.min(contact_pos) - hist_margin_um
-    max_ = np.max(contact_pos) + hist_margin_um
+    min_ = np.min(contact_depth) - hist_margin_um
+    max_ = np.max(contact_depth) + hist_margin_um
     spatial_bins = np.arange(min_, max_ + bin_um, bin_um)
 
     return spatial_bins

From 37014bbcb41344c1f7be1aeeb999a7ad75311e53 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Thu, 27 Jun 2024 14:15:48 +0200
Subject: [PATCH 12/31] more refactoring and parameters change

---
 .../benchmark/benchmark_motion_estimation.py  |  4 +-
 .../benchmark/benchmark_tools.py              |  2 +-
 .../sortingcomponents/motion/decentralized.py | 23 ++++++----
 .../sortingcomponents/motion/dredge.py        | 31 +++++++------
 .../motion/iterative_template.py              | 16 +++++--
 .../motion/motion_cleaner.py                  |  2 +-
 .../motion/motion_estimation.py               | 35 ++++-----------
 .../sortingcomponents/motion/motion_utils.py  | 43 ++++++++++++++-----
 8 files changed, 90 insertions(+), 66 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_estimation.py b/src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_estimation.py
index 55ef21de9d..ec7e1e24a8 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_estimation.py
@@ -9,13 +9,13 @@
 
 from spikeinterface.core import get_noise_levels
 from spikeinterface.sortingcomponents.benchmark.benchmark_tools import Benchmark, BenchmarkStudy, _simpleaxis
-from spikeinterface.sortingcomponents.motion_estimation import estimate_motion
+from spikeinterface.sortingcomponents.motion import estimate_motion
 from spikeinterface.sortingcomponents.peak_detection import detect_peaks
 from spikeinterface.sortingcomponents.peak_selection import select_peaks
 from spikeinterface.sortingcomponents.peak_localization import localize_peaks
 from spikeinterface.widgets import plot_probe_map
 
-from spikeinterface.sortingcomponents.motion_utils import Motion
+from spikeinterface.sortingcomponents.motion import Motion
 
 # import MEArec as mr
 
diff --git a/src/spikeinterface/sortingcomponents/benchmark/benchmark_tools.py b/src/spikeinterface/sortingcomponents/benchmark/benchmark_tools.py
index e9f128993d..7dc3fad280 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/benchmark_tools.py
+++ b/src/spikeinterface/sortingcomponents/benchmark/benchmark_tools.py
@@ -443,7 +443,7 @@ def load_folder(cls, folder):
 
                 result[k] = load_extractor(folder / k)
             elif format == "Motion":
-                from spikeinterface.sortingcomponents.motion_utils import Motion
+                from spikeinterface.sortingcomponents.motion import Motion
 
                 result[k] = Motion.load(folder / k)
             elif format == "zarr_templates":
diff --git a/src/spikeinterface/sortingcomponents/motion/decentralized.py b/src/spikeinterface/sortingcomponents/motion/decentralized.py
index baf0fae1f2..5815f77a48 100644
--- a/src/spikeinterface/sortingcomponents/motion/decentralized.py
+++ b/src/spikeinterface/sortingcomponents/motion/decentralized.py
@@ -10,7 +10,7 @@
 except ImportError:
     HAVE_TORCH = False
 
-from .motion_utils import Motion, get_windows, get_spatial_bin_edges, make_2d_motion_histogram, scipy_conv1d
+from .motion_utils import Motion, get_spatial_windows, get_spatial_bin_edges, make_2d_motion_histogram, scipy_conv1d
 
 
 class DecentralizedRegistration:
@@ -113,11 +113,11 @@ def run(
         verbose,
         progress_bar,
         extra,
-        bin_um=10.0,
-        hist_margin_um=0.0,
-        bin_duration_s=2.0,
-        histogram_depth_smooth_um=None,
-        histogram_time_smooth_s=None,
+        bin_um=1.0,
+        hist_margin_um=20.0,
+        bin_duration_s=1.0,
+        histogram_depth_smooth_um=1.,
+        histogram_time_smooth_s=1.,
         pairwise_displacement_method="conv",
         max_displacement_um=100.0,
         weight_scale="linear",
@@ -152,8 +152,15 @@ def run(
         spatial_bin_centers = 0.5 * (spatial_bin_edges[1:] + spatial_bin_edges[:-1])
 
         # get spatial windows
-        non_rigid_windows, non_rigid_window_centers = get_windows(
-            rigid, contact_depth, spatial_bin_centers, win_margin_um, win_step_um, win_scale_um, win_shape
+        non_rigid_windows, non_rigid_window_centers = get_spatial_windows(
+            contact_depth,
+            spatial_bin_centers,
+            rigid=rigid,
+            win_shape=win_shape,
+            win_step_um=win_step_um,
+            win_scale_um=win_scale_um,
+            win_margin_um=win_margin_um,
+            zero_threshold=None
         )
 
         # make 2D histogram raster
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 779b236d77..f2a46bdfcb 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -28,7 +28,7 @@
 
 import gc
 
-from .motion_utils import Motion, get_windows, get_window_domains, scipy_conv1d, make_2d_motion_histogram
+from .motion_utils import Motion, get_spatial_windows, get_window_domains, scipy_conv1d, make_2d_motion_histogram
 
 
 # to discuss
@@ -42,6 +42,8 @@
 # put smotthing inside the histogram function
 # put the log for weight inhitstogram
 
+# TODO maybe change everywhere bin_duration_s to bin_s
+
 
 # simple class wrapper to be compliant with estimate_motion
 class DredgeApRegistration:
@@ -221,6 +223,9 @@ def dredge_ap(
     if time_horizon_s:
         xcorr_kw["max_dt_bins"] = np.ceil(time_horizon_s / bin_s)
     
+    #TODO @charlie I think this is a bad to have the dict which is transported to every function
+    # this should be used only in histogram function but not in weight_correlation_matrix()
+    # only important kwargs should be explicitly reported
     raster_kw = dict(
         amp_scale_fn=amp_scale_fn,
         post_transform=post_transform,
@@ -277,7 +282,7 @@ def dredge_ap(
 
 
     # TODO @charlie check that we are doing the same thing
-    # windows, window_centers = get_windows(
+    # windows, window_centers = get_spatial_windows(
     #     np.c_[np.zeros_like(spatial_bin_edges_um), spatial_bin_edges_um],
     #     win_step_um,
     #     win_scale_um,
@@ -292,16 +297,18 @@ def dredge_ap(
     contact_depth = recording.get_channel_locations()[:, dim]
     spatial_bin_centers = 0.5 * (spatial_bin_edges_um[1:] + spatial_bin_edges_um[:-1])
     
-    windows, window_centers = get_windows(
-        rigid,
+    windows, window_centers = get_spatial_windows(
         contact_depth,
         spatial_bin_centers,
-        win_margin_um,
-        win_step_um,
-        win_scale_um,
-        win_shape,
-        zero_threshold=1e-5,
-    )
+        rigid=rigid,
+        win_shape=win_shape,
+        win_step_um=win_step_um,
+        win_scale_um=win_scale_um,
+        win_margin_um=win_margin_um,
+        zero_threshold=1e-5
+        )
+
+
 
     # TODO charlie : put back the count
     # if extra_outputs and count_masked_correlation:
@@ -553,10 +560,10 @@ def dredge_online_lfp(
     # Important detail : in LFP bin center are contact position in the direction
     spatial_bin_centers = contact_depth
 
-    windows, window_centers = get_windows(
-        rigid=rigid, 
+    windows, window_centers = get_spatial_windows(
         contact_depth=contact_depth,
         spatial_bin_centers=spatial_bin_centers,
+        rigid=rigid,
         win_margin_um=win_margin_um,
         win_step_um=win_step_um,
         win_scale_um=win_scale_um,
diff --git a/src/spikeinterface/sortingcomponents/motion/iterative_template.py b/src/spikeinterface/sortingcomponents/motion/iterative_template.py
index ab6877adc3..e7c978e865 100644
--- a/src/spikeinterface/sortingcomponents/motion/iterative_template.py
+++ b/src/spikeinterface/sortingcomponents/motion/iterative_template.py
@@ -1,6 +1,6 @@
 import numpy as np
 
-from .motion_utils import Motion, get_windows, get_spatial_bin_edges, make_3d_motion_histograms
+from .motion_utils import Motion, get_spatial_windows, get_spatial_bin_edges, make_3d_motion_histograms
 
 
 class IterativeTemplateRegistration:
@@ -78,18 +78,26 @@ def run(
     ):
 
         dim = ["x", "y", "z"].index(direction)
-        contact_pos = recording.get_channel_locations()[:, dim]
+        contact_depth = recording.get_channel_locations()[:, dim]
 
         # spatial histogram bins
         spatial_bin_edges = get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um)
         spatial_bin_centers = 0.5 * (spatial_bin_edges[1:] + spatial_bin_edges[:-1])
 
         # get spatial windows
-        non_rigid_windows, non_rigid_window_centers = get_windows(
-            rigid, contact_pos, spatial_bin_centers, win_margin_um, win_step_um, win_scale_um, win_shape
+        non_rigid_windows, non_rigid_window_centers = get_spatial_windows(
+            contact_depth=contact_depth,
+            spatial_bin_centers=spatial_bin_centers,
+            rigid=rigid,
+            win_margin_um=win_margin_um,
+            win_step_um=win_step_um,
+            win_scale_um=win_scale_um,
+            win_shape=win_shape,
+            zero_threshold=None,
         )
 
 
+
         # make a 3D histogram
         motion_histograms, temporal_hist_bin_edges, spatial_hist_bin_edges = make_3d_motion_histograms(
             recording,
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py b/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py
index 401210e079..de2c7df4cc 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py
@@ -1,6 +1,6 @@
 import numpy as np
 
-
+# TODO this need a full rewrite with motion object
 
 def clean_motion_vector(motion, temporal_bins, bin_duration_s, speed_threshold=30, sigma_smooth_s=None):
     """
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
index b6fa344def..aab3a1b491 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
@@ -8,7 +8,7 @@
 from spikeinterface.sortingcomponents.tools import make_multi_method_doc
 
 
-from .motion_utils import Motion, get_windows, get_spatial_bin_edges
+from .motion_utils import Motion, get_spatial_windows, get_spatial_bin_edges
 from .decentralized import DecentralizedRegistration
 from .iterative_template import IterativeTemplateRegistration
 from .dredge import DredgeLfpRegistration, DredgeApRegistration
@@ -19,13 +19,11 @@ def estimate_motion(
     peaks=None,
     peak_locations=None,
     direction="y",
-    # bin_um=10.0,
-    # hist_margin_um=0.0,
     rigid=False,
     win_shape="gaussian",
     win_step_um=50.0,
     win_scale_um=150.0,
-    win_margin_um=0.,
+    win_margin_um=None,
     method="decentralized",
     extra_outputs=False,
     progress_bar=False,
@@ -36,7 +34,8 @@ def estimate_motion(
     """
     Estimate motion for given peaks and after their localization.
 
-    Note that the way you detect peak locations (center of mass/monopolar triangulation) have an impact on the result.
+    Note that the way you detect peak locations (center of mass/monopolar triangulation)
+    have an impact on the result.
 
     Parameters
     ----------
@@ -70,14 +69,14 @@ def estimate_motion(
         The depth domain will be broken up into windows with shape controlled by win_shape,
         spaced by win_step_um at a margin of win_margin_um from the boundary, and with
         width controlled by win_scale_um.
+        When win_margin_um is None the margin is automatically set to -win_scale_um/2.
+        See get_spatial_windows.
     win_step_um : float, default: 50
         See win_shape
     win_scale_um : float, default: 150
         See win_shape
-    win_margin_um : float, default: 0.
-    See win_shape
-        
-        
+    win_margin_um : None | float, default: None
+        See win_shape
     extra_outputs: bool, default: False
         If True then return an extra dict that contains variables
         to check intermediate steps (motion_histogram, non_rigid_windows, pairwise_displacement)
@@ -114,25 +113,7 @@ def estimate_motion(
     else:
         extra = None
 
-    # contact positions
-    # probe = recording.get_probe()
-    # dim = ["x", "y", "z"].index(direction)
-    # contact_pos = probe.contact_positions[:, dim]
-
-    # # spatial histogram bins
-    # spatial_bin_edges = get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um)
-    # spatial_bin_centers = 0.5 * (spatial_bin_edges[1:] + spatial_bin_edges[:-1])
-
-    # # get spatial windows
-    # non_rigid_windows, non_rigid_window_centers = get_windows(
-    #     rigid, contact_pos, spatial_bin_centers, win_margin_um, win_step_um, win_scale_um, win_shape
-    # )
-
-    # if extra_outputs:
-    #     extra["non_rigid_windows"] = non_rigid_windows
-
     # run method
-    
     motion = method_class.run(
         recording,
         peaks,
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index 3fb0f8505a..f0442996a6 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -232,29 +232,45 @@ def copy(self):
 
 
 
-def get_windows(rigid, contact_depth, spatial_bin_centers, win_margin_um, win_step_um, win_scale_um, win_shape,
-                zero_threshold=None):
+def get_spatial_windows(
+        contact_depth,
+        spatial_bin_centers,
+        rigid=False,
+        win_shape="gaussian",
+        win_step_um=50.0,
+        win_scale_um=150.0,
+        win_margin_um=None,
+        zero_threshold=None
+    ):
     """
     Generate spatial windows (taper) for non-rigid motion.
     For rigid motion, this is equivalent to have one unique rectangular window that covers the entire probe.
     The windowing can be gaussian or rectangular.
+    Windows are centered between the min/max of contact_depth.
+    We can ensure window to not be to close from border with win_margin_um.
+
 
     Parameters
     ----------
-    rigid : bool
-        If True, returns a single rectangular window
     contact_depth : np.ndarray
         Position of electrodes of the corection direction shape=(num_channels, )
     spatial_bin_centers : np.array
         The pre-computed spatial bin centers
-    win_margin_um : float
-        The margin to extend (if positive) or shrink (if negative) the probe dimension to compute windows.=
+    rigid : bool, default False
+        If True, returns a single rectangular window
+    win_shape : str, default "gaussian"
+        Shape of the window
+        "gaussian" | "rect" | "triangle"
     win_step_um : float
         The steps at which windows are defined
-    win_scale_um : float
-        Sigma of gaussian window (if win_shape is gaussian)
-    win_shape : float
-        "gaussian" | "rect"
+    win_scale_um : float, default 150.
+        Sigma of gaussian window if win_shape is gaussian
+        Width of the rectangle if win_shape is rect
+    win_margin_um : None | float, default None
+        The margin to extend (if positive) or shrink (if negative) the probe dimension to compute windows.
+        When None, then the margin is set to -win_scale_um./2
+    zero_threshold: None | float
+        Lower value for thresholding to set zeros.
 
     Returns
     -------
@@ -280,9 +296,14 @@ def get_windows(rigid, contact_depth, spatial_bin_centers, win_margin_um, win_st
     else:
         if win_scale_um <= win_step_um/5.:
             warnings.warn(
-                f"get_windows(): spatial windows are probably not overlaping because {win_scale_um=} and {win_step_um=}"
+                f"get_spatial_windows(): spatial windows are probably not overlaping because {win_scale_um=} and {win_step_um=}"
             )
 
+        # @charlie: I am pretty sure this is the best option
+        if win_margin_um is None:
+            # this ensure that first/last windows do not overflow outside the probe
+            win_margin_um = -win_scale_um / 2.
+
         min_ = np.min(contact_depth) - win_margin_um
         max_ = np.max(contact_depth) + win_margin_um
         num_windows = int((max_ - min_) // win_step_um)

From e2e9bff651e6c319e88086f92aabc6fe09c8b470 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Thu, 27 Jun 2024 17:05:17 +0200
Subject: [PATCH 13/31] import fix

---
 .../benchmark/benchmark_motion_interpolation.py            | 2 +-
 src/spikeinterface/sortingcomponents/motion/dredge.py      | 7 -------
 .../motion/tests/test_motion_interpolation.py              | 4 ++--
 3 files changed, 3 insertions(+), 10 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_interpolation.py b/src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_interpolation.py
index a6ff05fc55..38365adfd1 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_interpolation.py
@@ -6,7 +6,7 @@
 from spikeinterface.sorters import run_sorter
 
 from spikeinterface.comparison import GroundTruthComparison
-from spikeinterface.sortingcomponents.motion_interpolation import InterpolateMotionRecording
+from spikeinterface.sortingcomponents.motion.motion_interpolation import InterpolateMotionRecording
 from spikeinterface.curation import MergeUnitsSorting
 
 
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index f2a46bdfcb..6fa2242d8c 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -31,13 +31,6 @@
 from .motion_utils import Motion, get_spatial_windows, get_window_domains, scipy_conv1d, make_2d_motion_histogram
 
 
-# to discuss
-# margin
-# xcorr new function
-# which dataset band usefull for ?
-# dredge_ap
-# use patient 2
-
 # todo use gaussian_filter1d in historgam 2d
 # put smotthing inside the histogram function
 # put the log for weight inhitstogram
diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
index cb26560272..e022f0cc6c 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
@@ -4,13 +4,13 @@
 import pytest
 import spikeinterface.core as sc
 from spikeinterface import download_dataset
-from spikeinterface.sortingcomponents.motion_interpolation import (
+from spikeinterface.sortingcomponents.motion.motion_interpolation import (
     InterpolateMotionRecording,
     correct_motion_on_peaks,
     interpolate_motion,
     interpolate_motion_on_traces,
 )
-from spikeinterface.sortingcomponents.motion_utils import Motion
+from spikeinterface.sortingcomponents.motion import Motion
 from spikeinterface.sortingcomponents.tests.common import make_dataset
 
 

From ea017292bcc2bcdfcc4a3e7031cf6b2759ea356b Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 28 Jun 2024 18:45:04 +0200
Subject: [PATCH 14/31] fixing dredge_ap details

---
 .../sortingcomponents/motion/dredge.py        | 73 +++++++++++--------
 .../motion/motion_estimation.py               |  4 +-
 .../sortingcomponents/motion/motion_utils.py  |  9 ++-
 src/spikeinterface/widgets/motion.py          |  2 +-
 4 files changed, 51 insertions(+), 37 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 6fa2242d8c..eb10ebe40b 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -113,10 +113,10 @@ def dredge_ap(
     mincorr_percentile=None,
     mincorr_percentile_nneighbs=None,
     # raster arguments
-    amp_scale_fn=None,
-    post_transform=np.log1p,
-    gaussian_smoothing_sigma_um=1,
-    gaussian_smoothing_sigma_s=1,
+    amp_scale_fn=None,  ## @Charlie this one is not used anymore
+    post_transform=np.log1p,  ###@this one is directly transimited to weight_correlation_matrix() and so get_wieiith()
+    histogram_depth_smooth_um=1,
+    histogram_time_smooth_s=1,
     avg_in_bin=False,
     count_masked_correlation=False,
     count_bins=401,
@@ -219,18 +219,19 @@ def dredge_ap(
     #TODO @charlie I think this is a bad to have the dict which is transported to every function
     # this should be used only in histogram function but not in weight_correlation_matrix()
     # only important kwargs should be explicitly reported
-    raster_kw = dict(
-        amp_scale_fn=amp_scale_fn,
-        post_transform=post_transform,
-        gaussian_smoothing_sigma_um=gaussian_smoothing_sigma_um,
-        gaussian_smoothing_sigma_s=gaussian_smoothing_sigma_s,
-        bin_s=bin_s,
-        bin_um=bin_um,
-        avg_in_bin=avg_in_bin,
-        return_counts=count_masked_correlation,
-        count_bins=count_bins,
-        count_bin_min=count_bin_min,
-    )
+    # raster_kw = dict(
+    #     amp_scale_fn=amp_scale_fn,
+    #     post_transform=post_transform,
+    #     histogram_depth_smooth_um=histogram_depth_smooth_um,
+    #     histogram_time_smooth_s=histogram_time_smooth_s,
+    #     bin_s=bin_s,
+    #     bin_um=bin_um,
+    #     avg_in_bin=avg_in_bin,
+    #     return_counts=count_masked_correlation,
+    #     count_bins=count_bins,
+    #     count_bin_min=count_bin_min,
+    # )
+
     weights_kw = dict(
         mincorr=mincorr,
         time_horizon_s=time_horizon_s,
@@ -246,7 +247,7 @@ def dredge_ap(
 
     # TODO charlie I switch this to make_2d_motion_histogram
     # but we need to add all options from the original spike_raster()
-
+    # but I think this is OK
     # raster_res = spike_raster(
     #     amps,
     #     depths_um,
@@ -258,23 +259,26 @@ def dredge_ap(
     # else:
     #     raster, spatial_bin_edges_um, time_bin_edges_s = raster_res
     
+
+
     motion_histogram, time_bin_edges_s, spatial_bin_edges_um = make_2d_motion_histogram(
         recording,
         peaks,
         peak_locations,
         weight_with_amplitude=False,
-        direction="y",
-        bin_duration_s=1.0,
-        bin_um=2.0,
-        hist_margin_um=50,
+        avg_in_bin=avg_in_bin,
+        direction=direction,
+        bin_duration_s=bin_s,
+        bin_um=bin_um,
+        hist_margin_um=0.,  # @charlie maybe we should expose this and set +20. for instance
         spatial_bin_edges=None,
-        depth_smooth_um=None,
-        time_smooth_s=None,
+        depth_smooth_um=histogram_depth_smooth_um,
+        time_smooth_s=histogram_time_smooth_s,
     )
     raster = motion_histogram.T
 
 
-    # TODO @charlie check that we are doing the same thing
+    # TODO @charlie you should check that we are doing the same thing
     # windows, window_centers = get_spatial_windows(
     #     np.c_[np.zeros_like(spatial_bin_edges_um), spatial_bin_edges_um],
     #     win_step_um,
@@ -303,7 +307,7 @@ def dredge_ap(
 
 
 
-    # TODO charlie : put back the count
+    # TODO charlie : the count has disapeared
     # if extra_outputs and count_masked_correlation:
     #     extra["counts"] = counts
 
@@ -335,7 +339,8 @@ def dredge_ap(
         raster,
         spatial_bin_edges_um,
         time_bin_edges_s,
-        raster_kw,
+        # raster_kw, #@charlie this is removed
+        post_transform=post_transform, # @charlie this isnew
         lambda_t=thomas_kw.get("lambda_t", DEFAULT_LAMBDA_T),
         eps=thomas_kw.get("eps", DEFAULT_EPS),
         progress_bar=progress_bar,
@@ -668,7 +673,7 @@ def dredge_online_lfp(
         return motion
 
 
-
+# -- zone forbiden for sam
 # -- functions from dredgelib
 
 DEFAULT_LAMBDA_T = 1.0
@@ -1303,7 +1308,9 @@ def get_weights(
     raster,
     dbe,
     tbe,
-    raster_kw,
+    # @charlie raster_kw is removed in favor of post_transform only is this OK ???
+    # raster_kw,
+    post_transform=np.log1p,
     weights_threshold_low=0.0,
     weights_threshold_high=np.inf,
     progress_bar=False,
@@ -1321,7 +1328,8 @@ def get_weights(
         weights.append(window_sliced @ raster[ilow:ihigh])
     weights_orig = np.array(weights)
 
-    scale_fn = raster_kw["post_transform"] or raster_kw["amp_scale_fn"]
+    # scale_fn = raster_kw["post_transform"] or raster_kw["amp_scale_fn"]
+    scale_fn = post_transform
     if isinstance(weights_threshold_low, tuple):
         nspikes_threshold_low, amp_threshold_low = weights_threshold_low
         unif = np.full_like(windows[0], 1 / len(windows[0]))
@@ -1353,7 +1361,9 @@ def weight_correlation_matrix(
     raster,
     depth_bin_edges,
     time_bin_edges,
-    raster_kw,
+    # @charlie raster_kw is remove in favor of post_transform only
+    # raster_kw,
+    post_transform=np.log1p,
     mincorr=0.0,
     mincorr_percentile=None,
     mincorr_percentile_nneighbs=20,
@@ -1405,7 +1415,8 @@ def weight_correlation_matrix(
         raster,
         depth_bin_edges,
         time_bin_edges,
-        raster_kw,
+        #raster_kw,
+        post_transform=post_transform,
         weights_threshold_low=weights_threshold_low,
         weights_threshold_high=weights_threshold_high,
         progress_bar=progress_bar,
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
index aab3a1b491..bbf2cdfd69 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
@@ -21,8 +21,8 @@ def estimate_motion(
     direction="y",
     rigid=False,
     win_shape="gaussian",
-    win_step_um=50.0,
-    win_scale_um=150.0,
+    win_step_um=50.0, # 400
+    win_scale_um=150.0, # 400
     win_margin_um=None,
     method="decentralized",
     extra_outputs=False,
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index f0442996a6..f2d6e62f16 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -299,7 +299,6 @@ def get_spatial_windows(
                 f"get_spatial_windows(): spatial windows are probably not overlaping because {win_scale_um=} and {win_step_um=}"
             )
 
-        # @charlie: I am pretty sure this is the best option
         if win_margin_um is None:
             # this ensure that first/last windows do not overflow outside the probe
             win_margin_um = -win_scale_um / 2.
@@ -392,6 +391,7 @@ def make_2d_motion_histogram(
     peaks,
     peak_locations,
     weight_with_amplitude=False,
+    avg_in_bin=True,
     direction="y",
     bin_duration_s=1.0,
     bin_um=2.0,
@@ -413,6 +413,9 @@ def make_2d_motion_histogram(
         Array with peak locations
     weight_with_amplitude : bool, default: False
         If True, motion histogram is weighted by amplitudes
+    avg_in_bin : bool, default True
+        If true, average the amplitudes in each bin.
+        This is done only if weight_with_amplitude=True.
     direction : "x" | "y" | "z", default: "y"
         The depth direction
     bin_duration_s : float, default: 1.0
@@ -457,9 +460,9 @@ def make_2d_motion_histogram(
         weights = None
 
     motion_histogram, edges = np.histogramdd(arr, bins=(temporal_bin_edges, spatial_bin_edges), weights=weights)
-
+    
     # average amplitude in each bin
-    if weight_with_amplitude:
+    if weight_with_amplitude and avg_in_bin:
         bin_counts, _ = np.histogramdd(arr, bins=(temporal_bin_edges, spatial_bin_edges))
         bin_counts[bin_counts == 0] = 1
         motion_histogram = motion_histogram / bin_counts
diff --git a/src/spikeinterface/widgets/motion.py b/src/spikeinterface/widgets/motion.py
index 0b79350a62..6f8bdc7a6e 100644
--- a/src/spikeinterface/widgets/motion.py
+++ b/src/spikeinterface/widgets/motion.py
@@ -5,7 +5,7 @@
 from .base import BaseWidget, to_attr
 
 from spikeinterface.core import BaseRecording, SortingAnalyzer
-from spikeinterface.sortingcomponents.motion_utils import Motion
+from spikeinterface.sortingcomponents.motion import Motion
 
 
 class MotionWidget(BaseWidget):

From 75decf6ec7937ed91e9bb68e7c7911c986e66c3e Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 3 Jul 2024 14:00:54 +0200
Subject: [PATCH 15/31] still rafactor and fix estimate_motion() for dredge_ap

---
 doc/modules/sortingcomponents.rst             |  2 +-
 src/spikeinterface/preprocessing/motion.py    |  8 +++----
 .../tests/test_benchmark_motion_estimation.py |  2 +-
 .../test_benchmark_motion_interpolation.py    |  2 +-
 .../sortingcomponents/motion/decentralized.py | 12 +++++-----
 .../sortingcomponents/motion/dredge.py        | 10 +++------
 .../motion/iterative_template.py              |  8 +++----
 .../motion/motion_estimation.py               | 22 +++++++------------
 .../sortingcomponents/motion/motion_utils.py  | 16 ++++++++------
 .../motion/tests/test_motion_estimation.py    |  2 +-
 10 files changed, 38 insertions(+), 46 deletions(-)

diff --git a/doc/modules/sortingcomponents.rst b/doc/modules/sortingcomponents.rst
index f33a0b3cf2..e7e05312bc 100644
--- a/doc/modules/sortingcomponents.rst
+++ b/doc/modules/sortingcomponents.rst
@@ -193,7 +193,7 @@ Here is an example with non-rigid motion estimation:
     from spikeinterface.sortingcomponents.motion_estimation import estimate_motion
     motion, temporal_bins, spatial_bins,
                 extra_check = estimate_motion(recording=recording, peaks=peaks, peak_locations=peak_locations,
-                                              direction='y', bin_duration_s=10., bin_um=10., margin_um=0.,
+                                              direction='y', bin_s=10., bin_um=10., margin_um=0.,
                                               method='decentralized_registration',
                                               rigid=False, win_shape='gaussian', win_step_um=50., win_sigma_um=150.,
                                               progress_bar=True, verbose=True)
diff --git a/src/spikeinterface/preprocessing/motion.py b/src/spikeinterface/preprocessing/motion.py
index ed097d19fc..59945b0a06 100644
--- a/src/spikeinterface/preprocessing/motion.py
+++ b/src/spikeinterface/preprocessing/motion.py
@@ -34,7 +34,7 @@
         "estimate_motion_kwargs": dict(
             method="decentralized",
             direction="y",
-            bin_duration_s=2.0,
+            bin_s=2.0,
             rigid=False,
             bin_um=5.0,
             margin_um=0.0,
@@ -93,7 +93,7 @@
         "estimate_motion_kwargs": dict(
             method="decentralized",
             direction="y",
-            bin_duration_s=2.0,
+            bin_s=2.0,
             rigid=False,
             bin_um=5.0,
             margin_um=0.0,
@@ -148,7 +148,7 @@
         ),
         "estimate_motion_kwargs": dict(
             method="decentralized",
-            bin_duration_s=10.0,
+            bin_s=10.0,
             rigid=True,
         ),
         "interpolate_motion_kwargs": dict(
@@ -178,7 +178,7 @@
         ),
         "estimate_motion_kwargs": dict(
             method="iterative_template",
-            bin_duration_s=2.0,
+            bin_s=2.0,
             rigid=False,
             win_step_um=50.0,
             win_scale_um=150.0,
diff --git a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_estimation.py b/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_estimation.py
index 56e1c18d62..78a9eb7dbc 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_estimation.py
@@ -41,7 +41,7 @@ def test_benchmark_motion_estimaton(create_cache_folder):
                 localize_kwargs=dict(method=loc_method),
                 estimate_motion_kwargs=dict(
                     method=est_method,
-                    bin_duration_s=1.0,
+                    bin_s=1.0,
                     bin_um=5.0,
                     rigid=False,
                     win_step_um=50.0,
diff --git a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_interpolation.py b/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_interpolation.py
index 6d80d027f2..18def37d54 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_interpolation.py
@@ -56,7 +56,7 @@ def test_benchmark_motion_interpolation(create_cache_folder):
     # plt.show()
 
     cases = {}
-    bin_duration_s = 1.0
+    bin_s = 1.0
 
     cases["static_SC2"] = dict(
         label="No drift - no correction - SC2",
diff --git a/src/spikeinterface/sortingcomponents/motion/decentralized.py b/src/spikeinterface/sortingcomponents/motion/decentralized.py
index 5815f77a48..53bc29d4b1 100644
--- a/src/spikeinterface/sortingcomponents/motion/decentralized.py
+++ b/src/spikeinterface/sortingcomponents/motion/decentralized.py
@@ -45,7 +45,7 @@ class DecentralizedRegistration:
         Margin in um from histogram estimation.
         Positive margin extrapolate out of the probe the motion.
         Negative margin crop the motion on the border
-    bin_duration_s: float, default: 2.0
+    bin_s: float, default: 2.0
         Bin duration in second
     histogram_depth_smooth_um: None or float
         Optional gaussian smoother on histogram on depth axis.
@@ -115,7 +115,7 @@ def run(
         extra,
         bin_um=1.0,
         hist_margin_um=20.0,
-        bin_duration_s=1.0,
+        bin_s=1.0,
         histogram_depth_smooth_um=1.,
         histogram_time_smooth_s=1.,
         pairwise_displacement_method="conv",
@@ -172,7 +172,7 @@ def run(
             peaks,
             peak_locations,
             direction=direction,
-            bin_duration_s=bin_duration_s,
+            bin_s=bin_s,
             spatial_bin_edges=spatial_bin_edges,
             weight_with_amplitude=weight_with_amplitude,
             depth_smooth_um=histogram_depth_smooth_um,
@@ -220,7 +220,7 @@ def run(
                 centered_xcorr=centered_xcorr,
                 corr_threshold=corr_threshold,
                 time_horizon_s=time_horizon_s,
-                bin_duration_s=bin_duration_s,
+                bin_s=bin_s,
                 progress_bar=False,
             )
 
@@ -315,7 +315,7 @@ def compute_pairwise_displacement(
     time_horizon_s=None,
     normalized_xcorr=True,
     centered_xcorr=True,
-    bin_duration_s=None,
+    bin_s=None,
     progress_bar=False,
     window=None,
 ):
@@ -329,7 +329,7 @@ def compute_pairwise_displacement(
     pairwise_displacement = np.zeros((size, size), dtype="float32")
 
     if time_horizon_s is not None:
-        band_width = int(np.ceil(time_horizon_s / bin_duration_s))
+        band_width = int(np.ceil(time_horizon_s / bin_s))
         if band_width >= size:
             time_horizon_s = None
 
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index eb10ebe40b..007dc3dd0a 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -28,15 +28,13 @@
 
 import gc
 
-from .motion_utils import Motion, get_spatial_windows, get_window_domains, scipy_conv1d, make_2d_motion_histogram
+from .motion_utils import Motion, get_spatial_windows, get_window_domains, scipy_conv1d, make_2d_motion_histogram, get_spatial_bin_edges
 
 
 # todo use gaussian_filter1d in historgam 2d
 # put smotthing inside the histogram function
 # put the log for weight inhitstogram
 
-# TODO maybe change everywhere bin_duration_s to bin_s
-
 
 # simple class wrapper to be compliant with estimate_motion
 class DredgeApRegistration:
@@ -259,16 +257,14 @@ def dredge_ap(
     # else:
     #     raster, spatial_bin_edges_um, time_bin_edges_s = raster_res
     
-
-
     motion_histogram, time_bin_edges_s, spatial_bin_edges_um = make_2d_motion_histogram(
         recording,
         peaks,
         peak_locations,
-        weight_with_amplitude=False,
+        weight_with_amplitude=True,
         avg_in_bin=avg_in_bin,
         direction=direction,
-        bin_duration_s=bin_s,
+        bin_s=bin_s,
         bin_um=bin_um,
         hist_margin_um=0.,  # @charlie maybe we should expose this and set +20. for instance
         spatial_bin_edges=None,
diff --git a/src/spikeinterface/sortingcomponents/motion/iterative_template.py b/src/spikeinterface/sortingcomponents/motion/iterative_template.py
index e7c978e865..a49d5bd639 100644
--- a/src/spikeinterface/sortingcomponents/motion/iterative_template.py
+++ b/src/spikeinterface/sortingcomponents/motion/iterative_template.py
@@ -29,7 +29,7 @@ class IterativeTemplateRegistration:
         Margin in um from histogram estimation.
         Positive margin extrapolate out of the probe the motion.
         Negative margin crop the motion on the border
-    bin_duration_s: float, default: 2.0
+    bin_s: float, default: 2.0
         Bin duration in second
     num_amp_bins: int, default: 20
         number ob bins in the histogram on the log amplitues dimension
@@ -66,7 +66,7 @@ def run(
         extra,
         bin_um=10.0,
         hist_margin_um=0.0,
-        bin_duration_s=2.0,
+        bin_s=2.0,
         num_amp_bins=20,
         num_shifts_global=15,
         num_iterations=10,
@@ -105,11 +105,11 @@ def run(
             peak_locations,
             direction=direction,
             num_amp_bins=num_amp_bins,
-            bin_duration_s=bin_duration_s,
+            bin_s=bin_s,
             spatial_bin_edges=spatial_bin_edges,
         )
         # temporal bins are bin center
-        temporal_bins = temporal_hist_bin_edges[:-1] + bin_duration_s // 2.0
+        temporal_bins = temporal_hist_bin_edges[:-1] + bin_s // 2.0
 
         # do alignment
         shift_indices, target_histogram, shift_covs_block = iterative_template_registration(
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
index bbf2cdfd69..6cd935e582 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
@@ -21,8 +21,8 @@ def estimate_motion(
     direction="y",
     rigid=False,
     win_shape="gaussian",
-    win_step_um=50.0, # 400
-    win_scale_um=150.0, # 400
+    win_step_um=50.0, # @alessio charlie is proposing here instead 400
+    win_scale_um=150.0, # @alessio charlie is proposing here instead 400
     win_margin_um=None,
     method="decentralized",
     extra_outputs=False,
@@ -32,9 +32,13 @@ def estimate_motion(
     **method_kwargs,
 ):
     """
-    Estimate motion for given peaks and after their localization.
+    
+    
+    Estimate motion with several possible methods.
 
-    Note that the way you detect peak locations (center of mass/monopolar triangulation)
+    Most of methods except dredge_lfp needs peaks and after their localization.
+
+    Note that the way you detect peak locations (center of mass/monopolar_triangulation/grid_convolution)
     have an impact on the result.
 
     Parameters
@@ -50,13 +54,8 @@ def estimate_motion(
     direction: "x" | "y" | "z", default: "y"
         Dimension on which the motion is estimated. "y" is depth along the probe.
 
-        
-        
     {method_doc}
 
-    **histogram section**
-
-
     **non-rigid section**
 
     rigid : bool, default: False
@@ -120,9 +119,6 @@ def estimate_motion(
         peak_locations,
         direction,
 
-        # bin_um,
-        # spatial_bin_edges,
-        # non_rigid_windows,
         rigid,
         win_shape,
         win_step_um,
@@ -135,8 +131,6 @@ def estimate_motion(
         **method_kwargs,
     )
 
-    # motion = Motion([motion_array], [temporal_bins], non_rigid_window_centers, direction=direction)
-
     if extra_outputs:
         return motion, extra
     else:
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index f2d6e62f16..de94b7a899 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -393,7 +393,7 @@ def make_2d_motion_histogram(
     weight_with_amplitude=False,
     avg_in_bin=True,
     direction="y",
-    bin_duration_s=1.0,
+    bin_s=1.0,
     bin_um=2.0,
     hist_margin_um=50,
     spatial_bin_edges=None,
@@ -418,7 +418,7 @@ def make_2d_motion_histogram(
         This is done only if weight_with_amplitude=True.
     direction : "x" | "y" | "z", default: "y"
         The depth direction
-    bin_duration_s : float, default: 1.0
+    bin_s : float, default: 1.0
         The temporal bin duration in s
     bin_um : float, default: 2.0
         The spatial bin size in um. Ignored if spatial_bin_edges is given.
@@ -446,9 +446,11 @@ def make_2d_motion_histogram(
     n_samples = recording.get_num_samples()
     mint_s = recording.sample_index_to_time(0)
     maxt_s = recording.sample_index_to_time(n_samples)
-    temporal_bin_edges = np.arange(mint_s, maxt_s + bin_duration_s, bin_duration_s)
+    temporal_bin_edges = np.arange(mint_s, maxt_s + bin_s, bin_s)
     if spatial_bin_edges is None:
         spatial_bin_edges = get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um)
+    else:
+        bin_um = spatial_bin_edges[1] - spatial_bin_edges[0]
 
     arr = np.zeros((peaks.size, 2), dtype="float64")
     arr[:, 0] = recording.sample_index_to_time(peaks["sample_index"])
@@ -473,7 +475,7 @@ def make_2d_motion_histogram(
         motion_histogram = gaussian_filter1d(motion_histogram, depth_smooth_um / bin_um, axis=1, mode="constant")
 
     if time_smooth_s is not None:
-        motion_histogram = gaussian_filter1d(motion_histogram, time_smooth_s / bin_duration_s, axis=0, mode="constant")
+        motion_histogram = gaussian_filter1d(motion_histogram, time_smooth_s / bin_s, axis=0, mode="constant")
 
     return motion_histogram, temporal_bin_edges, spatial_bin_edges
 
@@ -483,7 +485,7 @@ def make_3d_motion_histograms(
     peaks,
     peak_locations,
     direction="y",
-    bin_duration_s=1.0,
+    bin_s=1.0,
     bin_um=2.0,
     hist_margin_um=50,
     num_amp_bins=20,
@@ -505,7 +507,7 @@ def make_3d_motion_histograms(
         Array with peak locations
     direction : "x" | "y" | "z", default: "y"
         The depth direction
-    bin_duration_s : float, default: 1.0
+    bin_s : float, default: 1.0
         The temporal bin duration in s.
     bin_um : float, default: 2.0
         The spatial bin size in um. Ignored if spatial_bin_edges is given.
@@ -529,7 +531,7 @@ def make_3d_motion_histograms(
     n_samples = recording.get_num_samples()
     mint_s = recording.sample_index_to_time(0)
     maxt_s = recording.sample_index_to_time(n_samples)
-    temporal_bin_edges = np.arange(mint_s, maxt_s + bin_duration_s, bin_duration_s)
+    temporal_bin_edges = np.arange(mint_s, maxt_s + bin_s, bin_s)
     if spatial_bin_edges is None:
         spatial_bin_edges = get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um)
 
diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
index c626de527f..ac1d5aace7 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
@@ -150,7 +150,7 @@ def test_estimate_motion(setup_module):
 
         kwargs = dict(
             direction="y",
-            bin_duration_s=1.0,
+            bin_s=1.0,
             bin_um=10.0,
             margin_um=5,
             extra_outputs=True,

From ae18211e536541a4dd0ab15c67116836a04607ca Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 3 Jul 2024 16:19:33 +0200
Subject: [PATCH 16/31] move doc for dredge classes

---
 src/spikeinterface/preprocessing/motion.py    |   2 +-
 .../sortingcomponents/motion/decentralized.py |   2 +-
 .../sortingcomponents/motion/dredge.py        | 190 ++++++++++--------
 .../motion/tests/test_motion_estimation.py    |  18 +-
 4 files changed, 121 insertions(+), 91 deletions(-)

diff --git a/src/spikeinterface/preprocessing/motion.py b/src/spikeinterface/preprocessing/motion.py
index 59945b0a06..c77745a4ff 100644
--- a/src/spikeinterface/preprocessing/motion.py
+++ b/src/spikeinterface/preprocessing/motion.py
@@ -409,7 +409,7 @@ def correct_motion(
 
 
 def load_motion_info(folder):
-    from spikeinterface.sortingcomponents.motion_utils import Motion
+    from spikeinterface.sortingcomponents.motion import Motion
 
     folder = Path(folder)
 
diff --git a/src/spikeinterface/sortingcomponents/motion/decentralized.py b/src/spikeinterface/sortingcomponents/motion/decentralized.py
index 53bc29d4b1..a01fb2ffb3 100644
--- a/src/spikeinterface/sortingcomponents/motion/decentralized.py
+++ b/src/spikeinterface/sortingcomponents/motion/decentralized.py
@@ -45,7 +45,7 @@ class DecentralizedRegistration:
         Margin in um from histogram estimation.
         Positive margin extrapolate out of the probe the motion.
         Negative margin crop the motion on the border
-    bin_s: float, default: 2.0
+    bin_s: float, default 1.0
         Bin duration in second
     histogram_depth_smooth_um: None or float
         Optional gaussian smoother on histogram on depth axis.
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 007dc3dd0a..71d7b0ea8d 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -39,12 +39,52 @@
 # simple class wrapper to be compliant with estimate_motion
 class DredgeApRegistration:
     """
+    Estimate motion from spikes times and depth.
 
+    This the certified and official version of the dredge implementation.
+
+    Method developed by the Paninski's group from Columbia university:
+    Charlie Windolf, Julien Boussard, Erdem Varol
+
+    This method is quite similar to "decentralized" which was the previous implementation in spikeinterface.
+
+    The reference is here https://www.biorxiv.org/content/10.1101/2023.10.24.563768v1
+
+    The original code were here : https://github.com/evarol/DREDge
+    But this code which use the same internal function is in line with the Motion object of spikeinterface contrary to the dredge repo.
+
+    This code has been ported in spikeinterface (with simple copy/paste) by Samuel but main author is truely Charlie Windolf.
     """
+
     name = "dredge_ap"
     need_peak_location = True
     params_doc = """
-
+    bin_um: float
+        Bin duration in second
+    bin_s : float
+        The size of the bins along depth in microns and along time in seconds.
+        The returned object's .displacement array will respect these bins.
+        Increasing these can lead to more stable estimates and faster runtimes
+        at the cost of spatial and/or temporal resolution.
+    max_disp_um : float
+        Maximum possible displacement in microns. If you can guess a number which is larger
+        than the largest displacement possible in your recording across a span of `time_horizon_s`
+        seconds, setting this value to that number can stabilize the result and speed up
+        the algorithm (since it can do less cross-correlating).
+        By default, this is set to win-scale_um / 4, or 112.5 microns. Which can be a bit
+        large!
+    time_horizon_s : float
+        "Time horizon" parameter, in seconds. Time bins separated by more seconds than this
+        will not be cross-correlated. So, if your data has nonstationarities or changes which
+        could lead to bad cross-correlations at some timescale, it can help to input that
+        value here. If this is too small, it can make the motion estimation unstable.
+    mincorr : float, between 0 and 1
+        Correlation threshold. Pairs of frames whose maximal cross correlation value is smaller
+        than this threshold will be ignored when solving for the global displacement estimate.
+    thomas_kw, xcorr_kw, raster_kw, weights_kw
+        These dictionaries allow setting parameters for fine control over the registration
+    device : str or torch.device
+        What torch device to run on? E.g., "cpu" or "cuda" or "cuda:1".
     """
     @classmethod
     def run(
@@ -87,6 +127,7 @@ def run(
             motion = outs
         return motion
 
+
 # @TODO : Charlie I started very small refactoring, I let you continue
 def dredge_ap(
     recording,
@@ -138,13 +179,14 @@ def dredge_ap(
 
     Arguments
     ---------
-    recording : Recording
-        The recording
-    amps : np.array of shape (n_spikes,)
-    depths: np.array of shape (n_spikes,)
-    times : np.array of shape (n_spikes,)
-        The amplitudes, depths (microns) and times (seconds) of input
-        spike events.
+    recording: BaseRecording
+        The recording extractor
+    peaks: numpy array
+        Peak vector (complex dtype).
+        Needed for decentralized and iterative_template methods.
+    peak_locations: numpy array
+        Complex dtype with "x", "y", "z" fields
+        Needed for decentralized and iterative_template methods.
     direction : "x" | "y", default "y"
         Dimension on which the motion is estimated. "y" is depth along the probe.
     rigid : bool, default=False
@@ -160,39 +202,12 @@ def dredge_ap(
     win_margin_um : float
         Distance of nonrigid windows centers from the probe boundary (-1000 means there will
         be no window center within 1000um of the edge of the probe)
-    bin_um: float
-    bin_s : float
-        The size of the bins along depth in microns and along time in seconds.
-        The returned object's .displacement array will respect these bins.
-        Increasing these can lead to more stable estimates and faster runtimes
-        at the cost of spatial and/or temporal resolution.
-    max_disp_um : float
-        Maximum possible displacement in microns. If you can guess a number which is larger
-        than the largest displacement possible in your recording across a span of `time_horizon_s`
-        seconds, setting this value to that number can stabilize the result and speed up
-        the algorithm (since it can do less cross-correlating).
-        By default, this is set to win-scale_um / 4, or 112.5 microns. Which can be a bit
-        large!
-    time_horizon_s : float
-        "Time horizon" parameter, in seconds. Time bins separated by more seconds than this
-        will not be cross-correlated. So, if your data has nonstationarities or changes which
-        could lead to bad cross-correlations at some timescale, it can help to input that
-        value here. If this is too small, it can make the motion estimation unstable.
-    mincorr : float, between 0 and 1
-        Correlation threshold. Pairs of frames whose maximal cross correlation value is smaller
-        than this threshold will be ignored when solving for the global displacement estimate.
-    thomas_kw, xcorr_kw, raster_kw, weights_kw
-        These dictionaries allow setting parameters for fine control over the registration
-    device : str or torch.device
-        What torch device to run on? E.g., "cpu" or "cuda" or "cuda:1".
+    {}
 
     Returns
     -------
-    motion_est : a motion_util.MotionEstimate object
-        This has a .displacement attribute which is the displacement estimate in a
-        (num_nonrigid_blocks, num_time_bins) array. It also has properties describing
-        the time and spatial bins, and methods for getting the displacement at a particular
-        time and depth. See the documentation of these classes in motion_util.py.
+    motion : Motion
+        The motion object
     extra : dict
         This has extra info about what happened during registration, including the nonrigid
         windows if one wants to visualize them. Set `extra_outputs` to also save displacement
@@ -376,15 +391,64 @@ def dredge_ap(
         return motion
 
 
+dredge_ap.__doc__ = dredge_ap.__doc__.format(DredgeApRegistration.params_doc)
+
+
 # simple class wrapper to be compliant with estimate_motion
 class DredgeLfpRegistration:
     """
+    Estimate motion from LFP recording.
 
+    This the certified and official version of the dredge implementation.
+
+    Method developed by the Paninski's group from Columbia university:
+    Charlie Windolf, Julien Boussard, Erdem Varol
+
+    The reference is here https://www.biorxiv.org/content/10.1101/2023.10.24.563768v1
     """
     name = "dredge_lfp"
     need_peak_location = False
     params_doc = """
-
+    lfp_recording : spikeinterface BaseRecording object
+        Preprocessed LFP recording. The temporal resolution of this recording will
+        be the target resolution of the registration, so definitely use SpikeInterface
+        to resample your recording to, say, 250Hz (or a value you like) rather than
+        estimating motion at the original frequency (which may be high).
+    direction : "x" | "y", default "y"
+        Dimension on which the motion is estimated. "y" is depth along the probe.
+    rigid : boolean, optional
+        If True, window-related arguments are ignored and we do rigid registration
+    win_shape, win_step_um, win_scale_um, win_margin_um : float
+        Nonrigid window-related arguments
+        The depth domain will be broken up into windows with shape controlled by win_shape,
+        spaced by win_step_um at a margin of win_margin_um from the boundary, and with
+        width controlled by win_scale_um.
+    chunk_len_s : float
+        Length of chunks (in seconds) that the recording is broken into for online
+        registration. The computational speed of the method is a function of the
+        number of samples this corresponds to, and things can get slow if it is
+        set high enough that the number of samples per chunk is bigger than ~10,000.
+        But, it can't be set too low or the algorithm doesn't have enough data
+        to work with. The default is set assuming sampling rate of 250Hz, leading
+        to 2500 samples per chunk.
+    time_horizon_s : float
+        Time-bins farther apart than this value in seconds will not be cross-correlated.
+        Set this to at least `chunk_len_s`.
+    max_disp_um : number, optional
+        This is the ceiling on the possible displacement estimates. It should be
+        set to a number which is larger than the allowed displacement in a single
+        chunk. Setting it as small as possible (while following that rule) can speed
+        things up and improve the result by making it impossible to estimate motion
+        which is too big.
+    mincorr : float in [0,1]
+        Minimum correlation between pairs of frames such that they will be included
+        in the optimization of the displacement estimates.
+    mincorr_percentile, mincorr_percentile_nneighbs
+        If mincorr_percentile is set to a number in [0, 100], then mincorr will be replaced
+        by this percentile of the correlations of neighbors within mincorr_percentile_nneighbs
+        time bins of each other.
+    device : string or torch.device
+        Controls torch device
     """
     @classmethod
     def run(
@@ -429,6 +493,8 @@ def run(
 
 
 
+
+
 def dredge_online_lfp(
     lfp_recording,
     direction='y',
@@ -461,46 +527,7 @@ def dredge_online_lfp(
 
     Arguments
     ---------
-    lfp_recording : spikeinterface BaseRecording object
-        Preprocessed LFP recording. The temporal resolution of this recording will
-        be the target resolution of the registration, so definitely use SpikeInterface
-        to resample your recording to, say, 250Hz (or a value you like) rather than
-        estimating motion at the original frequency (which may be high).
-    direction : "x" | "y", default "y"
-        Dimension on which the motion is estimated. "y" is depth along the probe.
-    rigid : boolean, optional
-        If True, window-related arguments are ignored and we do rigid registration
-    win_shape, win_step_um, win_scale_um, win_margin_um : float
-        Nonrigid window-related arguments
-        The depth domain will be broken up into windows with shape controlled by win_shape,
-        spaced by win_step_um at a margin of win_margin_um from the boundary, and with
-        width controlled by win_scale_um.
-    chunk_len_s : float
-        Length of chunks (in seconds) that the recording is broken into for online
-        registration. The computational speed of the method is a function of the
-        number of samples this corresponds to, and things can get slow if it is
-        set high enough that the number of samples per chunk is bigger than ~10,000.
-        But, it can't be set too low or the algorithm doesn't have enough data
-        to work with. The default is set assuming sampling rate of 250Hz, leading
-        to 2500 samples per chunk.
-    time_horizon_s : float
-        Time-bins farther apart than this value in seconds will not be cross-correlated.
-        Set this to at least `chunk_len_s`.
-    max_disp_um : number, optional
-        This is the ceiling on the possible displacement estimates. It should be
-        set to a number which is larger than the allowed displacement in a single
-        chunk. Setting it as small as possible (while following that rule) can speed
-        things up and improve the result by making it impossible to estimate motion
-        which is too big.
-    mincorr : float in [0,1]
-        Minimum correlation between pairs of frames such that they will be included
-        in the optimization of the displacement estimates.
-    mincorr_percentile, mincorr_percentile_nneighbs
-        If mincorr_percentile is set to a number in [0, 100], then mincorr will be replaced
-        by this percentile of the correlations of neighbors within mincorr_percentile_nneighbs
-        time bins of each other.
-    device : string or torch.device
-        Controls torch device
+    {}
 
     Returns
     -------
@@ -668,9 +695,10 @@ def dredge_online_lfp(
     else:
         return motion
 
+dredge_online_lfp.__doc__  = dredge_online_lfp.__doc__.format(DredgeLfpRegistration.params_doc)
+
 
-# -- zone forbiden for sam
-# -- functions from dredgelib
+# -- functions from dredgelib (zone forbiden for sam)
 
 DEFAULT_LAMBDA_T = 1.0
 DEFAULT_EPS = 1e-3
diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
index ac1d5aace7..1168b65c79 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
@@ -18,7 +18,8 @@
     plt.show()
 
 
-def setup_module(cache_folder):
+def setup_dataset_and_peaks(cache_folder):
+    print(cache_folder, type(cache_folder))
     cache_folder.mkdir(parents=True, exist_ok=True)
 
     recording, sorting = make_dataset()
@@ -47,15 +48,16 @@ def setup_module(cache_folder):
     return recording, sorting, cache_folder
 
 
-@pytest.fixture(scope="module", name="setup_module")
-def setup_module_fixture(tmp_path_factory):
-    cache_folder = tmp_path_factory.mktemp("cache_folder")
-    return setup_module(cache_folder)
+@pytest.fixture(scope="module", name="dataset")
+def dataset_fixture(create_cache_folder):
+    cache_folder = create_cache_folder / "motion_estimation"
+    return setup_dataset_and_peaks(cache_folder)
 
 
-def test_estimate_motion(setup_module):
+def test_estimate_motion(dataset):
     # recording, sorting = make_dataset()
-    recording, sorting, cache_folder = setup_module
+    recording, sorting, cache_folder = dataset
+    
     peaks = np.load(cache_folder / "dataset_peaks.npy")
     peak_locations = np.load(cache_folder / "dataset_peak_locations.npy")
 
@@ -222,5 +224,5 @@ def test_estimate_motion(setup_module):
     import tempfile
     with tempfile.TemporaryDirectory() as tmpdirname:
         cache_folder = Path(tmpdirname)
-    args = setup_module(cache_folder)
+    args = setup_dataset_and_peaks(cache_folder)
     test_estimate_motion(args)

From 64f317722885f8997ef591052239478c33bbbdcd Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 5 Jul 2024 10:36:06 +0200
Subject: [PATCH 17/31] wip

---
 src/spikeinterface/generation/hybrid_tools.py |  2 +-
 src/spikeinterface/preprocessing/motion.py    | 30 ++++++++-----------
 .../motion/motion_interpolation.py            |  3 ++
 src/spikeinterface/widgets/motion.py          | 12 ++++----
 4 files changed, 22 insertions(+), 25 deletions(-)

diff --git a/src/spikeinterface/generation/hybrid_tools.py b/src/spikeinterface/generation/hybrid_tools.py
index a57e090f5f..8f2ef0ec21 100644
--- a/src/spikeinterface/generation/hybrid_tools.py
+++ b/src/spikeinterface/generation/hybrid_tools.py
@@ -15,7 +15,7 @@
 )
 from spikeinterface.core.template_tools import get_template_extremum_channel
 
-from spikeinterface.sortingcomponents.motion_utils import Motion
+from spikeinterface.sortingcomponents.motion import Motion
 
 from spikeinterface.generation.drift_tools import (
     InjectDriftingTemplatesRecording,
diff --git a/src/spikeinterface/preprocessing/motion.py b/src/spikeinterface/preprocessing/motion.py
index cb3fde20a7..82a89220bd 100644
--- a/src/spikeinterface/preprocessing/motion.py
+++ b/src/spikeinterface/preprocessing/motion.py
@@ -19,8 +19,8 @@
             method="locally_exclusive",
             peak_sign="neg",
             detect_threshold=8.0,
-            exclude_sweep_ms=0.1,
-            radius_um=50,
+            exclude_sweep_ms=0.8,
+            radius_um=80.,
         ),
         "select_kwargs": dict(),
         "localize_peaks_kwargs": dict(
@@ -35,16 +35,13 @@
         "estimate_motion_kwargs": dict(
             method="decentralized",
             direction="y",
-            bin_s=2.0,
+            bin_s=1.0,
             rigid=False,
             bin_um=5.0,
-            margin_um=0.0,
-            # win_shape="gaussian",
-            # win_step_um=50.0,
-            # win_scale_um=150.0,
+            hist_margin_um=20.0,
             win_shape="gaussian",
-            win_step_um=100.0,
-            win_scale_um=200.0,
+            win_step_um=200.0,
+            win_scale_um=300.0,
             histogram_depth_smooth_um=5.0,
             histogram_time_smooth_s=None,
             pairwise_displacement_method="conv",
@@ -78,13 +75,14 @@
             method="locally_exclusive",
             peak_sign="neg",
             detect_threshold=8.0,
-            exclude_sweep_ms=0.5,
-            radius_um=50,
+            exclude_sweep_ms=0.8,
+            radius_um=80.,
         ),
         "select_kwargs": dict(),
         "localize_peaks_kwargs": dict(
             method="grid_convolution",
-            radius_um=40.0,
+            # radius_um=40.0,
+            radius_um=80.0,
             upsampling_um=5.0,
             sigma_ms=0.25,
             margin_um=30.0,
@@ -97,10 +95,7 @@
             bin_s=2.0,
             rigid=False,
             bin_um=5.0,
-            margin_um=0.0,
-            # win_shape="gaussian",
-            # win_step_um=50.0,
-            # win_scale_um=150.0,
+            hist_margin_um=0.0,
             win_shape="gaussian",
             win_step_um=100.0,
             win_scale_um=200.0,
@@ -183,7 +178,7 @@
             rigid=False,
             win_step_um=50.0,
             win_scale_um=150.0,
-            margin_um=0,
+            hist_margin_um=0,
             win_shape="rect",
         ),
         "interpolate_motion_kwargs": dict(
@@ -201,6 +196,7 @@
 }
 
 
+
 def correct_motion(
     recording,
     preset="nonrigid_accurate",
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index 32bb7634e9..11ce11e1aa 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -27,6 +27,9 @@ def correct_motion_on_peaks(peaks, peak_locations, motion, recording):
     corrected_peak_locations: np.array
         Motion-corrected peak locations
     """
+    if recording is None:
+        raise ValueError("correct_motion_on_peaks need recording to be not None")
+
     corrected_peak_locations = peak_locations.copy()
 
     for segment_index in range(motion.num_segments):
diff --git a/src/spikeinterface/widgets/motion.py b/src/spikeinterface/widgets/motion.py
index 6f8bdc7a6e..81cda212b2 100644
--- a/src/spikeinterface/widgets/motion.py
+++ b/src/spikeinterface/widgets/motion.py
@@ -230,7 +230,7 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
         from matplotlib.colors import Normalize
         from .utils_matplotlib import make_mpl_figure
 
-        from spikeinterface.sortingcomponents.motion_interpolation import correct_motion_on_peaks
+        from spikeinterface.sortingcomponents.motion import correct_motion_on_peaks
 
         dp = to_attr(data_plot)
 
@@ -291,12 +291,10 @@ class MotionInfoWidget(BaseWidget):
     ----------
     motion_info : dict
         The motion info returned by correct_motion() or loaded back with load_motion_info().
+    recording : RecordingExtractor
+        The recording extractor object
     segment_index : int, default: None
         The segment index to display.
-    recording : RecordingExtractor, default: None
-        The recording extractor object (only used to get "real" times).
-    segment_index : int, default: 0
-        The segment index to display.
     sampling_frequency : float, default: None
         The sampling frequency (needed if recording is None).
     depth_lim : tuple or None, default: None
@@ -320,8 +318,8 @@ class MotionInfoWidget(BaseWidget):
     def __init__(
         self,
         motion_info: dict,
+        recording: BaseRecording,
         segment_index: int | None = None,
-        recording: BaseRecording | None = None,
         depth_lim: tuple[float, float] | None = None,
         motion_lim: tuple[float, float] | None = None,
         color_amplitude: bool = False,
@@ -366,7 +364,7 @@ def __init__(
     def plot_matplotlib(self, data_plot, **backend_kwargs):
         from .utils_matplotlib import make_mpl_figure
 
-        from spikeinterface.sortingcomponents.motion_interpolation import correct_motion_on_peaks
+        from spikeinterface.sortingcomponents.motion import correct_motion_on_peaks
 
         dp = to_attr(data_plot)
 

From 41e6eda8e68d8da51f63ec026a00236c62fcb821 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 8 Jul 2024 10:54:03 +0200
Subject: [PATCH 18/31] dredge_lfp doc

---
 doc/how_to/drift_with_lfp.rst                 | 189 +++++++++++++
 .../drift_with_lfp_12_1.png                   | Bin 0 -> 48141 bytes
 .../drift_with_lfp_8_1.png                    | Bin 0 -> 195184 bytes
 examples/how_to/drift_with_lfp.py             | 113 ++++++++
 .../sortingcomponents/motion/decentralized.py | 265 +++++++++---------
 .../sortingcomponents/motion/dredge.py        |  15 +-
 .../motion/motion_estimation.py               |   1 +
 7 files changed, 444 insertions(+), 139 deletions(-)
 create mode 100644 doc/how_to/drift_with_lfp.rst
 create mode 100644 doc/how_to/drift_with_lfp_files/drift_with_lfp_12_1.png
 create mode 100644 doc/how_to/drift_with_lfp_files/drift_with_lfp_8_1.png
 create mode 100644 examples/how_to/drift_with_lfp.py

diff --git a/doc/how_to/drift_with_lfp.rst b/doc/how_to/drift_with_lfp.rst
new file mode 100644
index 0000000000..e8d48301a0
--- /dev/null
+++ b/doc/how_to/drift_with_lfp.rst
@@ -0,0 +1,189 @@
+Estimate drift using the LFP traces
+===================================
+
+Charlie Windolf and colleagues have developed a method to estimate the
+motion using the LFP signal : **dredge**.
+
+You can see more detail in this preprint `DREDge: robust motion
+correction for high-density extracellular recordings across
+species <https://www.biorxiv.org/content/10.1101/2023.10.24.563768v1>`__
+
+This method is particularly adapated for the open dataset recorded at
+Massachusetts General Hospital by Angelique Paulk and colleagues. The
+dataset can be dowloaed `on
+datadryad <https://datadryad.org/stash/dataset/doi:10.5061/dryad.d2547d840>`__.
+This challenging dataset contain recording on patient with neuropixel
+probe! But a very high and very fast motion on the probe prevent doing
+spike sorting.
+
+The **dredge** method has two sides **dredge_lfp** and **dredge_ap**.
+They both haave been ported inside spikeinterface. Here we will use the
+**dredge_lfp**.
+
+Here we demonstrate how to use this method to estimate the fast and high
+drift on this recording.
+
+For each patient, the dataset contains two recording : a high pass (AP -
+30kHz) and a low pass (FP - 2.5kHz). We will use the low pass here.
+
+.. code:: ipython3
+
+    %matplotlib inline
+    %load_ext autoreload
+    %autoreload 2
+
+.. code:: ipython3
+
+    from pathlib import Path
+    import matplotlib.pyplot as plt
+    
+    import spikeinterface.full as si
+    from spikeinterface.sortingcomponents.motion import estimate_motion
+
+.. code:: ipython3
+
+    # the dataset has been locally downloaded
+    base_folder = Path("/mnt/data/sam/DataSpikeSorting/")
+    np_data_drift = base_folder / 'human_neuropixel/Pt02/'
+
+read the spikeglx file
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: ipython3
+
+    raw_rec = si.read_spikeglx(np_data_drift)
+    print(raw_rec)
+
+
+.. parsed-literal::
+
+    SpikeGLXRecordingExtractor: 384 channels - 2.5kHz - 1 segments - 2,183,292 samples 
+                                873.32s (14.56 minutes) - int16 dtype - 1.56 GiB
+
+
+preprocessing
+~~~~~~~~~~~~~
+
+Contrary to **dredge_ap** which need peak and peak location, the
+**dredge_lfp** is estimating the motion directly on traces but the
+method need an important preprocessing: \* low pass filter : this focus
+the signal on a particular band \* phase_shift : this is needed to
+conpensate the digitalization unalignement \* resample : the sample
+fequency of the signal will be the sample frequency of the estimated
+motion. Here we choose 250Hz to have 4ms precission. \*
+directional_derivative : this optional step apply a derivative at second
+order to enhance edges on the traces. This is not a general rules and
+need to be tested case by case. \* average_across_direction : neuropixel
+1 probe has several contact per depth. They are average to get a unique
+virtual signal along the probe depth (“y” in probeinterface and
+spikeinterface).
+
+When appying this preprocessing the motion can be estimated almost by
+eyes ont the traces plotted with the map mode.
+
+.. code:: ipython3
+
+    lfprec = si.bandpass_filter(
+        raw_rec,
+        freq_min=0.5,
+        freq_max=250,
+    
+        margin_ms=1500.,
+        filter_order=3,
+        dtype="float32",
+        add_reflect_padding=True,
+    )
+    lfprec = si.phase_shift(lfprec)
+    lfprec = si.resample(lfprec, resample_rate=250, margin_ms=1000)
+    
+    lfprec = si.directional_derivative(lfprec, order=2, edge_order=1)
+    lfprec = si.average_across_direction(lfprec)
+    
+    print(lfprec)
+
+
+.. parsed-literal::
+
+    AverageAcrossDirectionRecording: 192 channels - 0.2kHz - 1 segments - 218,329 samples 
+                                     873.32s (14.56 minutes) - float32 dtype - 159.91 MiB
+
+
+.. code:: ipython3
+
+    %matplotlib inline
+    si.plot_traces(lfprec, backend="matplotlib", mode="map", clim=(-0.05, 0.05), time_range=(400, 420))
+
+
+
+
+.. parsed-literal::
+
+    <spikeinterface.widgets.traces.TracesWidget at 0x75bc74d0af90>
+
+
+
+
+.. image:: drift_with_lfp_files/drift_with_lfp_8_1.png
+
+
+Run the method
+~~~~~~~~~~~~~~
+
+``estimate_motion()`` is the generic funciton with multi method in
+spikeinterface.
+
+This return a ``Motion`` object, you can note that the interval is
+exactly the same as downsampled signal.
+
+Here we use ``rigid=True``, this means that we have one unqiue signal to
+describe the motion for the entire probe.
+
+.. code:: ipython3
+
+    motion = estimate_motion(lfprec, method='dredge_lfp', rigid=True, progress_bar=True)
+    motion
+
+
+
+.. parsed-literal::
+
+    Online chunks [10.0s each]:   0%|          | 0/87 [00:00<?, ?it/s]
+
+
+
+
+.. parsed-literal::
+
+    Motion rigid - interval 0.004s - 1 segments
+
+
+
+plot the drift
+~~~~~~~~~~~~~~
+
+When plotting the drift, we can notice a very fast drift which
+corresponf to the heart rate.
+
+This motion match the LFP signal above.
+
+.. code:: ipython3
+
+    fig, ax = plt.subplots()
+    si.plot_motion(motion, mode='line', ax=ax)
+    ax.set_xlim(400, 420)
+    ax.set_ylim(800, 1300)
+
+
+
+
+
+.. parsed-literal::
+
+    (800.0, 1300.0)
+
+
+
+
+.. image:: drift_with_lfp_files/drift_with_lfp_12_1.png
+
+
diff --git a/doc/how_to/drift_with_lfp_files/drift_with_lfp_12_1.png b/doc/how_to/drift_with_lfp_files/drift_with_lfp_12_1.png
new file mode 100644
index 0000000000000000000000000000000000000000..745ca5fce08eb3e402d9e33e3b7957c840ac98a3
GIT binary patch
literal 48141
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
O!5+(~NS8_)2K+At*QCn;

literal 0
HcmV?d00001

diff --git a/doc/how_to/drift_with_lfp_files/drift_with_lfp_8_1.png b/doc/how_to/drift_with_lfp_files/drift_with_lfp_8_1.png
new file mode 100644
index 0000000000000000000000000000000000000000..c38c2eb6c564d8a76567d122e63c4359aaeae7ba
GIT binary patch
literal 195184
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
SGShv)pRvL1n-$j|MExHCA01Z!

literal 0
HcmV?d00001

diff --git a/examples/how_to/drift_with_lfp.py b/examples/how_to/drift_with_lfp.py
new file mode 100644
index 0000000000..fe84b2ab48
--- /dev/null
+++ b/examples/how_to/drift_with_lfp.py
@@ -0,0 +1,113 @@
+# ---
+# jupyter:
+#   jupytext:
+#     cell_metadata_filter: -all
+#     formats: ipynb,py
+#     text_representation:
+#       extension: .py
+#       format_name: light
+#       format_version: '1.5'
+#       jupytext_version: 1.16.2
+#   kernelspec:
+#     display_name: Python 3 (ipykernel)
+#     language: python
+#     name: python3
+# ---
+
+# # Estimate drift using the LFP traces
+#
+# Charlie Windolf and colleagues have developed a method to estimate the motion using the LFP signal : **dredge**.
+#
+# You can see more detail in this preprint [DREDge: robust motion correction for high-density extracellular recordings across species](https://www.biorxiv.org/content/10.1101/2023.10.24.563768v1)
+#
+# This method is particularly adapated for the open dataset recorded at Massachusetts General Hospital by Angelique Paulk and colleagues. The dataset can be dowloaed [on datadryad](https://datadryad.org/stash/dataset/doi:10.5061/dryad.d2547d840).
+# This challenging dataset contain recording on patient with neuropixel probe! But a very high and very fast motion on the probe prevent doing spike sorting.
+#
+# The **dredge** method has two sides **dredge_lfp** and **dredge_ap**. They both haave been ported inside spikeinterface. Here we will use the **dredge_lfp**.
+#
+# Here we demonstrate how to use this method to estimate the fast and high drift on this recording.
+#
+# For each patient, the dataset contains two recording : a high pass (AP - 30kHz) and a low pass (FP - 2.5kHz).
+# We will use the low pass here.
+
+# %matplotlib inline
+# %load_ext autoreload
+# %autoreload 2
+
+# +
+from pathlib import Path
+import matplotlib.pyplot as plt
+
+import spikeinterface.full as si
+from spikeinterface.sortingcomponents.motion import estimate_motion
+# -
+
+# the dataset has been locally downloaded
+base_folder = Path("/mnt/data/sam/DataSpikeSorting/")
+np_data_drift = base_folder / 'human_neuropixel/Pt02/'
+
+# ### read the spikeglx file
+
+raw_rec = si.read_spikeglx(np_data_drift)
+print(raw_rec)
+
+# ### preprocessing
+#
+# Contrary to **dredge_ap** which need peak and peak location, the **dredge_lfp** is estimating the motion directly on traces but the method need an important preprocessing:
+#   * low pass filter  : this focus the signal on a particular band
+#   * phase_shift : this is needed to conpensate the digitalization unalignement
+#   * resample : the sample fequency of the signal will be the sample frequency of the estimated motion. Here we choose      250Hz to have 4ms precission.
+#   * directional_derivative : this optional step apply a derivative at second order to enhance edges on the traces.
+#     This is not a general rules and need to be tested case by case.
+#   * average_across_direction : neuropixel 1 probe has several contact per depth. They are average to get a unique          virtual signal along the probe depth ("y" in probeinterface and spikeinterface).
+#
+# When appying this preprocessing the motion can be estimated almost by eyes ont the traces plotted with the map mode.
+
+# +
+lfprec = si.bandpass_filter(
+    raw_rec,
+    freq_min=0.5,
+    freq_max=250,
+
+    margin_ms=1500.,
+    filter_order=3,
+    dtype="float32",
+    add_reflect_padding=True,
+)
+lfprec = si.phase_shift(lfprec)
+lfprec = si.resample(lfprec, resample_rate=250, margin_ms=1000)
+
+lfprec = si.directional_derivative(lfprec, order=2, edge_order=1)
+lfprec = si.average_across_direction(lfprec)
+
+print(lfprec)
+# -
+
+# %matplotlib inline
+si.plot_traces(lfprec, backend="matplotlib", mode="map", clim=(-0.05, 0.05), time_range=(400, 420))
+
+# ### Run the method
+#
+# `estimate_motion()` is the generic funciton with multi method in spikeinterface.
+#
+# This return a `Motion` object, you can note that the interval is exactly the same as downsampled signal.
+#
+# Here we use `rigid=True`, this means that we have one unqiue signal to describe the motion for the entire probe.
+
+motion = estimate_motion(lfprec, method='dredge_lfp', rigid=True, progress_bar=True)
+motion
+
+# ### plot the drift
+#
+# When plotting the drift, we can notice a very fast drift which corresponf to the heart rate.
+#
+# This motion match the LFP signal above.
+#
+
+fig, ax = plt.subplots()
+si.plot_motion(motion, mode='line', ax=ax)
+ax.set_xlim(400, 420)
+ax.set_ylim(800, 1300)
+
+
+
diff --git a/src/spikeinterface/sortingcomponents/motion/decentralized.py b/src/spikeinterface/sortingcomponents/motion/decentralized.py
index a01fb2ffb3..396a18bba2 100644
--- a/src/spikeinterface/sortingcomponents/motion/decentralized.py
+++ b/src/spikeinterface/sortingcomponents/motion/decentralized.py
@@ -2,16 +2,11 @@
 
 from tqdm.auto import tqdm, trange
 
-try:
-    import torch
-    import torch.nn.functional as F
-
-    HAVE_TORCH = True
-except ImportError:
-    HAVE_TORCH = False
 
 from .motion_utils import Motion, get_spatial_windows, get_spatial_bin_edges, make_2d_motion_histogram, scipy_conv1d
 
+from .dredge import normxcorr1d
+
 
 class DecentralizedRegistration:
     """
@@ -140,9 +135,7 @@ def run(
         lsqr_robust_n_iter=20,
         weight_with_amplitude=False,
     ):
-        # use torch if installed
-        if conv_engine is None:
-            conv_engine = "torch" if HAVE_TORCH else "numpy"
+        
 
         dim = ["x", "y", "z"].index(direction)
         contact_depth = recording.get_channel_locations()[:, dim]
@@ -324,6 +317,15 @@ def compute_pairwise_displacement(
     """
     from scipy import linalg
 
+    if conv_engine is None:
+        # use torch if installed
+        try:
+            import torch
+            import torch.nn.functional as F
+            conv_engine = "torch"
+        except ImportError:
+            conv_engine = "numpy"
+
     assert conv_engine in ("torch", "numpy"), f"'conv_engine' must be 'torch' or 'numpy'"
     size = motion_hist.shape[0]
     pairwise_displacement = np.zeros((size, size), dtype="float32")
@@ -685,123 +687,126 @@ def jac(p):
     return np.squeeze(displacement)
 
 
-# TODO charlie sam : make a unique function for this
-# at the moment this is the legacy one ported in spikeinterface
-# the one in deredge.py is more recent
-def normxcorr1d(
-    template,
-    x,
-    weights=None,
-    centered=True,
-    normalized=True,
-    padding="same",
-    conv_engine="torch",
-):
-    """normxcorr1d: Normalized cross-correlation, optionally weighted
-
-    The API is like torch's F.conv1d, except I have accidentally
-    changed the position of input/weights -- template acts like weights,
-    and x acts like input.
-
-    Returns the cross-correlation of `template` and `x` at spatial lags
-    determined by `mode`. Useful for estimating the location of `template`
-    within `x`.
-
-    This might not be the most efficient implementation -- ideas welcome.
-    It uses a direct convolutional translation of the formula
-        corr = (E[XY] - EX EY) / sqrt(var X * var Y)
-
-    This also supports weights! In that case, the usual adaptation of
-    the above formula is made to the weighted case -- and all of the
-    normalizations are done per block in the same way.
-
-    Parameters
-    ----------
-    template : tensor, shape (num_templates, length)
-        The reference template signal
-    x : tensor, 1d shape (length,) or 2d shape (num_inputs, length)
-        The signal in which to find `template`
-    weights : tensor, shape (length,)
-        Will use weighted means, variances, covariances if supplied.
-    centered : bool
-        If true, means will be subtracted (per weighted patch).
-    normalized : bool
-        If true, normalize by the variance (per weighted patch).
-    padding : str
-        How far to look? if unset, we'll use half the length
-    conv_engine : string, one of "torch", "numpy"
-        What library to use for computing cross-correlations.
-        If numpy, falls back to the scipy correlate function.
-
-    Returns
-    -------
-    corr : tensor
-    """
-    if conv_engine == "torch":
-        assert HAVE_TORCH
-        conv1d = F.conv1d
-        npx = torch
-    elif conv_engine == "numpy":
-        conv1d = scipy_conv1d
-        npx = np
-    else:
-        raise ValueError(f"Unknown conv_engine {conv_engine}. 'conv_engine' must be 'torch' or 'numpy'")
-
-    x = npx.atleast_2d(x)
-    num_templates, length = template.shape
-    num_inputs, length_ = template.shape
-    assert length == length_
-
-    # generalize over weighted / unweighted case
-    device_kw = {} if conv_engine == "numpy" else dict(device=x.device)
-    ones = npx.ones((1, 1, length), dtype=x.dtype, **device_kw)
-    no_weights = weights is None
-    if no_weights:
-        weights = ones
-        wt = template[:, None, :]
-    else:
-        assert weights.shape == (length,)
-        weights = weights[None, None]
-        wt = template[:, None, :] * weights
-
-    # conv1d valid rule:
-    # (B,1,L),(O,1,L)->(B,O,L)
-
-    # compute expectations
-    # how many points in each window? seems necessary to normalize
-    # for numerical stability.
-    N = conv1d(ones, weights, padding=padding)
-    if centered:
-        Et = conv1d(ones, wt, padding=padding)
-        Et /= N
-        Ex = conv1d(x[:, None, :], weights, padding=padding)
-        Ex /= N
-
-    # compute (weighted) covariance
-    # important: the formula E[XY] - EX EY is well-suited here,
-    # because the means are naturally subtracted correctly
-    # patch-wise. you couldn't pre-subtract them!
-    cov = conv1d(x[:, None, :], wt, padding=padding)
-    cov /= N
-    if centered:
-        cov -= Ex * Et
-
-    # compute variances for denominator, using var X = E[X^2] - (EX)^2
-    if normalized:
-        var_template = conv1d(ones, wt * template[:, None, :], padding=padding)
-        var_template /= N
-        var_x = conv1d(npx.square(x)[:, None, :], weights, padding=padding)
-        var_x /= N
-        if centered:
-            var_template -= npx.square(Et)
-            var_x -= npx.square(Ex)
-
-    # now find the final normxcorr
-    corr = cov  # renaming for clarity
-    if normalized:
-        corr /= npx.sqrt(var_x)
-        corr /= npx.sqrt(var_template)
-        # get rid of NaNs in zero-variance areas
-        corr[~npx.isfinite(corr)] = 0
-
-    return corr
\ No newline at end of file
+
+
+
+# normxcorr1d is now implemented in dredge
+# we keep the old version here but this will be removed soon
+
+# def normxcorr1d(
+#     template,
+#     x,
+#     weights=None,
+#     centered=True,
+#     normalized=True,
+#     padding="same",
+#     conv_engine="torch",
+# ):
+#     """normxcorr1d: Normalized cross-correlation, optionally weighted
+
+#     The API is like torch's F.conv1d, except I have accidentally
+#     changed the position of input/weights -- template acts like weights,
+#     and x acts like input.
+
+#     Returns the cross-correlation of `template` and `x` at spatial lags
+#     determined by `mode`. Useful for estimating the location of `template`
+#     within `x`.
+
+#     This might not be the most efficient implementation -- ideas welcome.
+#     It uses a direct convolutional translation of the formula
+#         corr = (E[XY] - EX EY) / sqrt(var X * var Y)
+
+#     This also supports weights! In that case, the usual adaptation of
+#     the above formula is made to the weighted case -- and all of the
+#     normalizations are done per block in the same way.
+
+#     Parameters
+#     ----------
+#     template : tensor, shape (num_templates, length)
+#         The reference template signal
+#     x : tensor, 1d shape (length,) or 2d shape (num_inputs, length)
+#         The signal in which to find `template`
+#     weights : tensor, shape (length,)
+#         Will use weighted means, variances, covariances if supplied.
+#     centered : bool
+#         If true, means will be subtracted (per weighted patch).
+#     normalized : bool
+#         If true, normalize by the variance (per weighted patch).
+#     padding : str
+#         How far to look? if unset, we'll use half the length
+#     conv_engine : string, one of "torch", "numpy"
+#         What library to use for computing cross-correlations.
+#         If numpy, falls back to the scipy correlate function.
+
+#     Returns
+#     -------
+#     corr : tensor
+#     """
+#     if conv_engine == "torch":
+#         assert HAVE_TORCH
+#         conv1d = F.conv1d
+#         npx = torch
+#     elif conv_engine == "numpy":
+#         conv1d = scipy_conv1d
+#         npx = np
+#     else:
+#         raise ValueError(f"Unknown conv_engine {conv_engine}. 'conv_engine' must be 'torch' or 'numpy'")
+
+#     x = npx.atleast_2d(x)
+#     num_templates, length = template.shape
+#     num_inputs, length_ = template.shape
+#     assert length == length_
+
+#     # generalize over weighted / unweighted case
+#     device_kw = {} if conv_engine == "numpy" else dict(device=x.device)
+#     ones = npx.ones((1, 1, length), dtype=x.dtype, **device_kw)
+#     no_weights = weights is None
+#     if no_weights:
+#         weights = ones
+#         wt = template[:, None, :]
+#     else:
+#         assert weights.shape == (length,)
+#         weights = weights[None, None]
+#         wt = template[:, None, :] * weights
+
+#     # conv1d valid rule:
+#     # (B,1,L),(O,1,L)->(B,O,L)
+
+#     # compute expectations
+#     # how many points in each window? seems necessary to normalize
+#     # for numerical stability.
+#     N = conv1d(ones, weights, padding=padding)
+#     if centered:
+#         Et = conv1d(ones, wt, padding=padding)
+#         Et /= N
+#         Ex = conv1d(x[:, None, :], weights, padding=padding)
+#         Ex /= N
+
+#     # compute (weighted) covariance
+#     # important: the formula E[XY] - EX EY is well-suited here,
+#     # because the means are naturally subtracted correctly
+#     # patch-wise. you couldn't pre-subtract them!
+#     cov = conv1d(x[:, None, :], wt, padding=padding)
+#     cov /= N
+#     if centered:
+#         cov -= Ex * Et
+
+#     # compute variances for denominator, using var X = E[X^2] - (EX)^2
+#     if normalized:
+#         var_template = conv1d(ones, wt * template[:, None, :], padding=padding)
+#         var_template /= N
+#         var_x = conv1d(npx.square(x)[:, None, :], weights, padding=padding)
+#         var_x /= N
+#         if centered:
+#             var_template -= npx.square(Et)
+#             var_x -= npx.square(Ex)
+
+#     # now find the final normxcorr
+#     corr = cov  # renaming for clarity
+#     if normalized:
+#         corr /= npx.sqrt(var_x)
+#         corr /= npx.sqrt(var_template)
+#         # get rid of NaNs in zero-variance areas
+#         corr[~npx.isfinite(corr)] = 0
+
+#     return corr
\ No newline at end of file
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 71d7b0ea8d..9aa15852cd 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -31,9 +31,7 @@
 from .motion_utils import Motion, get_spatial_windows, get_window_domains, scipy_conv1d, make_2d_motion_histogram, get_spatial_bin_edges
 
 
-# todo use gaussian_filter1d in historgam 2d
-# put smotthing inside the histogram function
-# put the log for weight inhitstogram
+
 
 
 # simple class wrapper to be compliant with estimate_motion
@@ -157,9 +155,6 @@ def dredge_ap(
     histogram_depth_smooth_um=1,
     histogram_time_smooth_s=1,
     avg_in_bin=False,
-    count_masked_correlation=False,
-    count_bins=401,
-    count_bin_min=2,
     # low-level keyword args
     thomas_kw=None,
     xcorr_kw=None,
@@ -288,6 +283,8 @@ def dredge_ap(
     )
     raster = motion_histogram.T
 
+    # TODO charlie : put the log for hitstogram
+
 
     # TODO @charlie you should check that we are doing the same thing
     # windows, window_centers = get_spatial_windows(
@@ -1180,7 +1177,6 @@ def calc_corr_decent_pair(
     return D, C
 
 
-# TODO charlie sam : at the moment this is a duplicate with small differences see motion_estimate.py same function
 def normxcorr1d(
     template,
     x,
@@ -1190,6 +1186,7 @@ def normxcorr1d(
     normalized=True,
     padding="same",
     conv_engine="torch",
+
 ):
     """normxcorr1d: Normalized cross-correlation, optionally weighted
 
@@ -1223,10 +1220,10 @@ def normxcorr1d(
         If true, normalize by the variance (per weighted patch).
     padding : int, optional
         How far to look? if unset, we'll use half the length
-    conv_engine : string, one of "torch", "numpy"
+    conv_engine : "torch" | "numpy"
         What library to use for computing cross-correlations.
         If numpy, falls back to the scipy correlate function.
-
+conv_engine
     Returns
     -------
     corr : tensor
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
index 6cd935e582..f7f4f4ad66 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
@@ -14,6 +14,7 @@
 from .dredge import DredgeLfpRegistration, DredgeApRegistration
 
 
+# estimate_motion > infer_motion
 def estimate_motion(
     recording,
     peaks=None,

From 5c250e13e5b160691c49635a05e9187bbd5d4a69 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 8 Jul 2024 10:55:11 +0200
Subject: [PATCH 19/31] dredge_lfp doc

---
 doc/how_to/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/how_to/index.rst b/doc/how_to/index.rst
index 54fd404848..8fa14690f8 100644
--- a/doc/how_to/index.rst
+++ b/doc/how_to/index.rst
@@ -13,3 +13,4 @@ Guides on how to solve specific, short problems in SpikeInterface. Learn how to.
     combine_recordings
     process_by_channel_group
     load_your_data_into_sorting
+    drift_with_lfp

From 8ef01d90b2444dc3e018adc2447b59a48657dabf Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 8 Jul 2024 11:13:24 +0200
Subject: [PATCH 20/31] Add tutorial motion.

---
 .../plot_1_estimate_motion.py                 | 103 ++++++++++++++++++
 src/spikeinterface/preprocessing/motion.py    |  20 +++-
 2 files changed, 119 insertions(+), 4 deletions(-)
 create mode 100644 examples/tutorials/sortingcomponents/plot_1_estimate_motion.py

diff --git a/examples/tutorials/sortingcomponents/plot_1_estimate_motion.py b/examples/tutorials/sortingcomponents/plot_1_estimate_motion.py
new file mode 100644
index 0000000000..0ce60ac7d3
--- /dev/null
+++ b/examples/tutorials/sortingcomponents/plot_1_estimate_motion.py
@@ -0,0 +1,103 @@
+"""
+Motion estimation
+=================
+
+SpikeInterface offers a very flexible framework to handle drift as a
+preprocessing step. If you want to know more, please read the
+:ref:`motion_correction` section of the documentation.
+
+Here a short example with a simulated drifting recording.
+
+"""
+
+# %%
+import matplotlib.pyplot as plt
+
+
+from spikeinterface.generation import generate_drifting_recording
+from spikeinterface.preprocessing import correct_motion
+from spikeinterface.widgets import plot_motion, plot_motion_info, plot_probe_map
+
+# %%
+# First, let's simulate a drifting recording using the 
+# :code:`spikeinterface.generation module`.
+# 
+# Here the simulated recording has a small zigzag motion along the 'y' axis of the probe.
+
+static_recording, drifting_recording, sorting = generate_drifting_recording(
+    num_units=200,
+    duration=300.,
+    probe_name='Neuropixel-128', 
+    generate_displacement_vector_kwargs=dict(
+        displacement_sampling_frequency=5.0,
+        drift_start_um=[0, 20],
+        drift_stop_um=[0, -20],
+        drift_step_um=1,
+        motion_list=[
+            dict(
+                drift_mode="zigzag",
+                non_rigid_gradient=None,
+                t_start_drift=60.0,
+                t_end_drift=None,
+                period_s=200,
+            ),
+        ],
+    ),
+    seed=2205,
+)
+
+plot_probe_map(drifting_recording)
+
+# %%
+# Here we will use the high level function :code:`correct_motion()`
+# 
+# Internally, this function is doing all steps of the motion detection:
+#  1. **activity profile** : detect peaks and localize them along time and depth
+#  2. **motion inference**: estimate the drift motion
+#  3. **motion interpolation**: interpolate traces using the estimated motion
+# 
+# All steps have an use several methods with many parameters. This is why we can use
+# 'preset' which combine methods and related parameters.
+#
+# This function can take a while peak detection and localization is a slow process
+# that need to go trought the entire traces
+
+recording_corrected, motion, motion_info = correct_motion(
+    drifting_recording, preset="nonrigid_fast_and_accurate",
+    output_motion=True, output_motion_info=True,
+    n_jobs=-1, progress_bar=True,
+)
+
+# %%
+# The function return a recording 'corrected'
+# 
+# A new recording is return, this recording will interpolate motion corrected traces
+# when calling get_traces()
+
+print(recording_corrected)
+
+# %%
+# Optionally the function also return the `Motion` object itself
+# 
+
+print(motion)
+
+# %%
+# This motion can be plotted, in our case the motion has been estimated as non-rigid
+# so we can use the use the `mode='map'` to check the motion across depth.
+# 
+
+plot_motion(motion, mode='line')
+plot_motion(motion, mode='map')
+
+
+# %%
+# The dict `motion_info` can be used for more plotting.
+# Here we can appreciate of the two top axes the raster of peaks depth vs times before and 
+# after correction.
+
+fig = plt.figure()
+plot_motion_info(motion_info, drifting_recording, amplitude_cmap="inferno", color_amplitude=True, figure=fig)
+fig.axes[0].set_ylim(520, 620)
+plt.show()
+# %%
diff --git a/src/spikeinterface/preprocessing/motion.py b/src/spikeinterface/preprocessing/motion.py
index 82a89220bd..59b5a590c2 100644
--- a/src/spikeinterface/preprocessing/motion.py
+++ b/src/spikeinterface/preprocessing/motion.py
@@ -201,6 +201,7 @@ def correct_motion(
     recording,
     preset="nonrigid_accurate",
     folder=None,
+    output_motion=False,
     output_motion_info=False,
     overwrite=False,
     detect_kwargs={},
@@ -251,6 +252,8 @@ def correct_motion(
         The preset name
     folder : Path str or None, default: None
         If not None then intermediate motion info are saved into a folder
+    output_motion : bool, default: False
+        It True, the function returns a `motion` object.
     output_motion_info : bool, default: False
         If True, then the function returns a `motion_info` dictionary that contains variables
         to check intermediate steps (motion_histogram, non_rigid_windows, pairwise_displacement)
@@ -275,8 +278,11 @@ def correct_motion(
     -------
     recording_corrected : Recording
         The motion corrected recording
+    motion : Motion
+        Optional output if `output_motion=True`.
     motion_info : dict
-        Optional output if `output_motion_info=True`. The key "motion" holds the Motion object.
+        Optional output if `output_motion_info=True`. This dict contains several variable for
+        for plotting. See `plot_motion_info()`
     """
     # local import are important because "sortingcomponents" is not important by default
     from spikeinterface.sortingcomponents.peak_detection import detect_peaks, detect_peak_methods
@@ -390,10 +396,16 @@ def correct_motion(
     if folder is not None:
         save_motion_info(motion_info, folder, overwrite=overwrite)
 
-    if output_motion_info:
-        return recording_corrected, motion_info
-    else:
+    if not output_motion and not output_motion_info:
         return recording_corrected
+    
+    out = (recording_corrected, )
+    if output_motion:
+        out += (motion, )
+    if output_motion_info:
+        out += (motion_info, )
+    return out
+
 
 
 _doc_presets = "\n"

From 18b7cfebfcd52c08513a521f96da6975bb0d89aa Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 11 Jul 2024 08:53:59 +0000
Subject: [PATCH 21/31] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 doc/how_to/drift_with_lfp.rst                 |  14 +-
 doc/how_to/index.rst                          |   2 +-
 examples/how_to/drift_with_lfp.py             |   3 -
 .../plot_1_estimate_motion.py                 |  18 +-
 src/spikeinterface/preprocessing/motion.py    |  14 +-
 .../sortingcomponents/motion/__init__.py      |   8 +-
 .../sortingcomponents/motion/decentralized.py |  14 +-
 .../sortingcomponents/motion/dredge.py        | 222 +++++++-----------
 .../motion/iterative_template.py              |   3 -
 .../motion/motion_cleaner.py                  |   3 +-
 .../motion/motion_estimation.py               |  12 +-
 .../sortingcomponents/motion/motion_utils.py  |  28 +--
 .../motion/tests/test_drege.py                |   2 -
 .../motion/tests/test_motion_estimation.py    |   3 +-
 14 files changed, 134 insertions(+), 212 deletions(-)

diff --git a/doc/how_to/drift_with_lfp.rst b/doc/how_to/drift_with_lfp.rst
index e8d48301a0..a215f0920f 100644
--- a/doc/how_to/drift_with_lfp.rst
+++ b/doc/how_to/drift_with_lfp.rst
@@ -36,7 +36,7 @@ For each patient, the dataset contains two recording : a high pass (AP -
 
     from pathlib import Path
     import matplotlib.pyplot as plt
-    
+
     import spikeinterface.full as si
     from spikeinterface.sortingcomponents.motion import estimate_motion
 
@@ -57,7 +57,7 @@ read the spikeglx file
 
 .. parsed-literal::
 
-    SpikeGLXRecordingExtractor: 384 channels - 2.5kHz - 1 segments - 2,183,292 samples 
+    SpikeGLXRecordingExtractor: 384 channels - 2.5kHz - 1 segments - 2,183,292 samples
                                 873.32s (14.56 minutes) - int16 dtype - 1.56 GiB
 
 
@@ -87,7 +87,7 @@ eyes ont the traces plotted with the map mode.
         raw_rec,
         freq_min=0.5,
         freq_max=250,
-    
+
         margin_ms=1500.,
         filter_order=3,
         dtype="float32",
@@ -95,16 +95,16 @@ eyes ont the traces plotted with the map mode.
     )
     lfprec = si.phase_shift(lfprec)
     lfprec = si.resample(lfprec, resample_rate=250, margin_ms=1000)
-    
+
     lfprec = si.directional_derivative(lfprec, order=2, edge_order=1)
     lfprec = si.average_across_direction(lfprec)
-    
+
     print(lfprec)
 
 
 .. parsed-literal::
 
-    AverageAcrossDirectionRecording: 192 channels - 0.2kHz - 1 segments - 218,329 samples 
+    AverageAcrossDirectionRecording: 192 channels - 0.2kHz - 1 segments - 218,329 samples
                                      873.32s (14.56 minutes) - float32 dtype - 159.91 MiB
 
 
@@ -185,5 +185,3 @@ This motion match the LFP signal above.
 
 
 .. image:: drift_with_lfp_files/drift_with_lfp_12_1.png
-
-
diff --git a/doc/how_to/index.rst b/doc/how_to/index.rst
index cf9cadcfc3..5d7eae9003 100644
--- a/doc/how_to/index.rst
+++ b/doc/how_to/index.rst
@@ -14,4 +14,4 @@ Guides on how to solve specific, short problems in SpikeInterface. Learn how to.
     process_by_channel_group
     load_your_data_into_sorting
     benchmark_with_hybrid_recordings
-    drift_with_lfp
\ No newline at end of file
+    drift_with_lfp
diff --git a/examples/how_to/drift_with_lfp.py b/examples/how_to/drift_with_lfp.py
index fe84b2ab48..df656bc4ae 100644
--- a/examples/how_to/drift_with_lfp.py
+++ b/examples/how_to/drift_with_lfp.py
@@ -108,6 +108,3 @@
 si.plot_motion(motion, mode='line', ax=ax)
 ax.set_xlim(400, 420)
 ax.set_ylim(800, 1300)
-
-
-
diff --git a/examples/tutorials/sortingcomponents/plot_1_estimate_motion.py b/examples/tutorials/sortingcomponents/plot_1_estimate_motion.py
index 0ce60ac7d3..87eaa4c51a 100644
--- a/examples/tutorials/sortingcomponents/plot_1_estimate_motion.py
+++ b/examples/tutorials/sortingcomponents/plot_1_estimate_motion.py
@@ -19,15 +19,15 @@
 from spikeinterface.widgets import plot_motion, plot_motion_info, plot_probe_map
 
 # %%
-# First, let's simulate a drifting recording using the 
+# First, let's simulate a drifting recording using the
 # :code:`spikeinterface.generation module`.
-# 
+#
 # Here the simulated recording has a small zigzag motion along the 'y' axis of the probe.
 
 static_recording, drifting_recording, sorting = generate_drifting_recording(
     num_units=200,
     duration=300.,
-    probe_name='Neuropixel-128', 
+    probe_name='Neuropixel-128',
     generate_displacement_vector_kwargs=dict(
         displacement_sampling_frequency=5.0,
         drift_start_um=[0, 20],
@@ -50,12 +50,12 @@
 
 # %%
 # Here we will use the high level function :code:`correct_motion()`
-# 
+#
 # Internally, this function is doing all steps of the motion detection:
 #  1. **activity profile** : detect peaks and localize them along time and depth
 #  2. **motion inference**: estimate the drift motion
 #  3. **motion interpolation**: interpolate traces using the estimated motion
-# 
+#
 # All steps have an use several methods with many parameters. This is why we can use
 # 'preset' which combine methods and related parameters.
 #
@@ -70,7 +70,7 @@
 
 # %%
 # The function return a recording 'corrected'
-# 
+#
 # A new recording is return, this recording will interpolate motion corrected traces
 # when calling get_traces()
 
@@ -78,14 +78,14 @@
 
 # %%
 # Optionally the function also return the `Motion` object itself
-# 
+#
 
 print(motion)
 
 # %%
 # This motion can be plotted, in our case the motion has been estimated as non-rigid
 # so we can use the use the `mode='map'` to check the motion across depth.
-# 
+#
 
 plot_motion(motion, mode='line')
 plot_motion(motion, mode='map')
@@ -93,7 +93,7 @@
 
 # %%
 # The dict `motion_info` can be used for more plotting.
-# Here we can appreciate of the two top axes the raster of peaks depth vs times before and 
+# Here we can appreciate of the two top axes the raster of peaks depth vs times before and
 # after correction.
 
 fig = plt.figure()
diff --git a/src/spikeinterface/preprocessing/motion.py b/src/spikeinterface/preprocessing/motion.py
index 59b5a590c2..0568650316 100644
--- a/src/spikeinterface/preprocessing/motion.py
+++ b/src/spikeinterface/preprocessing/motion.py
@@ -20,7 +20,7 @@
             peak_sign="neg",
             detect_threshold=8.0,
             exclude_sweep_ms=0.8,
-            radius_um=80.,
+            radius_um=80.0,
         ),
         "select_kwargs": dict(),
         "localize_peaks_kwargs": dict(
@@ -76,7 +76,7 @@
             peak_sign="neg",
             detect_threshold=8.0,
             exclude_sweep_ms=0.8,
-            radius_um=80.,
+            radius_um=80.0,
         ),
         "select_kwargs": dict(),
         "localize_peaks_kwargs": dict(
@@ -196,7 +196,6 @@
 }
 
 
-
 def correct_motion(
     recording,
     preset="nonrigid_accurate",
@@ -398,16 +397,15 @@ def correct_motion(
 
     if not output_motion and not output_motion_info:
         return recording_corrected
-    
-    out = (recording_corrected, )
+
+    out = (recording_corrected,)
     if output_motion:
-        out += (motion, )
+        out += (motion,)
     if output_motion_info:
-        out += (motion_info, )
+        out += (motion_info,)
     return out
 
 
-
 _doc_presets = "\n"
 for k, v in motion_options_preset.items():
     if k == "":
diff --git a/src/spikeinterface/sortingcomponents/motion/__init__.py b/src/spikeinterface/sortingcomponents/motion/__init__.py
index 15233efc32..d2e6a8a3d9 100644
--- a/src/spikeinterface/sortingcomponents/motion/__init__.py
+++ b/src/spikeinterface/sortingcomponents/motion/__init__.py
@@ -1,5 +1,9 @@
 from .motion_utils import Motion
 from .motion_estimation import estimate_motion
-from .motion_interpolation import (correct_motion_on_peaks, interpolate_motion_on_traces,
-                                   InterpolateMotionRecording, interpolate_motion)
+from .motion_interpolation import (
+    correct_motion_on_peaks,
+    interpolate_motion_on_traces,
+    InterpolateMotionRecording,
+    interpolate_motion,
+)
 from .motion_cleaner import clean_motion_vector
diff --git a/src/spikeinterface/sortingcomponents/motion/decentralized.py b/src/spikeinterface/sortingcomponents/motion/decentralized.py
index 396a18bba2..d054995839 100644
--- a/src/spikeinterface/sortingcomponents/motion/decentralized.py
+++ b/src/spikeinterface/sortingcomponents/motion/decentralized.py
@@ -111,8 +111,8 @@ def run(
         bin_um=1.0,
         hist_margin_um=20.0,
         bin_s=1.0,
-        histogram_depth_smooth_um=1.,
-        histogram_time_smooth_s=1.,
+        histogram_depth_smooth_um=1.0,
+        histogram_time_smooth_s=1.0,
         pairwise_displacement_method="conv",
         max_displacement_um=100.0,
         weight_scale="linear",
@@ -135,7 +135,6 @@ def run(
         lsqr_robust_n_iter=20,
         weight_with_amplitude=False,
     ):
-        
 
         dim = ["x", "y", "z"].index(direction)
         contact_depth = recording.get_channel_locations()[:, dim]
@@ -153,7 +152,7 @@ def run(
             win_step_um=win_step_um,
             win_scale_um=win_scale_um,
             win_margin_um=win_margin_um,
-            zero_threshold=None
+            zero_threshold=None,
         )
 
         # make 2D histogram raster
@@ -322,6 +321,7 @@ def compute_pairwise_displacement(
         try:
             import torch
             import torch.nn.functional as F
+
             conv_engine = "torch"
         except ImportError:
             conv_engine = "numpy"
@@ -430,7 +430,6 @@ def compute_pairwise_displacement(
     return pairwise_displacement, pairwise_displacement_weight
 
 
-
 _possible_convergence_method = ("lsmr", "gradient_descent", "lsqr_robust")
 
 
@@ -687,9 +686,6 @@ def jac(p):
     return np.squeeze(displacement)
 
 
-
-
-
 # normxcorr1d is now implemented in dredge
 # we keep the old version here but this will be removed soon
 
@@ -809,4 +805,4 @@ def jac(p):
 #         # get rid of NaNs in zero-variance areas
 #         corr[~npx.isfinite(corr)] = 0
 
-#     return corr
\ No newline at end of file
+#     return corr
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 9aa15852cd..3eb83dfbaa 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -2,7 +2,7 @@
 Copy-paste and then refactoring of DREDge
 https://github.com/evarol/dredge
 
-For historical reason, some function from the DREDge package where implemeneted 
+For historical reason, some function from the DREDge package where implemeneted
 in spikeinterface in the motion_estimation.py before the DREDge package itself!
 
 Here a copy/paste (and small rewriting) of some functions from DREDge.
@@ -21,6 +21,7 @@
 but the original function dredge_ap() and dredge_online_lfp() can be used directly.
 
 """
+
 import warnings
 
 from tqdm.auto import trange
@@ -28,10 +29,14 @@
 
 import gc
 
-from .motion_utils import Motion, get_spatial_windows, get_window_domains, scipy_conv1d, make_2d_motion_histogram, get_spatial_bin_edges
-
-
-
+from .motion_utils import (
+    Motion,
+    get_spatial_windows,
+    get_window_domains,
+    scipy_conv1d,
+    make_2d_motion_histogram,
+    get_spatial_bin_edges,
+)
 
 
 # simple class wrapper to be compliant with estimate_motion
@@ -84,6 +89,7 @@ class DredgeApRegistration:
     device : str or torch.device
         What torch device to run on? E.g., "cpu" or "cuda" or "cuda:1".
     """
+
     @classmethod
     def run(
         cls,
@@ -102,7 +108,6 @@ def run(
         **method_kwargs,
     ):
 
-
         outs = dredge_ap(
             recording,
             peaks,
@@ -141,7 +146,7 @@ def dredge_ap(
     bin_um=1.0,
     bin_s=1.0,
     max_disp_um=None,
-    time_horizon_s=1000.,
+    time_horizon_s=1000.0,
     mincorr=0.1,
     # weights arguments
     do_window_weights=True,
@@ -217,14 +222,12 @@ def dredge_ap(
     depths_um = peak_depths = peak_locations[direction]
     times_s = peak_times = recording.sample_index_to_time(peaks["sample_index"])
 
-
-
     thomas_kw = thomas_kw if thomas_kw is not None else {}
     xcorr_kw = xcorr_kw if xcorr_kw is not None else {}
     if time_horizon_s:
         xcorr_kw["max_dt_bins"] = np.ceil(time_horizon_s / bin_s)
-    
-    #TODO @charlie I think this is a bad to have the dict which is transported to every function
+
+    # TODO @charlie I think this is a bad to have the dict which is transported to every function
     # this should be used only in histogram function but not in weight_correlation_matrix()
     # only important kwargs should be explicitly reported
     # raster_kw = dict(
@@ -251,8 +254,6 @@ def dredge_ap(
     # this will store return values other than the MotionEstimate
     extra = {}
 
-
-
     # TODO charlie I switch this to make_2d_motion_histogram
     # but we need to add all options from the original spike_raster()
     # but I think this is OK
@@ -266,7 +267,7 @@ def dredge_ap(
     #     raster, spatial_bin_edges_um, time_bin_edges_s, counts = raster_res
     # else:
     #     raster, spatial_bin_edges_um, time_bin_edges_s = raster_res
-    
+
     motion_histogram, time_bin_edges_s, spatial_bin_edges_um = make_2d_motion_histogram(
         recording,
         peaks,
@@ -276,7 +277,7 @@ def dredge_ap(
         direction=direction,
         bin_s=bin_s,
         bin_um=bin_um,
-        hist_margin_um=0.,  # @charlie maybe we should expose this and set +20. for instance
+        hist_margin_um=0.0,  # @charlie maybe we should expose this and set +20. for instance
         spatial_bin_edges=None,
         depth_smooth_um=histogram_depth_smooth_um,
         time_smooth_s=histogram_time_smooth_s,
@@ -285,7 +286,6 @@ def dredge_ap(
 
     # TODO charlie : put the log for hitstogram
 
-
     # TODO @charlie you should check that we are doing the same thing
     # windows, window_centers = get_spatial_windows(
     #     np.c_[np.zeros_like(spatial_bin_edges_um), spatial_bin_edges_um],
@@ -301,7 +301,7 @@ def dredge_ap(
     dim = ["x", "y", "z"].index(direction)
     contact_depth = recording.get_channel_locations()[:, dim]
     spatial_bin_centers = 0.5 * (spatial_bin_edges_um[1:] + spatial_bin_edges_um[:-1])
-    
+
     windows, window_centers = get_spatial_windows(
         contact_depth,
         spatial_bin_centers,
@@ -310,16 +310,13 @@ def dredge_ap(
         win_step_um=win_step_um,
         win_scale_um=win_scale_um,
         win_margin_um=win_margin_um,
-        zero_threshold=1e-5
-        )
-
-
+        zero_threshold=1e-5,
+    )
 
     # TODO charlie : the count has disapeared
     # if extra_outputs and count_masked_correlation:
     #     extra["counts"] = counts
 
-    
     # cross-correlate to get D and C
     if precomputed_D_C_maxdisp is None:
         Ds, Cs, max_disp_um = xcorr_windows(
@@ -348,7 +345,7 @@ def dredge_ap(
         spatial_bin_edges_um,
         time_bin_edges_s,
         # raster_kw, #@charlie this is removed
-        post_transform=post_transform, # @charlie this isnew
+        post_transform=post_transform,  # @charlie this isnew
         lambda_t=thomas_kw.get("lambda_t", DEFAULT_LAMBDA_T),
         eps=thomas_kw.get("eps", DEFAULT_EPS),
         progress_bar=progress_bar,
@@ -403,6 +400,7 @@ class DredgeLfpRegistration:
 
     The reference is here https://www.biorxiv.org/content/10.1101/2023.10.24.563768v1
     """
+
     name = "dredge_lfp"
     need_peak_location = False
     params_doc = """
@@ -447,6 +445,7 @@ class DredgeLfpRegistration:
     device : string or torch.device
         Controls torch device
     """
+
     @classmethod
     def run(
         cls,
@@ -462,7 +461,6 @@ def run(
         verbose,
         progress_bar,
         extra,
-
         **method_kwargs,
     ):
         # Note peaks and peak_locations are not used and can be None
@@ -488,24 +486,17 @@ def run(
         return motion
 
 
-
-
-
-
 def dredge_online_lfp(
     lfp_recording,
-    direction='y',
+    direction="y",
     # nonrigid window construction arguments
     rigid=True,
     win_shape="gaussian",
     win_step_um=800,
     win_scale_um=850,
     win_margin_um=None,
-    
     chunk_len_s=10.0,
     max_disp_um=500,
-    
-    
     time_horizon_s=None,
     # weighting arguments
     mincorr=0.8,
@@ -537,7 +528,6 @@ def dredge_online_lfp(
     # contact pos is the only on the direction
     contact_depth = lfp_recording.get_channel_locations()[:, dim]
 
-
     fs = lfp_recording.get_sampling_frequency()
     T_total = lfp_recording.get_num_samples()
     T_chunk = min(int(np.floor(fs * chunk_len_s)), T_total)
@@ -563,7 +553,6 @@ def dredge_online_lfp(
         bin_s=1 / fs,  # only relevant for time_horizon_s
     )
 
-    
     # here we check that contact positons are unique on the direction
     if contact_depth.size != np.unique(contact_depth).size:
         raise ValueError(
@@ -599,9 +588,7 @@ def dredge_online_lfp(
     # below, t0 is start of prev chunk, t1 start of cur chunk, t2 end of cur
     t0, t1 = 0, T_chunk
     traces0 = lfp_recording.get_traces(start_frame=t0, end_frame=t1)
-    Ds0, Cs0, max_disp_um = xcorr_windows(
-        traces0.T, windows, contact_depth, win_scale_um, **full_xcorr_kw
-    )
+    Ds0, Cs0, max_disp_um = xcorr_windows(traces0.T, windows, contact_depth, win_scale_um, **full_xcorr_kw)
     full_xcorr_kw["max_disp_um"] = max_disp_um
     Ss0, mincorr0 = threshold_correlation_matrix(
         Cs0,
@@ -646,19 +633,14 @@ def dredge_online_lfp(
         )
 
         # cross-correlation in current chunk
-        Ds1, Cs1, _ = xcorr_windows(
-            traces1.T, windows, contact_depth, win_scale_um, **full_xcorr_kw
-        )
+        Ds1, Cs1, _ = xcorr_windows(traces1.T, windows, contact_depth, win_scale_um, **full_xcorr_kw)
         Ss1, mincorr1 = threshold_correlation_matrix(
             Cs1,
             mincorr_percentile=mincorr_percentile,
             mincorr=mincorr,
             **threshold_kw,
         )
-        Ss10, _ = threshold_correlation_matrix(
-            Cs10, mincorr=mincorr1, t_offset_bins=T_chunk, **threshold_kw
-        )
-        
+        Ss10, _ = threshold_correlation_matrix(Cs10, mincorr=mincorr1, t_offset_bins=T_chunk, **threshold_kw)
 
         if extra_outputs:
             extra["mincorrs"].append(mincorr1)
@@ -692,7 +674,8 @@ def dredge_online_lfp(
     else:
         return motion
 
-dredge_online_lfp.__doc__  = dredge_online_lfp.__doc__.format(DredgeLfpRegistration.params_doc)
+
+dredge_online_lfp.__doc__ = dredge_online_lfp.__doc__.format(DredgeLfpRegistration.params_doc)
 
 
 # -- functions from dredgelib (zone forbiden for sam)
@@ -721,7 +704,6 @@ def laplacian(n, wink=True, eps=DEFAULT_EPS, lambd=1.0, ridge_mask=None):
     return lap
 
 
-
 def neg_hessian_likelihood_term(Ub, Ub_prevcur=None, Ub_curprev=None):
     """Newton step coefficients
 
@@ -761,12 +743,7 @@ def newton_rhs(
 
     # online case
     align_term = (Ub_prevcur.T + Ub_curprev) @ Pb_prev
-    rhs = (
-        align_term
-        + grad_at_0
-        + (Ub_curprev * Db_curprev).sum(1)
-        - (Ub_prevcur * Db_prevcur).sum(0)
-    )
+    rhs = align_term + grad_at_0 + (Ub_curprev * Db_curprev).sum(1) - (Ub_prevcur * Db_prevcur).sum(0)
 
     return rhs
 
@@ -881,9 +858,7 @@ def thomas_solve(
         P = np.zeros((B, T))
         extra["HU"] = np.zeros((B, T, T))
         for b in range(B):
-            P[b], extra["HU"][b] = newton_solve_rigid(
-                Ds[b], Us[b], L_t[b], **online_kw_rhs(b)
-            )
+            P[b], extra["HU"][b] = newton_solve_rigid(Ds[b], Us[b], L_t[b], **online_kw_rhs(b))
         return P, extra
 
     # spatial prior is a sparse, block tridiagonal kronecker product
@@ -893,31 +868,21 @@ def thomas_solve(
     Lambda_s_offdiag = laplacian(T, eps=0, lambd=-lambda_s / 2)
 
     # initialize block-LU stuff and forward variable
-    alpha_hat_b = (
-        L_t[0]
-        + Lambda_s_diagb
-        + neg_hessian_likelihood_term(Us[0], **online_kw_hess(0))
-    )
-    targets = np.c_[
-        Lambda_s_offdiag, newton_rhs(Us[0], Ds[0], **online_kw_rhs(0))
-    ]
+    alpha_hat_b = L_t[0] + Lambda_s_diagb + neg_hessian_likelihood_term(Us[0], **online_kw_hess(0))
+    targets = np.c_[Lambda_s_offdiag, newton_rhs(Us[0], Ds[0], **online_kw_rhs(0))]
     res = solve(alpha_hat_b, targets, assume_a="pos")
     assert res.shape == (T, T + 1)
     gamma_hats = [res[:, :T]]
     ys = [res[:, T]]
 
     # forward pass
-    for b in (trange(1, B, desc="Solve") if progress_bar else range(1, B)):
+    for b in trange(1, B, desc="Solve") if progress_bar else range(1, B):
         if b < B - 1:
             Lambda_s_diagb = laplacian(T, eps=eps, lambd=lambda_s, ridge_mask=had_weights[b])
         else:
             Lambda_s_diagb = laplacian(T, eps=eps, lambd=lambda_s / 2, ridge_mask=had_weights[b])
 
-        Ab = (
-            L_t[b]
-            + Lambda_s_diagb
-            + neg_hessian_likelihood_term(Us[b], **online_kw_hess(b))
-        )
+        Ab = L_t[b] + Lambda_s_diagb + neg_hessian_likelihood_term(Us[b], **online_kw_hess(b))
         alpha_hat_b = Ab - Lambda_s_offdiag @ gamma_hats[b - 1]
         targets[:, T] = newton_rhs(Us[b], Ds[b], **online_kw_rhs(b))
         targets[:, T] -= Lambda_s_offdiag @ ys[b - 1]
@@ -938,7 +903,6 @@ def thomas_solve(
     return P, extra
 
 
-
 def threshold_correlation_matrix(
     Cs,
     mincorr=0.0,
@@ -952,10 +916,7 @@ def threshold_correlation_matrix(
     soft=True,
 ):
     if mincorr_percentile is not None:
-        diags = [
-            np.diagonal(Cs, offset=j, axis1=1, axis2=2).ravel()
-            for j in range(1, mincorr_percentile_nneighbs)
-        ]
+        diags = [np.diagonal(Cs, offset=j, axis1=1, axis2=2).ravel() for j in range(1, mincorr_percentile_nneighbs)]
         mincorr = np.percentile(
             np.concatenate(diags),
             mincorr_percentile,
@@ -974,12 +935,7 @@ def threshold_correlation_matrix(
             Ss = np.square((Cs >= mincorr) * Cs)
         else:
             Ss = (Cs >= mincorr).astype(Cs.dtype)
-    if (
-        time_horizon_s is not None
-        and time_horizon_s > 0
-        and T is not None
-        and time_horizon_s < T
-    ):
+    if time_horizon_s is not None and time_horizon_s > 0 and T is not None and time_horizon_s < T:
         tt0 = bin_s * np.arange(T)
         tt1 = tt0
         if t_offset_bins:
@@ -1136,11 +1092,7 @@ def calc_corr_decent_pair(
 
     # pick torch device if unset
     if device is None:
-        device = (
-            torch.device("cuda")
-            if torch.cuda.is_available()
-            else torch.device("cpu")
-        )
+        device = torch.device("cuda") if torch.cuda.is_available() else torch.device("cpu")
 
     # process rasters into the tensors we need for conv2ds below
     # convert to TxD device floats
@@ -1152,9 +1104,7 @@ def calc_corr_decent_pair(
     C = np.zeros((Ta, Tb), dtype=np.float32)
     for i in range(0, Ta, batch_size):
         for j in range(0, Tb, batch_size):
-            dt_bins = min(
-                abs(i - j), abs(i + batch_size - j), abs(i - j - batch_size)
-            )
+            dt_bins = min(abs(i - j), abs(i + batch_size - j), abs(i - j - batch_size))
             if max_dt_bins and dt_bins > max_dt_bins:
                 continue
             weights_ = weights
@@ -1186,53 +1136,52 @@ def normxcorr1d(
     normalized=True,
     padding="same",
     conv_engine="torch",
-
 ):
     """normxcorr1d: Normalized cross-correlation, optionally weighted
 
-    The API is like torch's F.conv1d, except I have accidentally
-    changed the position of input/weights -- template acts like weights,
-    and x acts like input.
-
-    Returns the cross-correlation of `template` and `x` at spatial lags
-    determined by `mode`. Useful for estimating the location of `template`
-    within `x`.
-
-    This might not be the most efficient implementation -- ideas welcome.
-    It uses a direct convolutional translation of the formula
-        corr = (E[XY] - EX EY) / sqrt(var X * var Y)
-
-    This also supports weights! In that case, the usual adaptation of
-    the above formula is made to the weighted case -- and all of the
-    normalizations are done per block in the same way.
-
-    Arguments
-    ---------
-    template : tensor, shape (num_templates, length)
-        The reference template signal
-    x : tensor, 1d shape (length,) or 2d shape (num_inputs, length)
-        The signal in which to find `template`
-    weights : tensor, shape (length,)
-        Will use weighted means, variances, covariances if supplied.
-    centered : bool
-        If true, means will be subtracted (per weighted patch).
-    normalized : bool
-        If true, normalize by the variance (per weighted patch).
-    padding : int, optional
-        How far to look? if unset, we'll use half the length
-    conv_engine : "torch" | "numpy"
-        What library to use for computing cross-correlations.
-        If numpy, falls back to the scipy correlate function.
-conv_engine
-    Returns
-    -------
-    corr : tensor
+        The API is like torch's F.conv1d, except I have accidentally
+        changed the position of input/weights -- template acts like weights,
+        and x acts like input.
+
+        Returns the cross-correlation of `template` and `x` at spatial lags
+        determined by `mode`. Useful for estimating the location of `template`
+        within `x`.
+
+        This might not be the most efficient implementation -- ideas welcome.
+        It uses a direct convolutional translation of the formula
+            corr = (E[XY] - EX EY) / sqrt(var X * var Y)
+
+        This also supports weights! In that case, the usual adaptation of
+        the above formula is made to the weighted case -- and all of the
+        normalizations are done per block in the same way.
+
+        Arguments
+        ---------
+        template : tensor, shape (num_templates, length)
+            The reference template signal
+        x : tensor, 1d shape (length,) or 2d shape (num_inputs, length)
+            The signal in which to find `template`
+        weights : tensor, shape (length,)
+            Will use weighted means, variances, covariances if supplied.
+        centered : bool
+            If true, means will be subtracted (per weighted patch).
+        normalized : bool
+            If true, normalize by the variance (per weighted patch).
+        padding : int, optional
+            How far to look? if unset, we'll use half the length
+        conv_engine : "torch" | "numpy"
+            What library to use for computing cross-correlations.
+            If numpy, falls back to the scipy correlate function.
+    conv_engine
+        Returns
+        -------
+        corr : tensor
     """
 
-
     if conv_engine == "torch":
         import torch
         import torch.nn.functional as F
+
         conv1d = F.conv1d
         npx = torch
     elif conv_engine == "numpy":
@@ -1297,9 +1246,7 @@ def normxcorr1d(
 
     # compute variances for denominator, using var X = E[X^2] - (EX)^2
     if normalized:
-        var_template = conv1d(
-            onesx, wt * template, padding=padding
-        )
+        var_template = conv1d(onesx, wt * template, padding=padding)
         var_template /= Nx
         var_x = conv1d(wx * x, weights, padding=padding)
         var_x /= Nx
@@ -1354,20 +1301,12 @@ def get_weights(
     if isinstance(weights_threshold_low, tuple):
         nspikes_threshold_low, amp_threshold_low = weights_threshold_low
         unif = np.full_like(windows[0], 1 / len(windows[0]))
-        weights_threshold_low = (
-            scale_fn(amp_threshold_low)
-            * windows
-            @ (nspikes_threshold_low * unif)
-        )
+        weights_threshold_low = scale_fn(amp_threshold_low) * windows @ (nspikes_threshold_low * unif)
         weights_threshold_low = weights_threshold_low[:, None]
     if isinstance(weights_threshold_high, tuple):
         nspikes_threshold_high, amp_threshold_high = weights_threshold_high
         unif = np.full_like(windows[0], 1 / len(windows[0]))
-        weights_threshold_high = (
-            scale_fn(amp_threshold_high)
-            * windows
-            @ (nspikes_threshold_high * unif)
-        )
+        weights_threshold_high = scale_fn(amp_threshold_high) * windows @ (nspikes_threshold_high * unif)
         weights_threshold_high = weights_threshold_high[:, None]
     weights_thresh = weights_orig.copy()
     weights_thresh[weights_orig < weights_threshold_low] = 0
@@ -1375,6 +1314,7 @@ def get_weights(
 
     return weights, weights_thresh, p_inds
 
+
 def weight_correlation_matrix(
     Ds,
     Cs,
@@ -1436,7 +1376,7 @@ def weight_correlation_matrix(
         raster,
         depth_bin_edges,
         time_bin_edges,
-        #raster_kw,
+        # raster_kw,
         post_transform=post_transform,
         weights_threshold_low=weights_threshold_low,
         weights_threshold_high=weights_threshold_high,
diff --git a/src/spikeinterface/sortingcomponents/motion/iterative_template.py b/src/spikeinterface/sortingcomponents/motion/iterative_template.py
index a49d5bd639..f5e2e30d4a 100644
--- a/src/spikeinterface/sortingcomponents/motion/iterative_template.py
+++ b/src/spikeinterface/sortingcomponents/motion/iterative_template.py
@@ -96,8 +96,6 @@ def run(
             zero_threshold=None,
         )
 
-
-
         # make a 3D histogram
         motion_histograms, temporal_hist_bin_edges, spatial_hist_bin_edges = make_3d_motion_histograms(
             recording,
@@ -143,7 +141,6 @@ def run(
         return motion
 
 
-
 def iterative_template_registration(
     spikecounts_hist_images,
     non_rigid_windows=None,
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py b/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py
index de2c7df4cc..2ac20ad46d 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py
@@ -2,6 +2,7 @@
 
 # TODO this need a full rewrite with motion object
 
+
 def clean_motion_vector(motion, temporal_bins, bin_duration_s, speed_threshold=30, sigma_smooth_s=None):
     """
     Simple machinery to remove spurious fast bump in the motion vector.
@@ -69,5 +70,3 @@ def clean_motion_vector(motion, temporal_bins, bin_duration_s, speed_threshold=3
         motion_clean = scipy.signal.fftconvolve(motion_clean, smooth_kernel, mode="same", axes=0)
 
     return motion_clean
-
-
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
index f7f4f4ad66..2d8564fc54 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_estimation.py
@@ -4,7 +4,6 @@
 import numpy as np
 
 
-
 from spikeinterface.sortingcomponents.tools import make_multi_method_doc
 
 
@@ -22,8 +21,8 @@ def estimate_motion(
     direction="y",
     rigid=False,
     win_shape="gaussian",
-    win_step_um=50.0, # @alessio charlie is proposing here instead 400
-    win_scale_um=150.0, # @alessio charlie is proposing here instead 400
+    win_step_um=50.0,  # @alessio charlie is proposing here instead 400
+    win_scale_um=150.0,  # @alessio charlie is proposing here instead 400
     win_margin_um=None,
     method="decentralized",
     extra_outputs=False,
@@ -33,8 +32,8 @@ def estimate_motion(
     **method_kwargs,
 ):
     """
-    
-    
+
+
     Estimate motion with several possible methods.
 
     Most of methods except dredge_lfp needs peaks and after their localization.
@@ -98,7 +97,6 @@ def estimate_motion(
     if margin_um is not None:
         warnings.warn("estimate_motion() margin_um has been removed used hist_margin_um or win_margin_um")
 
-
     # TODO handle multi segment one day : Charlie this is for you
     assert recording.get_num_segments() == 1, "At the moment estimate_motion handle only unique segment"
 
@@ -119,13 +117,11 @@ def estimate_motion(
         peaks,
         peak_locations,
         direction,
-
         rigid,
         win_shape,
         win_step_um,
         win_scale_um,
         win_margin_um,
-
         verbose,
         progress_bar,
         extra,
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index 228110b7ec..a848ca1746 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -229,22 +229,21 @@ def copy(self):
             [d.copy() for d in self.displacement],
             [t.copy() for t in self.temporal_bins_s],
             self.spatial_bins_um.copy(),
-            direction=self.direction,    
+            direction=self.direction,
             interpolation_method=self.interpolation_method,
         )
 
 
-
 def get_spatial_windows(
-        contact_depth,
-        spatial_bin_centers,
-        rigid=False,
-        win_shape="gaussian",
-        win_step_um=50.0,
-        win_scale_um=150.0,
-        win_margin_um=None,
-        zero_threshold=None
-    ):
+    contact_depth,
+    spatial_bin_centers,
+    rigid=False,
+    win_shape="gaussian",
+    win_step_um=50.0,
+    win_scale_um=150.0,
+    win_margin_um=None,
+    zero_threshold=None,
+):
     """
     Generate spatial windows (taper) for non-rigid motion.
     For rigid motion, this is equivalent to have one unique rectangular window that covers the entire probe.
@@ -297,14 +296,14 @@ def get_spatial_windows(
         middle = (spatial_bin_centers[0] + spatial_bin_centers[-1]) / 2.0
         window_centers = np.array([middle])
     else:
-        if win_scale_um <= win_step_um/5.:
+        if win_scale_um <= win_step_um / 5.0:
             warnings.warn(
                 f"get_spatial_windows(): spatial windows are probably not overlaping because {win_scale_um=} and {win_step_um=}"
             )
 
         if win_margin_um is None:
             # this ensure that first/last windows do not overflow outside the probe
-            win_margin_um = -win_scale_um / 2.
+            win_margin_um = -win_scale_um / 2.0
 
         min_ = np.min(contact_depth) - win_margin_um
         max_ = np.max(contact_depth) + win_margin_um
@@ -388,7 +387,6 @@ def get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um):
     return spatial_bins
 
 
-
 def make_2d_motion_histogram(
     recording,
     peaks,
@@ -465,7 +463,7 @@ def make_2d_motion_histogram(
         weights = None
 
     motion_histogram, edges = np.histogramdd(arr, bins=(temporal_bin_edges, spatial_bin_edges), weights=weights)
-    
+
     # average amplitude in each bin
     if weight_with_amplitude and avg_in_bin:
         bin_counts, _ = np.histogramdd(arr, bins=(temporal_bin_edges, spatial_bin_edges))
diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_drege.py b/src/spikeinterface/sortingcomponents/motion/tests/test_drege.py
index 218d9036aa..8133c1fa6b 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_drege.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_drege.py
@@ -1,8 +1,6 @@
 import pytest
 
 
-
-
 def test_dredge_online_lfp():
     pass
 
diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
index 1168b65c79..3c83a56b9d 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_estimation.py
@@ -57,7 +57,7 @@ def dataset_fixture(create_cache_folder):
 def test_estimate_motion(dataset):
     # recording, sorting = make_dataset()
     recording, sorting, cache_folder = dataset
-    
+
     peaks = np.load(cache_folder / "dataset_peaks.npy")
     peak_locations = np.load(cache_folder / "dataset_peak_locations.npy")
 
@@ -222,6 +222,7 @@ def test_estimate_motion(dataset):
 
 if __name__ == "__main__":
     import tempfile
+
     with tempfile.TemporaryDirectory() as tmpdirname:
         cache_folder = Path(tmpdirname)
     args = setup_dataset_and_peaks(cache_folder)

From de7df4b26c0847d4e7f5d1e70a48ed64fdd24c05 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 12 Jul 2024 10:21:46 +0200
Subject: [PATCH 22/31] Fix tests

---
 src/spikeinterface/core/core_tools.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/core_tools.py b/src/spikeinterface/core/core_tools.py
index 996718dc42..42d5561547 100644
--- a/src/spikeinterface/core/core_tools.py
+++ b/src/spikeinterface/core/core_tools.py
@@ -75,7 +75,7 @@ class SIJsonEncoder(json.JSONEncoder):
 
     def default(self, obj):
         from spikeinterface.core.base import BaseExtractor
-        from spikeinterface.sortingcomponents.motion_utils import Motion
+        from spikeinterface.sortingcomponents.motion.motion_utils import Motion
 
         # Over-write behaviors for datetime object
         if isinstance(obj, datetime.datetime):

From 261b021bee08d8228754cfe0aee2347e8fa4f2e3 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 12 Jul 2024 11:36:02 +0200
Subject: [PATCH 23/31] Cleanup how to

---
 doc/how_to/drift_with_lfp.rst     | 102 ++++++++++++------------------
 examples/how_to/drift_with_lfp.py |  56 ++++++++--------
 2 files changed, 68 insertions(+), 90 deletions(-)

diff --git a/doc/how_to/drift_with_lfp.rst b/doc/how_to/drift_with_lfp.rst
index a215f0920f..0decc1058a 100644
--- a/doc/how_to/drift_with_lfp.rst
+++ b/doc/how_to/drift_with_lfp.rst
@@ -1,30 +1,27 @@
 Estimate drift using the LFP traces
 ===================================
 
-Charlie Windolf and colleagues have developed a method to estimate the
-motion using the LFP signal : **dredge**.
+Drift is a well known issue for long shank probes. Some datasets, especially from primates and humans,
+can experience very fast motion due to breathing and heart beats. In these cases, the standard motion
+estimation methods that use detected spikes as a basis for motion inference will fail, because there
+are not enough spikes to "follow" such fast drifts.
 
-You can see more detail in this preprint `DREDge: robust motion
-correction for high-density extracellular recordings across
-species <https://www.biorxiv.org/content/10.1101/2023.10.24.563768v1>`__
+Charlie Windolf and colleagues from the Paninski Lab at Columbia have developed a method to estimate
+the motion using the LFP signal: **DREDge**. (more details about the method in the paper
+`DREDge: robust motion correction for high-density extracellular recordings across species <https://doi.org/10.1101/2023.10.24.563768>`_).
 
-This method is particularly adapated for the open dataset recorded at
-Massachusetts General Hospital by Angelique Paulk and colleagues. The
-dataset can be dowloaed `on
-datadryad <https://datadryad.org/stash/dataset/doi:10.5061/dryad.d2547d840>`__.
-This challenging dataset contain recording on patient with neuropixel
-probe! But a very high and very fast motion on the probe prevent doing
-spike sorting.
+This method is particularly suited for the open dataset recorded at Massachusetts General Hospital by Angelique Paulk and colleagues in humans (more details in the [paper](https://doi.org/10.1038/s41593-021-00997-0)). The dataset can be dowloaed from [datadryad](https://datadryad.org/stash/dataset/doi:10.5061/dryad.d2547d840) and it contains recordings on human patients with a Neuropixels probe, some of which with very high and fast motion on the probe, which prevents accurate spike sorting without a proper and adequate motion correction
 
-The **dredge** method has two sides **dredge_lfp** and **dredge_ap**.
-They both haave been ported inside spikeinterface. Here we will use the
-**dredge_lfp**.
+The **DREDge** method has two options: **dredge_lfp** and **dredge_ap**, which have both been ported inside `SpikeInterface`.
 
-Here we demonstrate how to use this method to estimate the fast and high
-drift on this recording.
+Here we will demonstrate the **dredge_lfp** method to estimate the fast and high drift on this recording.
 
-For each patient, the dataset contains two recording : a high pass (AP -
-30kHz) and a low pass (FP - 2.5kHz). We will use the low pass here.
+For each patient, the dataset contains two streams:
+
+* a highpass "action potential" (AP), sampled at 30kHz
+* a lowpass "local field" (LF) sampled at 2.5kHz
+
+For this demonstration, we will use the LF stream.
 
 .. code:: ipython3
 
@@ -46,7 +43,7 @@ For each patient, the dataset contains two recording : a high pass (AP -
     base_folder = Path("/mnt/data/sam/DataSpikeSorting/")
     np_data_drift = base_folder / 'human_neuropixel/Pt02/'
 
-read the spikeglx file
+Read the spikeglx file
 ~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: ipython3
@@ -61,25 +58,20 @@ read the spikeglx file
                                 873.32s (14.56 minutes) - int16 dtype - 1.56 GiB
 
 
-preprocessing
+Preprocessing
 ~~~~~~~~~~~~~
 
-Contrary to **dredge_ap** which need peak and peak location, the
-**dredge_lfp** is estimating the motion directly on traces but the
-method need an important preprocessing: \* low pass filter : this focus
-the signal on a particular band \* phase_shift : this is needed to
-conpensate the digitalization unalignement \* resample : the sample
-fequency of the signal will be the sample frequency of the estimated
-motion. Here we choose 250Hz to have 4ms precission. \*
-directional_derivative : this optional step apply a derivative at second
-order to enhance edges on the traces. This is not a general rules and
-need to be tested case by case. \* average_across_direction : neuropixel
-1 probe has several contact per depth. They are average to get a unique
-virtual signal along the probe depth (“y” in probeinterface and
-spikeinterface).
-
-When appying this preprocessing the motion can be estimated almost by
-eyes ont the traces plotted with the map mode.
+Contrary to the **dredge_ap** approach, which needs detected peaks and peak locations, the **dredge_lfp**
+method is estimating the motion directly on traces.
+Importantly, the method requires some additional pre-processing steps:
+  * ``bandpass_filter``: to "focus" the signal on a particular band
+  * ``phase_shift``: to compensate for the sampling misalignement
+  * ``resample``: to further reduce the sampling fequency of the signal and speed up the computation. The sampling frequency of the estimated motion will be the same as the resampling frequency. Here we choose 250Hz, which corresponds to a sampling interval of 4ms.
+  * ``directional_derivative``: this optional step applies a second order derivative in the spatial dimension to enhance edges on the traces.
+    This is not a general rules and need to be tested case by case.
+  * ``average_across_direction``: Neuropixels 1.0 probes have two contacts per depth. This steps averages them to obtain a unique virtual signal along the probe depth ("y" in ``spikeinterface``).
+
+After appying this preprocessing chain, the motion can be estimated almost by eyes ont the traces plotted with the map mode.
 
 .. code:: ipython3
 
@@ -115,28 +107,20 @@ eyes ont the traces plotted with the map mode.
 
 
 
-
-.. parsed-literal::
-
-    <spikeinterface.widgets.traces.TracesWidget at 0x75bc74d0af90>
-
-
-
-
 .. image:: drift_with_lfp_files/drift_with_lfp_8_1.png
 
 
 Run the method
 ~~~~~~~~~~~~~~
 
-``estimate_motion()`` is the generic funciton with multi method in
-spikeinterface.
+``estimate_motion()`` is the generic function to estimate motion with multiple
+methods in ``spikeinterface``.
 
-This return a ``Motion`` object, you can note that the interval is
-exactly the same as downsampled signal.
+This function returns a ``Motion`` object and we can notice that the interval is exactly
+the same as downsampled signal.
 
-Here we use ``rigid=True``, this means that we have one unqiue signal to
-describe the motion for the entire probe.
+Here we use ``rigid=True``, which means that we have one unqiue signal to
+describe the motion across the entire probe depth.
 
 .. code:: ipython3
 
@@ -144,27 +128,24 @@ describe the motion for the entire probe.
     motion
 
 
-
 .. parsed-literal::
 
     Online chunks [10.0s each]:   0%|          | 0/87 [00:00<?, ?it/s]
 
 
-
-
 .. parsed-literal::
 
     Motion rigid - interval 0.004s - 1 segments
 
 
 
-plot the drift
+Plot the drift
 ~~~~~~~~~~~~~~
 
-When plotting the drift, we can notice a very fast drift which
-corresponf to the heart rate.
+When plotting the drift, we can notice a very fast drift which corresponds to the heart rate.
+The slower oscillations can be attributed to the breathing signal.
 
-This motion match the LFP signal above.
+We can appreciate how the estimated motion signal matches the processed LFP traces plotted above.
 
 .. code:: ipython3
 
@@ -174,14 +155,9 @@ This motion match the LFP signal above.
     ax.set_ylim(800, 1300)
 
 
-
-
-
 .. parsed-literal::
 
     (800.0, 1300.0)
 
 
-
-
 .. image:: drift_with_lfp_files/drift_with_lfp_12_1.png
diff --git a/examples/how_to/drift_with_lfp.py b/examples/how_to/drift_with_lfp.py
index df656bc4ae..66a31bd6f2 100644
--- a/examples/how_to/drift_with_lfp.py
+++ b/examples/how_to/drift_with_lfp.py
@@ -16,19 +16,22 @@
 
 # # Estimate drift using the LFP traces
 #
-# Charlie Windolf and colleagues have developed a method to estimate the motion using the LFP signal : **dredge**.
+# Drift is a well known issue for long shank probes. Some datasets, especially from primates and humans, can experience very fast motion due to breathing and heart beats. In these cases, the standard motion estimation methods that use detected spikes as a basis for motion inference will fail, because there are not enough spikes to "follow" such fast drifts.
 #
-# You can see more detail in this preprint [DREDge: robust motion correction for high-density extracellular recordings across species](https://www.biorxiv.org/content/10.1101/2023.10.24.563768v1)
+# Charlie Windolf and colleagues from the Paninski Lab at Columbia have developed a method to estimate the motion using the LFP signal: **DREDge**. (more details about the method in the paper [DREDge: robust motion correction for high-density extracellular recordings across species](https://doi.org/10.1101/2023.10.24.563768)).
 #
-# This method is particularly adapated for the open dataset recorded at Massachusetts General Hospital by Angelique Paulk and colleagues. The dataset can be dowloaed [on datadryad](https://datadryad.org/stash/dataset/doi:10.5061/dryad.d2547d840).
-# This challenging dataset contain recording on patient with neuropixel probe! But a very high and very fast motion on the probe prevent doing spike sorting.
+# This method is particularly suited for the open dataset recorded at Massachusetts General Hospital by Angelique Paulk and colleagues in humans (more details in the [paper](https://doi.org/10.1038/s41593-021-00997-0)). The dataset can be dowloaed from [datadryad](https://datadryad.org/stash/dataset/doi:10.5061/dryad.d2547d840) and it contains recordings on human patients with a Neuropixels probe, some of which with very high and fast motion on the probe, which prevents accurate spike sorting without a proper and adequate motion correction
 #
-# The **dredge** method has two sides **dredge_lfp** and **dredge_ap**. They both haave been ported inside spikeinterface. Here we will use the **dredge_lfp**.
+# The **DREDge** method has two options: **dredge_lfp** and **dredge_ap**, which have both been ported inside `SpikeInterface`.
 #
-# Here we demonstrate how to use this method to estimate the fast and high drift on this recording.
+# Here we will demonstrate the **dredge_lfp** method to estimate the fast and high drift on this recording.
 #
-# For each patient, the dataset contains two recording : a high pass (AP - 30kHz) and a low pass (FP - 2.5kHz).
-# We will use the low pass here.
+# For each patient, the dataset contains two streams:
+#
+# * a highpass "action potential" (AP), sampled at 30kHz
+# * a lowpass "local field" (LF) sampled at 2.5kHz
+#
+# For this demonstration, we will use the LF stream.
 
 # %matplotlib inline
 # %load_ext autoreload
@@ -42,33 +45,33 @@
 from spikeinterface.sortingcomponents.motion import estimate_motion
 # -
 
-# the dataset has been locally downloaded
+# the dataset has been downloaded locally
 base_folder = Path("/mnt/data/sam/DataSpikeSorting/")
-np_data_drift = base_folder / 'human_neuropixel/Pt02/'
+np_data_drift = base_folder / 'human_neuropixel" / "Pt02"
 
-# ### read the spikeglx file
+# ### Read the spikeglx file
 
 raw_rec = si.read_spikeglx(np_data_drift)
 print(raw_rec)
 
-# ### preprocessing
+# ### Preprocessing
 #
-# Contrary to **dredge_ap** which need peak and peak location, the **dredge_lfp** is estimating the motion directly on traces but the method need an important preprocessing:
-#   * low pass filter  : this focus the signal on a particular band
-#   * phase_shift : this is needed to conpensate the digitalization unalignement
-#   * resample : the sample fequency of the signal will be the sample frequency of the estimated motion. Here we choose      250Hz to have 4ms precission.
-#   * directional_derivative : this optional step apply a derivative at second order to enhance edges on the traces.
+# Contrary to the **dredge_ap** approach, which needs detected peaks and peak locations, the **dredge_lfp** method is estimating the motion directly on traces.
+# Importantly, the method requires some additional pre-processing steps:
+#   * `bandpass_filter`: to "focus" the signal on a particular band
+#   * `phase_shift`: to compensate for the sampling misalignement
+#   * `resample`: to further reduce the sampling fequency of the signal and speed up the computation. The sampling frequency of the estimated motion will be the same as the resampling frequency. Here we choose 250Hz, which corresponds to a sampling interval of 4ms.
+#   * `directional_derivative`: this optional step applies a second order derivative in the spatial dimension to enhance edges on the traces.
 #     This is not a general rules and need to be tested case by case.
-#   * average_across_direction : neuropixel 1 probe has several contact per depth. They are average to get a unique          virtual signal along the probe depth ("y" in probeinterface and spikeinterface).
+#   * `average_across_direction`: Neuropixels 1.0 probes have two contacts per depth. This steps averages them to obtain a unique virtual signal along the probe depth ("y" in `spikeinterface`).
 #
-# When appying this preprocessing the motion can be estimated almost by eyes ont the traces plotted with the map mode.
+# After appying this preprocessing chain, the motion can be estimated almost by eyes ont the traces plotted with the map mode.
 
 # +
 lfprec = si.bandpass_filter(
     raw_rec,
     freq_min=0.5,
     freq_max=250,
-
     margin_ms=1500.,
     filter_order=3,
     dtype="float32",
@@ -88,21 +91,20 @@
 
 # ### Run the method
 #
-# `estimate_motion()` is the generic funciton with multi method in spikeinterface.
+# `estimate_motion()` is the generic function to estimate motion with multiple methods in `spikeinterface`.
 #
-# This return a `Motion` object, you can note that the interval is exactly the same as downsampled signal.
+# This function returns a `Motion` object and we can notice that the interval is exactly the same as downsampled signal.
 #
-# Here we use `rigid=True`, this means that we have one unqiue signal to describe the motion for the entire probe.
+# Here we use `rigid=True`, which means that we have one unqiue signal to describe the motion across the entire probe depth.
 
 motion = estimate_motion(lfprec, method='dredge_lfp', rigid=True, progress_bar=True)
 motion
 
-# ### plot the drift
-#
-# When plotting the drift, we can notice a very fast drift which corresponf to the heart rate.
+# ### Plot the drift
 #
-# This motion match the LFP signal above.
+# When plotting the drift, we can notice a very fast drift which corresponds to the heart rate. The slower oscillations can be attributed to the breathing signal.
 #
+# We can appreciate how the estimated motion signal matches the processed LFP traces plotted above.
 
 fig, ax = plt.subplots()
 si.plot_motion(motion, mode='line', ax=ax)

From 41d3903c9bed02849f5bb14a17caeb8c065669d7 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 12 Jul 2024 12:00:37 +0200
Subject: [PATCH 24/31] Handle negative/0 windows,
 contact_depth->contact_depths, add verbosity to iterative_template

---
 src/spikeinterface/preprocessing/motion.py    |  1 +
 .../preprocessing/tests/test_motion.py        |  2 +-
 .../sortingcomponents/motion/decentralized.py |  4 +-
 .../sortingcomponents/motion/dredge.py        | 22 +++---
 .../motion/iterative_template.py              |  8 +-
 .../sortingcomponents/motion/motion_utils.py  | 79 ++++++++++++-------
 6 files changed, 70 insertions(+), 46 deletions(-)

diff --git a/src/spikeinterface/preprocessing/motion.py b/src/spikeinterface/preprocessing/motion.py
index 0568650316..5e91623257 100644
--- a/src/spikeinterface/preprocessing/motion.py
+++ b/src/spikeinterface/preprocessing/motion.py
@@ -99,6 +99,7 @@
             win_shape="gaussian",
             win_step_um=100.0,
             win_scale_um=200.0,
+            win_margin_um=None,
             histogram_depth_smooth_um=5.0,
             histogram_time_smooth_s=None,
             pairwise_displacement_method="conv",
diff --git a/src/spikeinterface/preprocessing/tests/test_motion.py b/src/spikeinterface/preprocessing/tests/test_motion.py
index baa7235263..02efef1e3b 100644
--- a/src/spikeinterface/preprocessing/tests/test_motion.py
+++ b/src/spikeinterface/preprocessing/tests/test_motion.py
@@ -13,7 +13,7 @@ def test_estimate_and_correct_motion(create_cache_folder):
     if folder.exists():
         shutil.rmtree(folder)
 
-    rec_corrected = correct_motion(rec, folder=folder)
+    rec_corrected = correct_motion(rec, folder=folder, estimate_motion_kwargs={"win_step_um": 20})
     print(rec_corrected)
 
     # test reloading motion info
diff --git a/src/spikeinterface/sortingcomponents/motion/decentralized.py b/src/spikeinterface/sortingcomponents/motion/decentralized.py
index d054995839..32f60f568f 100644
--- a/src/spikeinterface/sortingcomponents/motion/decentralized.py
+++ b/src/spikeinterface/sortingcomponents/motion/decentralized.py
@@ -137,7 +137,7 @@ def run(
     ):
 
         dim = ["x", "y", "z"].index(direction)
-        contact_depth = recording.get_channel_locations()[:, dim]
+        contact_depths = recording.get_channel_locations()[:, dim]
 
         # spatial histogram bins
         spatial_bin_edges = get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um)
@@ -145,7 +145,7 @@ def run(
 
         # get spatial windows
         non_rigid_windows, non_rigid_window_centers = get_spatial_windows(
-            contact_depth,
+            contact_depths,
             spatial_bin_centers,
             rigid=rigid,
             win_shape=win_shape,
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 3eb83dfbaa..7c3b2e4c5a 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -299,11 +299,11 @@ def dredge_ap(
     # )
 
     dim = ["x", "y", "z"].index(direction)
-    contact_depth = recording.get_channel_locations()[:, dim]
+    contact_depths = recording.get_channel_locations()[:, dim]
     spatial_bin_centers = 0.5 * (spatial_bin_edges_um[1:] + spatial_bin_edges_um[:-1])
 
     windows, window_centers = get_spatial_windows(
-        contact_depth,
+        contact_depths,
         spatial_bin_centers,
         rigid=rigid,
         win_shape=win_shape,
@@ -526,7 +526,7 @@ def dredge_online_lfp(
     """
     dim = ["x", "y", "z"].index(direction)
     # contact pos is the only on the direction
-    contact_depth = lfp_recording.get_channel_locations()[:, dim]
+    contact_depths = lfp_recording.get_channel_locations()[:, dim]
 
     fs = lfp_recording.get_sampling_frequency()
     T_total = lfp_recording.get_num_samples()
@@ -538,7 +538,7 @@ def dredge_online_lfp(
     thomas_kw = thomas_kw if thomas_kw is not None else {}
     full_xcorr_kw = dict(
         rigid=rigid,
-        bin_um=np.median(np.diff(contact_depth)),
+        bin_um=np.median(np.diff(contact_depths)),
         max_disp_um=max_disp_um,
         progress_bar=False,
         device=device,
@@ -554,21 +554,21 @@ def dredge_online_lfp(
     )
 
     # here we check that contact positons are unique on the direction
-    if contact_depth.size != np.unique(contact_depth).size:
+    if contact_depths.size != np.unique(contact_depths).size:
         raise ValueError(
             f"estimate motion with 'dredge_lfp' need channel_positions to be unique in the direction='{direction}'"
         )
-    if np.any(np.diff(contact_depth) < 0):
+    if np.any(np.diff(contact_depths) < 0):
         raise ValueError(
             f"estimate motion with 'dredge_lfp' need channel_positions to be ordered direction='{direction}'"
             "please use spikeinterface.preprocessing.depth_order(recording)"
         )
 
     # Important detail : in LFP bin center are contact position in the direction
-    spatial_bin_centers = contact_depth
+    spatial_bin_centers = contact_depths
 
     windows, window_centers = get_spatial_windows(
-        contact_depth=contact_depth,
+        contact_depths=contact_depths,
         spatial_bin_centers=spatial_bin_centers,
         rigid=rigid,
         win_margin_um=win_margin_um,
@@ -588,7 +588,7 @@ def dredge_online_lfp(
     # below, t0 is start of prev chunk, t1 start of cur chunk, t2 end of cur
     t0, t1 = 0, T_chunk
     traces0 = lfp_recording.get_traces(start_frame=t0, end_frame=t1)
-    Ds0, Cs0, max_disp_um = xcorr_windows(traces0.T, windows, contact_depth, win_scale_um, **full_xcorr_kw)
+    Ds0, Cs0, max_disp_um = xcorr_windows(traces0.T, windows, contact_depths, win_scale_um, **full_xcorr_kw)
     full_xcorr_kw["max_disp_um"] = max_disp_um
     Ss0, mincorr0 = threshold_correlation_matrix(
         Cs0,
@@ -626,14 +626,14 @@ def dredge_online_lfp(
         Ds10, Cs10, _ = xcorr_windows(
             traces1.T,
             windows,
-            contact_depth,
+            contact_depths,
             win_scale_um,
             raster_b=traces0.T,
             **full_xcorr_kw,
         )
 
         # cross-correlation in current chunk
-        Ds1, Cs1, _ = xcorr_windows(traces1.T, windows, contact_depth, win_scale_um, **full_xcorr_kw)
+        Ds1, Cs1, _ = xcorr_windows(traces1.T, windows, contact_depths, win_scale_um, **full_xcorr_kw)
         Ss1, mincorr1 = threshold_correlation_matrix(
             Cs1,
             mincorr_percentile=mincorr_percentile,
diff --git a/src/spikeinterface/sortingcomponents/motion/iterative_template.py b/src/spikeinterface/sortingcomponents/motion/iterative_template.py
index f5e2e30d4a..1b5eb75508 100644
--- a/src/spikeinterface/sortingcomponents/motion/iterative_template.py
+++ b/src/spikeinterface/sortingcomponents/motion/iterative_template.py
@@ -78,7 +78,7 @@ def run(
     ):
 
         dim = ["x", "y", "z"].index(direction)
-        contact_depth = recording.get_channel_locations()[:, dim]
+        contact_depths = recording.get_channel_locations()[:, dim]
 
         # spatial histogram bins
         spatial_bin_edges = get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um)
@@ -86,7 +86,7 @@ def run(
 
         # get spatial windows
         non_rigid_windows, non_rigid_window_centers = get_spatial_windows(
-            contact_depth=contact_depth,
+            contact_depths=contact_depths,
             spatial_bin_centers=spatial_bin_centers,
             rigid=rigid,
             win_margin_um=win_margin_um,
@@ -97,6 +97,8 @@ def run(
         )
 
         # make a 3D histogram
+        if verbose:
+            print("Making 3D motion histograms")
         motion_histograms, temporal_hist_bin_edges, spatial_hist_bin_edges = make_3d_motion_histograms(
             recording,
             peaks,
@@ -110,6 +112,8 @@ def run(
         temporal_bins = temporal_hist_bin_edges[:-1] + bin_s // 2.0
 
         # do alignment
+        if verbose:
+            print("Estimating alignment shifts")
         shift_indices, target_histogram, shift_covs_block = iterative_template_registration(
             motion_histograms,
             non_rigid_windows=non_rigid_windows,
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index a848ca1746..d98501d257 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -235,7 +235,7 @@ def copy(self):
 
 
 def get_spatial_windows(
-    contact_depth,
+    contact_depths,
     spatial_bin_centers,
     rigid=False,
     win_shape="gaussian",
@@ -248,13 +248,13 @@ def get_spatial_windows(
     Generate spatial windows (taper) for non-rigid motion.
     For rigid motion, this is equivalent to have one unique rectangular window that covers the entire probe.
     The windowing can be gaussian or rectangular.
-    Windows are centered between the min/max of contact_depth.
+    Windows are centered between the min/max of contact_depths.
     We can ensure window to not be to close from border with win_margin_um.
 
 
     Parameters
     ----------
-    contact_depth : np.ndarray
+    contact_depths : np.ndarray
         Position of electrodes of the corection direction shape=(num_channels, )
     spatial_bin_centers : np.array
         The pre-computed spatial bin centers
@@ -292,9 +292,7 @@ def get_spatial_windows(
 
     if rigid:
         # win_shape = 'rect' is forced
-        windows = [np.ones(n, dtype="float64")]
-        middle = (spatial_bin_centers[0] + spatial_bin_centers[-1]) / 2.0
-        window_centers = np.array([middle])
+        windows, window_centers = get_rigid_windows(spatial_bin_centers)
     else:
         if win_scale_um <= win_step_um / 5.0:
             warnings.warn(
@@ -305,27 +303,41 @@ def get_spatial_windows(
             # this ensure that first/last windows do not overflow outside the probe
             win_margin_um = -win_scale_um / 2.0
 
-        min_ = np.min(contact_depth) - win_margin_um
-        max_ = np.max(contact_depth) + win_margin_um
-        num_windows = int((max_ - min_) // win_step_um)
-        border = ((max_ - min_) % win_step_um) / 2
-        window_centers = np.arange(num_windows + 1) * win_step_um + min_ + border
-        windows = []
-
-        for win_center in window_centers:
-            if win_shape == "gaussian":
-                win = np.exp(-((spatial_bin_centers - win_center) ** 2) / (2 * win_scale_um**2))
-            elif win_shape == "rect":
-                win = np.abs(spatial_bin_centers - win_center) < (win_scale_um / 2.0)
-                win = win.astype("float64")
-            elif win_shape == "triangle":
-                center_dist = np.abs(spatial_bin_centers - win_center)
-                in_window = center_dist <= (win_scale_um / 2.0)
-                win = -center_dist
-                win[~in_window] = 0
-                win[in_window] -= win[in_window].min()
-                win[in_window] /= win[in_window].max()
-            windows.append(win)
+        min_ = np.min(contact_depths) - win_margin_um
+        max_ = np.max(contact_depths) + win_margin_um
+        if min_ >= max_:
+            warnings.warn(
+                f"get_spatial_windows(): win_margin_um is too large for the probe size. " "Using rigid motion."
+            )
+            # if the probe is too small, we use a single window
+            windows, window_centers = get_rigid_windows(spatial_bin_centers)
+        else:
+            num_windows = int((max_ - min_) // win_step_um)
+            if num_windows == 0:
+                warnings.warn(
+                    f"get_spatial_windows(): win_step_um and win_margin_um are too large for the probe size. "
+                    "Using rigid motion."
+                )
+                windows, window_centers = get_rigid_windows(spatial_bin_centers)
+            else:
+                border = ((max_ - min_) % win_step_um) / 2
+                window_centers = np.arange(num_windows + 1) * win_step_um + min_ + border
+                windows = []
+
+                for win_center in window_centers:
+                    if win_shape == "gaussian":
+                        win = np.exp(-((spatial_bin_centers - win_center) ** 2) / (2 * win_scale_um**2))
+                    elif win_shape == "rect":
+                        win = np.abs(spatial_bin_centers - win_center) < (win_scale_um / 2.0)
+                        win = win.astype("float64")
+                    elif win_shape == "triangle":
+                        center_dist = np.abs(spatial_bin_centers - win_center)
+                        in_window = center_dist <= (win_scale_um / 2.0)
+                        win = -center_dist
+                        win[~in_window] = 0
+                        win[in_window] -= win[in_window].min()
+                        win[in_window] /= win[in_window].max()
+                    windows.append(win)
 
     windows = np.array(windows)
 
@@ -336,6 +348,13 @@ def get_spatial_windows(
     return windows, window_centers
 
 
+def get_rigid_windows(spatial_bin_centers):
+    """Generate a single rectangular window for rigid motion."""
+    windows = np.ones((1, spatial_bin_centers.size), dtype="float64")
+    window_centers = np.array([(spatial_bin_centers[0] + spatial_bin_centers[-1]) / 2.0])
+    return windows, window_centers
+
+
 def get_window_domains(windows):
     """Array of windows -> list of slices where window > 0."""
     slices = []
@@ -378,10 +397,10 @@ def get_spatial_bin_edges(recording, direction, hist_margin_um, bin_um):
     # contact along one axis
     probe = recording.get_probe()
     dim = ["x", "y", "z"].index(direction)
-    contact_depth = probe.contact_positions[:, dim]
+    contact_depths = probe.contact_positions[:, dim]
 
-    min_ = np.min(contact_depth) - hist_margin_um
-    max_ = np.max(contact_depth) + hist_margin_um
+    min_ = np.min(contact_depths) - hist_margin_um
+    max_ = np.max(contact_depths) + hist_margin_um
     spatial_bins = np.arange(min_, max_ + bin_um, bin_um)
 
     return spatial_bins

From 27a7f12cbdff199a06128e08510c1155da0200b0 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 12 Jul 2024 12:01:29 +0200
Subject: [PATCH 25/31] typo

---
 src/spikeinterface/sortingcomponents/motion/motion_cleaner.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py b/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py
index 2ac20ad46d..6fe36a6193 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_cleaner.py
@@ -6,7 +6,7 @@
 def clean_motion_vector(motion, temporal_bins, bin_duration_s, speed_threshold=30, sigma_smooth_s=None):
     """
     Simple machinery to remove spurious fast bump in the motion vector.
-    Also can applyt a smoothing.
+    Also can apply a smoothing.
 
 
     Arguments

From 997cdba0170483d8bfac64859ef123a007e6530d Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 12 Jul 2024 12:20:58 +0200
Subject: [PATCH 26/31] Use numpy.broadcast_to for conv_engine numpy in
 normxcorr1d

---
 .../preprocessing/tests/test_motion.py        |  4 +-
 .../sortingcomponents/motion/dredge.py        | 81 ++++++++++---------
 2 files changed, 44 insertions(+), 41 deletions(-)

diff --git a/src/spikeinterface/preprocessing/tests/test_motion.py b/src/spikeinterface/preprocessing/tests/test_motion.py
index 02efef1e3b..b7d740cfd6 100644
--- a/src/spikeinterface/preprocessing/tests/test_motion.py
+++ b/src/spikeinterface/preprocessing/tests/test_motion.py
@@ -13,7 +13,9 @@ def test_estimate_and_correct_motion(create_cache_folder):
     if folder.exists():
         shutil.rmtree(folder)
 
-    rec_corrected = correct_motion(rec, folder=folder, estimate_motion_kwargs={"win_step_um": 20})
+    rec_corrected = correct_motion(
+        rec, folder=folder, estimate_motion_kwargs={"win_step_um": 20, "conv_engine": "numpy"}
+    )
     print(rec_corrected)
 
     # test reloading motion info
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 7c3b2e4c5a..a0dde6d52b 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -1137,45 +1137,46 @@ def normxcorr1d(
     padding="same",
     conv_engine="torch",
 ):
-    """normxcorr1d: Normalized cross-correlation, optionally weighted
-
-        The API is like torch's F.conv1d, except I have accidentally
-        changed the position of input/weights -- template acts like weights,
-        and x acts like input.
-
-        Returns the cross-correlation of `template` and `x` at spatial lags
-        determined by `mode`. Useful for estimating the location of `template`
-        within `x`.
-
-        This might not be the most efficient implementation -- ideas welcome.
-        It uses a direct convolutional translation of the formula
-            corr = (E[XY] - EX EY) / sqrt(var X * var Y)
-
-        This also supports weights! In that case, the usual adaptation of
-        the above formula is made to the weighted case -- and all of the
-        normalizations are done per block in the same way.
-
-        Arguments
-        ---------
-        template : tensor, shape (num_templates, length)
-            The reference template signal
-        x : tensor, 1d shape (length,) or 2d shape (num_inputs, length)
-            The signal in which to find `template`
-        weights : tensor, shape (length,)
-            Will use weighted means, variances, covariances if supplied.
-        centered : bool
-            If true, means will be subtracted (per weighted patch).
-        normalized : bool
-            If true, normalize by the variance (per weighted patch).
-        padding : int, optional
-            How far to look? if unset, we'll use half the length
-        conv_engine : "torch" | "numpy"
-            What library to use for computing cross-correlations.
-            If numpy, falls back to the scipy correlate function.
-    conv_engine
-        Returns
-        -------
-        corr : tensor
+    """
+    normxcorr1d: Normalized cross-correlation, optionally weighted
+
+    The API is like torch's F.conv1d, except I have accidentally
+    changed the position of input/weights -- template acts like weights,
+    and x acts like input.
+
+    Returns the cross-correlation of `template` and `x` at spatial lags
+    determined by `mode`. Useful for estimating the location of `template`
+    within `x`.
+
+    This might not be the most efficient implementation -- ideas welcome.
+    It uses a direct convolutional translation of the formula
+        corr = (E[XY] - EX EY) / sqrt(var X * var Y)
+
+    This also supports weights! In that case, the usual adaptation of
+    the above formula is made to the weighted case -- and all of the
+    normalizations are done per block in the same way.
+
+    Parameters
+    ----------
+    template : tensor, shape (num_templates, length)
+        The reference template signal
+    x : tensor, 1d shape (length,) or 2d shape (num_inputs, length)
+        The signal in which to find `template`
+    weights : tensor, shape (length,)
+        Will use weighted means, variances, covariances if supplied.
+    centered : bool
+        If true, means will be subtracted (per weighted patch).
+    normalized : bool
+        If true, normalize by the variance (per weighted patch).
+    padding : int, optional
+        How far to look? if unset, we'll use half the length
+    conv_engine : "torch" | "numpy"
+        What library to use for computing cross-correlations.
+        If numpy, falls back to the scipy correlate function.
+
+    Returns
+    -------
+    corr : tensor
     """
 
     if conv_engine == "torch":
@@ -1261,7 +1262,7 @@ def normxcorr1d(
     # now find the final normxcorr
     corr = cov  # renaming for clarity
     if normalized:
-        corr[torch.broadcast_to(empty, corr.shape)] = 0
+        corr[npx.broadcast_to(empty, corr.shape)] = 0
         corr /= npx.sqrt(var_x)
         corr /= npx.sqrt(var_template)
 

From e8f4e7659a03fcdaddb84f5e58f254685d8f5114 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 12 Jul 2024 12:25:10 +0200
Subject: [PATCH 27/31] formatting

---
 src/spikeinterface/sortingcomponents/motion/motion_utils.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index d98501d257..22c64ef8fb 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -306,9 +306,7 @@ def get_spatial_windows(
         min_ = np.min(contact_depths) - win_margin_um
         max_ = np.max(contact_depths) + win_margin_um
         if min_ >= max_:
-            warnings.warn(
-                f"get_spatial_windows(): win_margin_um is too large for the probe size. " "Using rigid motion."
-            )
+            warnings.warn(f"get_spatial_windows(): win_margin_um is too large for the probe size. Using rigid motion.")
             # if the probe is too small, we use a single window
             windows, window_centers = get_rigid_windows(spatial_bin_centers)
         else:

From 756826074a5c5fd23168a3cb31ed80dcb32bb473 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 12 Jul 2024 13:20:51 +0200
Subject: [PATCH 28/31] Fix tdc2 and propagate to API

---
 doc/api.rst                                   | 18 +++++++----
 .../benchmark_with_hybrid_recordings.rst      | 32 +++++++++----------
 doc/how_to/handle_drift.rst                   |  2 +-
 doc/modules/motion_correction.rst             |  3 +-
 doc/modules/sortingcomponents.rst             |  6 ++--
 .../benchmark_with_hybrid_recordings.py       |  2 +-
 examples/how_to/handle_drift.py               |  2 +-
 src/spikeinterface/preprocessing/motion.py    |  4 +--
 .../sorters/internal/tridesclous2.py          |  2 +-
 9 files changed, 38 insertions(+), 33 deletions(-)

diff --git a/doc/api.rst b/doc/api.rst
index 3e825084e7..ac221ac602 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -408,12 +408,6 @@ Peak Detection
 
     .. autofunction:: detect_peaks
 
-Motion Correction
-~~~~~~~~~~~~~~~~~
-.. automodule:: spikeinterface.sortingcomponents.motion_interpolation
-
-    .. autoclass:: InterpolateMotionRecording
-
 Clustering
 ~~~~~~~~~~
 .. automodule:: spikeinterface.sortingcomponents.clustering
@@ -425,3 +419,15 @@ Template Matching
 .. automodule:: spikeinterface.sortingcomponents.matching
 
     .. autofunction:: find_spikes_from_templates
+
+Motion Correction
+~~~~~~~~~~~~~~~~~
+.. automodule:: spikeinterface.sortingcomponents.motion
+
+    .. autoclass:: Motion
+    .. autofunction:: estimate_motion
+    .. autofunction:: interpolate_motion
+    .. autofunction:: correct_motion_on_peaks
+    .. autofunction:: interpolate_motion_on_traces
+    .. autofunction:: clean_motion_vector
+    .. autoclass:: InterpolateMotionRecording
diff --git a/doc/how_to/benchmark_with_hybrid_recordings.rst b/doc/how_to/benchmark_with_hybrid_recordings.rst
index 5870d87955..9975bb1a4b 100644
--- a/doc/how_to/benchmark_with_hybrid_recordings.rst
+++ b/doc/how_to/benchmark_with_hybrid_recordings.rst
@@ -24,7 +24,7 @@ order to smoothly inject spikes into the recording.
     import spikeinterface.generation as sgen
     import spikeinterface.widgets as sw
 
-    from spikeinterface.sortingcomponents.motion_estimation import estimate_motion
+    from spikeinterface.sortingcomponents.motion import estimate_motion
 
     import numpy as np
     import matplotlib.pyplot as plt
@@ -1202,63 +1202,63 @@ drifts when injecting hybrid spikes.
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     1.         0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     2.         0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     3.         0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     4.         0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     5.         0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     6.         0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     7.         0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     8.         0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     9.         0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     10.        0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     11.        0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     12.        0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     13.        0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     14.        0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385
-     0.         0.         0.07692308 0.07692308 0.15384615 0.15384615
+     15.        0.         0.07692308 0.07692308 0.15384615 0.15384615
      0.23076923 0.23076923 0.30769231 0.30769231 0.38461538 0.38461538
      0.46153846 0.46153846 0.53846154 0.53846154 0.61538462 0.61538462
      0.69230769 0.69230769 0.76923077 0.76923077 0.84615385 0.84615385]</details></ul></details>
diff --git a/doc/how_to/handle_drift.rst b/doc/how_to/handle_drift.rst
index 5c4476187b..fae4e8d2f6 100644
--- a/doc/how_to/handle_drift.rst
+++ b/doc/how_to/handle_drift.rst
@@ -245,7 +245,7 @@ to display the results.
 
 .. code:: ipython
 
-    from spikeinterface.sortingcomponents.motion_interpolation import correct_motion_on_peaks
+    from spikeinterface.sortingcomponents.motion import correct_motion_on_peaks
 
     for preset in some_presets:
         folder = base_folder / 'motion_folder_dataset1' / preset
diff --git a/doc/modules/motion_correction.rst b/doc/modules/motion_correction.rst
index af81cb42d1..076a560e31 100644
--- a/doc/modules/motion_correction.rst
+++ b/doc/modules/motion_correction.rst
@@ -151,8 +151,7 @@ The high-level :py:func:`~spikeinterface.preprocessing.correct_motion()` is inte
     from spikeinterface.sortingcomponents.peak_detection import detect_peaks
     from spikeinterface.sortingcomponents.peak_selection import select_peaks
     from spikeinterface.sortingcomponents.peak_localization import localize_peaks
-    from spikeinterface.sortingcomponents.motion_estimation import estimate_motion
-    from spikeinterface.sortingcomponents.motion_interpolation import interpolate_motion
+    from spikeinterface.sortingcomponents.motion import estimate_motion, interpolate_motion
 
     job_kwargs = dict(chunk_duration="1s", n_jobs=20, progress_bar=True)
     # Step 1 : activity profile
diff --git a/doc/modules/sortingcomponents.rst b/doc/modules/sortingcomponents.rst
index e7e05312bc..a32e111bd7 100644
--- a/doc/modules/sortingcomponents.rst
+++ b/doc/modules/sortingcomponents.rst
@@ -190,7 +190,7 @@ Here is an example with non-rigid motion estimation:
     peak_locations = localize_peaks(recording=recording, peaks=peaks, ...) # as above
 
 
-    from spikeinterface.sortingcomponents.motion_estimation import estimate_motion
+    from spikeinterface.sortingcomponents.motion import estimate_motion
     motion, temporal_bins, spatial_bins,
                 extra_check = estimate_motion(recording=recording, peaks=peaks, peak_locations=peak_locations,
                                               direction='y', bin_s=10., bin_um=10., margin_um=0.,
@@ -206,7 +206,7 @@ Motion interpolation
 
 The estimated motion can be used to interpolate traces, in other words, for drift correction.
 One possible way is to make an interpolation sample-by-sample to compensate for the motion.
-The :py:class:`~spikeinterface.sortingcomponents.motion_interpolation.InterpolateMotionRecording` is a preprocessing
+The :py:class:`~spikeinterface.sortingcomponents.motion.InterpolateMotionRecording` is a preprocessing
 step doing this. This preprocessing is *lazy*, so that interpolation is done on-the-fly. However, the class needs the
 "motion vector" as input, which requires a relatively long computation (peak detection, localization and motion
 estimation).
@@ -216,7 +216,7 @@ Here is a short example that depends on the output of "Motion interpolation":
 
 .. code-block:: python
 
-  from spikeinterface.sortingcomponents.motion_interpolation import InterpolateMotionRecording
+  from spikeinterface.sortingcomponents.motion import InterpolateMotionRecording
 
   recording_corrected = InterpolateMotionRecording(recording=recording_with_drift, motion=motion, temporal_bins=temporal_bins, spatial_bins=spatial_bins
                                                    spatial_interpolation_method='kriging',
diff --git a/examples/how_to/benchmark_with_hybrid_recordings.py b/examples/how_to/benchmark_with_hybrid_recordings.py
index 5507ab7a7f..abf6a25ff5 100644
--- a/examples/how_to/benchmark_with_hybrid_recordings.py
+++ b/examples/how_to/benchmark_with_hybrid_recordings.py
@@ -32,7 +32,7 @@
 import spikeinterface.generation as sgen
 import spikeinterface.widgets as sw
 
-from spikeinterface.sortingcomponents.motion_estimation import estimate_motion
+from spikeinterface.sortingcomponents.motion import estimate_motion
 
 import numpy as np
 import matplotlib.pyplot as plt
diff --git a/examples/how_to/handle_drift.py b/examples/how_to/handle_drift.py
index 79a7c899f5..ecf17a1b1f 100644
--- a/examples/how_to/handle_drift.py
+++ b/examples/how_to/handle_drift.py
@@ -167,7 +167,7 @@ def preprocess_chain(rec):
 # Case 1 is used before running a spike sorter and the case 2 is used here to display the results.
 
 # +
-from spikeinterface.sortingcomponents.motion_interpolation import correct_motion_on_peaks
+from spikeinterface.sortingcomponents.motion import correct_motion_on_peaks
 
 for preset in some_presets:
     folder = base_folder / "motion_folder_dataset1" / preset
diff --git a/src/spikeinterface/preprocessing/motion.py b/src/spikeinterface/preprocessing/motion.py
index 5e91623257..8e9911b47e 100644
--- a/src/spikeinterface/preprocessing/motion.py
+++ b/src/spikeinterface/preprocessing/motion.py
@@ -238,8 +238,8 @@ def correct_motion(
       * :py:func:`~spikeinterface.sortingcomponents.peak_detection.detect_peaks`
       * :py:func:`~spikeinterface.sortingcomponents.peak_selection.select_peaks`
       * :py:func:`~spikeinterface.sortingcomponents.peak_localization.localize_peaks`
-      * :py:func:`~spikeinterface.sortingcomponents.motion.motion_estimation.estimate_motion`
-      * :py:func:`~spikeinterface.sortingcomponents.motion.motion_interpolation.interpolate_motion`
+      * :py:func:`~spikeinterface.sortingcomponents.motion.motion.estimate_motion`
+      * :py:func:`~spikeinterface.sortingcomponents.motion.motion.interpolate_motion`
 
 
     Possible presets : {}
diff --git a/src/spikeinterface/sorters/internal/tridesclous2.py b/src/spikeinterface/sorters/internal/tridesclous2.py
index 2f965b0483..57755cd759 100644
--- a/src/spikeinterface/sorters/internal/tridesclous2.py
+++ b/src/spikeinterface/sorters/internal/tridesclous2.py
@@ -89,7 +89,7 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
         from spikeinterface.sortingcomponents.clustering.main import find_cluster_from_peaks
         from spikeinterface.sortingcomponents.tools import remove_empty_templates
         from spikeinterface.preprocessing import correct_motion
-        from spikeinterface.sortingcomponents.motion_interpolation import InterpolateMotionRecording
+        from spikeinterface.sortingcomponents.motion import InterpolateMotionRecording
 
         job_kwargs = params["job_kwargs"].copy()
         job_kwargs = fix_job_kwargs(job_kwargs)

From e3180881d72d855a4e823ef74cd86312048755c9 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 12 Jul 2024 14:06:21 +0200
Subject: [PATCH 29/31] raise error if num_windows<1 and fix motion test

---
 .../preprocessing/tests/test_motion.py        |  4 +-
 .../sortingcomponents/motion/motion_utils.py  | 58 +++++++++----------
 2 files changed, 27 insertions(+), 35 deletions(-)

diff --git a/src/spikeinterface/preprocessing/tests/test_motion.py b/src/spikeinterface/preprocessing/tests/test_motion.py
index b7d740cfd6..a1ad3766a9 100644
--- a/src/spikeinterface/preprocessing/tests/test_motion.py
+++ b/src/spikeinterface/preprocessing/tests/test_motion.py
@@ -13,9 +13,7 @@ def test_estimate_and_correct_motion(create_cache_folder):
     if folder.exists():
         shutil.rmtree(folder)
 
-    rec_corrected = correct_motion(
-        rec, folder=folder, estimate_motion_kwargs={"win_step_um": 20, "conv_engine": "numpy"}
-    )
+    rec_corrected = correct_motion(rec, folder=folder, estimate_motion_kwargs={"win_step_um": 50, "win_scale_um": 100})
     print(rec_corrected)
 
     # test reloading motion info
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index 22c64ef8fb..a45973592b 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -296,7 +296,7 @@ def get_spatial_windows(
     else:
         if win_scale_um <= win_step_um / 5.0:
             warnings.warn(
-                f"get_spatial_windows(): spatial windows are probably not overlaping because {win_scale_um=} and {win_step_um=}"
+                f"get_spatial_windows(): spatial windows are probably not overlapping because {win_scale_um=} and {win_step_um=}"
             )
 
         if win_margin_um is None:
@@ -305,37 +305,31 @@ def get_spatial_windows(
 
         min_ = np.min(contact_depths) - win_margin_um
         max_ = np.max(contact_depths) + win_margin_um
-        if min_ >= max_:
-            warnings.warn(f"get_spatial_windows(): win_margin_um is too large for the probe size. Using rigid motion.")
-            # if the probe is too small, we use a single window
-            windows, window_centers = get_rigid_windows(spatial_bin_centers)
-        else:
-            num_windows = int((max_ - min_) // win_step_um)
-            if num_windows == 0:
-                warnings.warn(
-                    f"get_spatial_windows(): win_step_um and win_margin_um are too large for the probe size. "
-                    "Using rigid motion."
-                )
-                windows, window_centers = get_rigid_windows(spatial_bin_centers)
-            else:
-                border = ((max_ - min_) % win_step_um) / 2
-                window_centers = np.arange(num_windows + 1) * win_step_um + min_ + border
-                windows = []
-
-                for win_center in window_centers:
-                    if win_shape == "gaussian":
-                        win = np.exp(-((spatial_bin_centers - win_center) ** 2) / (2 * win_scale_um**2))
-                    elif win_shape == "rect":
-                        win = np.abs(spatial_bin_centers - win_center) < (win_scale_um / 2.0)
-                        win = win.astype("float64")
-                    elif win_shape == "triangle":
-                        center_dist = np.abs(spatial_bin_centers - win_center)
-                        in_window = center_dist <= (win_scale_um / 2.0)
-                        win = -center_dist
-                        win[~in_window] = 0
-                        win[in_window] -= win[in_window].min()
-                        win[in_window] /= win[in_window].max()
-                    windows.append(win)
+        num_windows = int((max_ - min_) // win_step_um)
+
+        if num_windows < 1:
+            raise Exception(
+                f"get_spatial_windows(): win_step_um/win_scale_um/win_margin_um are too large for the probe size. "
+                "You can try to reduce them or use rigid motion."
+            )
+        border = ((max_ - min_) % win_step_um) / 2
+        window_centers = np.arange(num_windows + 1) * win_step_um + min_ + border
+        windows = []
+
+        for win_center in window_centers:
+            if win_shape == "gaussian":
+                win = np.exp(-((spatial_bin_centers - win_center) ** 2) / (2 * win_scale_um**2))
+            elif win_shape == "rect":
+                win = np.abs(spatial_bin_centers - win_center) < (win_scale_um / 2.0)
+                win = win.astype("float64")
+            elif win_shape == "triangle":
+                center_dist = np.abs(spatial_bin_centers - win_center)
+                in_window = center_dist <= (win_scale_um / 2.0)
+                win = -center_dist
+                win[~in_window] = 0
+                win[in_window] -= win[in_window].min()
+                win[in_window] /= win[in_window].max()
+            windows.append(win)
 
     windows = np.array(windows)
 

From 4c4e70f6d135c25005861a95089cd5d22e4d0321 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 12 Jul 2024 14:10:30 +0200
Subject: [PATCH 30/31] Fix final(?) torch import

---
 src/spikeinterface/sortingcomponents/motion/decentralized.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/decentralized.py b/src/spikeinterface/sortingcomponents/motion/decentralized.py
index 32f60f568f..41b03b1c43 100644
--- a/src/spikeinterface/sortingcomponents/motion/decentralized.py
+++ b/src/spikeinterface/sortingcomponents/motion/decentralized.py
@@ -320,12 +320,14 @@ def compute_pairwise_displacement(
         # use torch if installed
         try:
             import torch
-            import torch.nn.functional as F
 
             conv_engine = "torch"
         except ImportError:
             conv_engine = "numpy"
 
+    if conv_engine == "torch":
+        import torch
+
     assert conv_engine in ("torch", "numpy"), f"'conv_engine' must be 'torch' or 'numpy'"
     size = motion_hist.shape[0]
     pairwise_displacement = np.zeros((size, size), dtype="float32")

From abb6a7c4948a93db3a81aa8bcce7add2e97a0d7e Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 12 Jul 2024 14:54:38 +0200
Subject: [PATCH 31/31] Fix generation tests

---
 src/spikeinterface/generation/tests/test_hybrid_tools.py  | 8 +++++---
 .../sortingcomponents/motion/motion_utils.py              | 4 ++--
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/src/spikeinterface/generation/tests/test_hybrid_tools.py b/src/spikeinterface/generation/tests/test_hybrid_tools.py
index d31a0ec81d..bdcd8dbb8f 100644
--- a/src/spikeinterface/generation/tests/test_hybrid_tools.py
+++ b/src/spikeinterface/generation/tests/test_hybrid_tools.py
@@ -7,7 +7,7 @@
     generate_templates,
     generate_unit_locations,
 )
-from spikeinterface.preprocessing.motion import correct_motion, load_motion_info
+from spikeinterface.preprocessing.motion import correct_motion
 from spikeinterface.generation.hybrid_tools import (
     estimate_templates_from_recording,
     generate_hybrid_recording,
@@ -35,8 +35,10 @@ def test_generate_hybrid_with_sorting():
 
 
 def test_generate_hybrid_motion():
-    rec, _ = generate_ground_truth_recording(sampling_frequency=20000, durations=[10], seed=0)
-    _, motion_info = correct_motion(rec, output_motion_info=True)
+    rec, _ = generate_ground_truth_recording(sampling_frequency=20000, durations=[10], num_channels=16, seed=0)
+    _, motion_info = correct_motion(
+        rec, output_motion_info=True, estimate_motion_kwargs={"win_step_um": 20, "win_scale_um": 20}
+    )
     motion = motion_info["motion"]
     hybrid, sorting_hybrid = generate_hybrid_recording(rec, motion=motion, seed=0)
     assert rec.get_num_channels() == hybrid.get_num_channels()
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index a45973592b..a48e10b3e1 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -309,8 +309,8 @@ def get_spatial_windows(
 
         if num_windows < 1:
             raise Exception(
-                f"get_spatial_windows(): win_step_um/win_scale_um/win_margin_um are too large for the probe size. "
-                "You can try to reduce them or use rigid motion."
+                f"get_spatial_windows(): {win_step_um=}/{win_scale_um=}/{win_margin_um=} are too large for the "
+                f"probe size (depth range={np.ptp(contact_depths)}). You can try to reduce them or use rigid motion."
             )
         border = ((max_ - min_) % win_step_um) / 2
         window_centers = np.arange(num_windows + 1) * win_step_um + min_ + border