UnitMatchPy 3.2.8__tar.gz → 3.3.0__tar.gz

unitmatchpy-3.3.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: UnitMatchPy
+Version: 3.3.0
+Summary: Automatic matching of neurons across sessions
+Author: Enny van Beest, Célian Bimbard, Suyash Agarwal, Wentao Qiu
+License: CC BY-NC-SA 4.0 International
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.13,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.0,>=1.21
+Requires-Dist: scipy<2.0,>=1.9
+Requires-Dist: pandas<3.0,>=1.5
+Requires-Dist: matplotlib<4.0,>=3.6
+Requires-Dist: joblib<2.0,>=1.2
+Requires-Dist: tqdm<5.0,>=4.64
+Requires-Dist: h5py<4.0,>=3.8
+Requires-Dist: scikit-learn<2.0,>=1.2
+Requires-Dist: mtscomp
+Requires-Dist: torch<3.0,>=2.1
+Provides-Extra: full
+Requires-Dist: mat73<1.0,>=0.62; extra == "full"
+Requires-Dist: spikeinterface<0.120,>=0.100; extra == "full"
+Provides-Extra: notebooks
+Requires-Dist: ipykernel<7,>=6; extra == "notebooks"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# UnitMatchPy (UMPy) and DeepUnitMatch (DUM)
+
+This repository contains:
+- **UnitMatchPy (UMPy)**: automatic matching of neurons across sessions (Python package).
+- **DeepUnitMatch (DUM)**: DeepUnitMatch pipeline and demos (see preprint below).
+
+## References
+
+- **UnitMatch (UMPy):** https://www.nature.com/articles/s41592-024-02440-1
+- **DeepUnitMatch (DUM) preprint:** https://www.biorxiv.org/content/10.64898/2026.01.30.702777v1
+
+## Versions
+
+- **UnitMatchPy version:** `3.2.9` (from `pyproject.toml`)
+- **DeepUnitMatch:** code lives under `DeepUnitMatch/` (see **DeepUnitMatch (DUM)** section)
+
+## Installation
+
+`pip install` (including `pip install -e .`) installs into whatever Python environment your `pip` points to (system Python, a conda env, or a virtualenv). `pip` does **not** create or name environments.
+
+We recommend using Anaconda/Miniconda (conda) to create an isolated environment first:
+
+```bash
+# Create a new environment (pick any name you like; example: UMPy)
+conda create -n UMPy python=3.11 pip #(press y when prompted)
+conda activate UMPy
+```
+
+Then install using pip (options below).
+
+### Option A: Install the released package (PyPI)
+
+```bash
+pip install UnitMatchPy
+```
+
+Optional extras (heavier dependencies used by some notebooks and integration with SpikeInterface):
+
+```bash
+pip install "UnitMatchPy[full,notebooks]"
+```
+
+### Option B: Install a local, editable copy (for development / modified code)
+
+First, open a terminal and navigate to this folder (the one containing `pyproject.toml`). The `pip install -e` command must be run from here:
+
+```bash
+# Windows (PowerShell)
+cd $HOME\Documents\GitHub\DeepUnitMatch\UnitMatchPy
+
+# macOS / Linux
+cd ~/Documents/GitHub/DeepUnitMatch/UnitMatchPy
+```
+
+```bash
+pip install -e .
+```
+
+Optional extras (e.g. if you'd like to run the notebooks or integrate with SpikeInterface):
+
+```bash
+pip install -e ".[full,notebooks]"
+```
+
+## Demo notebooks
+
+All demo notebooks are in `Demo Notebooks/`.
+
+### Run UnitMatchPy (UMPy)
+
+To run UMPy, standard spike sorting data is needed (channel positions and extracted raw waveforms for each unit). Waveforms can be extracted externally (e.g. [BombCell](https://github.com/Julie-Fabre/bombcell)) or using the demo notebooks:
+- `Demo Notebooks/extract_raw_data_demo.ipynb` (compressed `.cbin`/`.ch` or raw)
+- `Demo Notebooks/extract_raw_data_demo_open_ephys.ipynb` (Open Ephys)
+- `Demo Notebooks/UMPy_spike_interface_demo.ipynb` ([SpikeInterface](https://spikeinterface.readthedocs.io/en/latest/) workflow)
+
+Example notebooks:
+- `Demo Notebooks/UMPy_example.ipynb` (recommended starting point)
+- `Demo Notebooks/UMPy_example_detailed.ipynb` (more modular / advanced)
+
+The GUI is an optional step to curate and explore UnitMatch outputs; see `Demo Notebooks/GUI_Reference_Guide.md` for usage tips and shortcuts.
+
+## DeepUnitMatch (DUM)
+
+To try the DeepUnitMatch version, start with:
+- `Demo Notebooks/DeepUnitMatch.ipynb`
+
+If you want to train / fine-tune a model on your own data, see:
+- `Demo Notebooks/DUM_training.ipynb`
+
+Important note: DeepUnitMatch current trained model is for Npix 2.0 4-shank only. You will need to train a new model with your own data if you have any other type of probe. (For example, Mouse2 from the figshare data is a Npix 1 dataset, you'll notice the trained model won't give good results on this mouse for that reason.)

unitmatchpy-3.3.0/README.md

@@ -0,0 +1,90 @@
+# UnitMatchPy (UMPy) and DeepUnitMatch (DUM)
+
+This repository contains:
+- **UnitMatchPy (UMPy)**: automatic matching of neurons across sessions (Python package).
+- **DeepUnitMatch (DUM)**: DeepUnitMatch pipeline and demos (see preprint below).
+
+## References
+
+- **UnitMatch (UMPy):** https://www.nature.com/articles/s41592-024-02440-1
+- **DeepUnitMatch (DUM) preprint:** https://www.biorxiv.org/content/10.64898/2026.01.30.702777v1
+
+## Versions
+
+- **UnitMatchPy version:** `3.2.9` (from `pyproject.toml`)
+- **DeepUnitMatch:** code lives under `DeepUnitMatch/` (see **DeepUnitMatch (DUM)** section)
+
+## Installation
+
+`pip install` (including `pip install -e .`) installs into whatever Python environment your `pip` points to (system Python, a conda env, or a virtualenv). `pip` does **not** create or name environments.
+
+We recommend using Anaconda/Miniconda (conda) to create an isolated environment first:
+
+```bash
+# Create a new environment (pick any name you like; example: UMPy)
+conda create -n UMPy python=3.11 pip #(press y when prompted)
+conda activate UMPy
+```
+
+Then install using pip (options below).
+
+### Option A: Install the released package (PyPI)
+
+```bash
+pip install UnitMatchPy
+```
+
+Optional extras (heavier dependencies used by some notebooks and integration with SpikeInterface):
+
+```bash
+pip install "UnitMatchPy[full,notebooks]"
+```
+
+### Option B: Install a local, editable copy (for development / modified code)
+
+First, open a terminal and navigate to this folder (the one containing `pyproject.toml`). The `pip install -e` command must be run from here:
+
+```bash
+# Windows (PowerShell)
+cd $HOME\Documents\GitHub\DeepUnitMatch\UnitMatchPy
+
+# macOS / Linux
+cd ~/Documents/GitHub/DeepUnitMatch/UnitMatchPy
+```
+
+```bash
+pip install -e .
+```
+
+Optional extras (e.g. if you'd like to run the notebooks or integrate with SpikeInterface):
+
+```bash
+pip install -e ".[full,notebooks]"
+```
+
+## Demo notebooks
+
+All demo notebooks are in `Demo Notebooks/`.
+
+### Run UnitMatchPy (UMPy)
+
+To run UMPy, standard spike sorting data is needed (channel positions and extracted raw waveforms for each unit). Waveforms can be extracted externally (e.g. [BombCell](https://github.com/Julie-Fabre/bombcell)) or using the demo notebooks:
+- `Demo Notebooks/extract_raw_data_demo.ipynb` (compressed `.cbin`/`.ch` or raw)
+- `Demo Notebooks/extract_raw_data_demo_open_ephys.ipynb` (Open Ephys)
+- `Demo Notebooks/UMPy_spike_interface_demo.ipynb` ([SpikeInterface](https://spikeinterface.readthedocs.io/en/latest/) workflow)
+
+Example notebooks:
+- `Demo Notebooks/UMPy_example.ipynb` (recommended starting point)
+- `Demo Notebooks/UMPy_example_detailed.ipynb` (more modular / advanced)
+
+The GUI is an optional step to curate and explore UnitMatch outputs; see `Demo Notebooks/GUI_Reference_Guide.md` for usage tips and shortcuts.
+
+## DeepUnitMatch (DUM)
+
+To try the DeepUnitMatch version, start with:
+- `Demo Notebooks/DeepUnitMatch.ipynb`
+
+If you want to train / fine-tune a model on your own data, see:
+- `Demo Notebooks/DUM_training.ipynb`
+
+Important note: DeepUnitMatch current trained model is for Npix 2.0 4-shank only. You will need to train a new model with your own data if you have any other type of probe. (For example, Mouse2 from the figshare data is a Npix 1 dataset, you'll notice the trained model won't give good results on this mouse for that reason.)

{unitmatchpy-3.2.8 → unitmatchpy-3.3.0}/UnitMatchPy/default_params.py

@@ -25,7 +25,8 @@ def get_default_param(param = None):
             'min_angle_dist' : 0.1, # smallest distance for and angle to be consider
             'min_new_shank_distance' : 100, #The smallest distance which separates 2 shanks
             'units_per_shank_thrs' : 15, # threshold for doing per shank drift correction
-            'match_threshold' : 0.5 # probability threshold to consider as a match
+            'match_threshold' : 0.5, # probability threshold to consider as a match
+            'curve_fit_maxfev' : 10000, # max evaluations for decay curve fitting
         }
     
     tmp['score_vector'] = np.arange(tmp['stepsz']/2 ,1 ,tmp['stepsz'])

{unitmatchpy-3.2.8 → unitmatchpy-3.3.0}/UnitMatchPy/metric_functions.py

@@ -118,7 +118,7 @@ def get_waveforms_mse(avg_waveform, param):
     waveform_mse = re_scale(raw_wave_mse_norm)
     return waveform_mse
 
-def flip_dim(avg_waveform_per_tp, param):
+def flip_dim(avg_waveform_per_tp, param, n=None):
     """
     Creates a version of the weighted average waveform per time point, where the x axis is flipped, due to the effect
     where the average position tends to wards the center of the x coords when the wave is decaying
@@ -135,7 +135,10 @@ def flip_dim(avg_waveform_per_tp, param):
     ndarray
         The average waveform per time point with the x axis flipped and not flipped 
     """
-    n_units = param['n_units']
+    if n is not None:
+        n_units = n
+    else:
+        n_units = param['n_units']
     spike_width = param['spike_width']
 
     flip_dim = np.array((1,)) # BE CAREFUL HERE, Which dimension is the x-axis  
@@ -152,7 +155,7 @@ def flip_dim(avg_waveform_per_tp, param):
 
     return avg_waveform_per_tp_flip
 
-def get_Euclidean_dist(avg_waveform_per_tp_flip,param):
+def get_Euclidean_dist(avg_waveform_per_tp_flip,param, n=None):
     """
     Calculated the Euclidean distance between the units at each time point and for the flipped axis case
 
@@ -170,7 +173,10 @@ def get_Euclidean_dist(avg_waveform_per_tp_flip,param):
     """
     # Memory-efficient implementation using loops instead of massive tiling
     waveidx = param['waveidx']
-    n_units = param['n_units']
+    if n is not None:
+        n_units = n
+    else:
+        n_units = param['n_units']
     
     # Extract the relevant slices once
     data_cv0 = avg_waveform_per_tp_flip[:,:,waveidx,0,:]  # (3, n_units, len(waveidx), n_flips)
@@ -186,13 +192,13 @@ def get_Euclidean_dist(avg_waveform_per_tp_flip,param):
             unit_i_data = data_cv0[:, i, :, :]  # (3, len(waveidx), n_flips)
             unit_j_data = data_cv1[:, j, :, :]  # (3, len(waveidx), n_flips)
             
-            # Check for NaN values
-            w = np.isnan(np.abs(unit_i_data[0,:,:] - unit_j_data[0,:,:]))
-            
             # Compute Euclidean distance between units i and j
             diff = unit_i_data - unit_j_data  # (3, len(waveidx), n_flips)
             tmp_euclid = np.linalg.norm(diff, axis=0)  # (len(waveidx), n_flips)
-            tmp_euclid[w] = np.nan
+
+            # Be explicit about NaNs across any spatial dimension
+            nan_mask = np.isnan(diff).any(axis=0)
+            tmp_euclid[nan_mask] = np.nan
             
             # Store result
             euclid_dist[i, :, :, j] = tmp_euclid
@@ -216,19 +222,30 @@ def centroid_metrics(euclid_dist, param):
         An array (n_units, n_units) of scores for centroid distance and variance
     """
     max_dist = param['max_dist']
-    waveidx = param['waveidx']
-    new_peak_loc = param['peak_loc']    
+    waveidx = np.asarray(param['waveidx'])
+    peak_loc = int(param['peak_loc'])
 
-    centroid_dist = np.nanmin( euclid_dist[:,new_peak_loc - waveidx ==0,:,:].squeeze(), axis =1 ).squeeze()
+    peak_matches = np.flatnonzero(waveidx == peak_loc)
+    if peak_matches.size == 0:
+        raise ValueError("param['peak_loc'] must be present in param['waveidx'].")
+    peak_idx = int(peak_matches[0])
 
+    # euclid_dist: (n_units, n_waveidx, n_flips, n_units)
+    centroid_dist = np.nanmin(euclid_dist[:, peak_idx, :, :], axis=1)
 
-    centroid_dist = 1 - ((centroid_dist - np.nanmin(centroid_dist)) / (max_dist - np.nanmin(centroid_dist)))
-    centroid_dist[centroid_dist<0] = 0
+    min_centroid_dist = np.nanmin(centroid_dist)
+    denom = max_dist - min_centroid_dist
+    if not np.isfinite(denom) or denom <= 0:
+        centroid_dist = np.zeros_like(centroid_dist)
+    else:
+        centroid_dist = 1 - ((centroid_dist - min_centroid_dist) / denom)
+        centroid_dist = np.clip(centroid_dist, 0, 1)
     centroid_dist[np.isnan(centroid_dist)] = 0
 
     #Centroid Var
     # need ddof = 1 to match with ML
-    centroid_var = np.nanmin( np.nanvar(euclid_dist, axis = 1, ddof = 1 ).squeeze(), axis =1 ).squeeze()
+    ddof = 1 if euclid_dist.shape[1] > 1 else 0
+    centroid_var = np.nanmin(np.nanvar(euclid_dist, axis=1, ddof=ddof), axis=1)
     centroid_var = np.sqrt(centroid_var)
     centroid_var = re_scale(centroid_var)
     centroid_var[np.isnan(centroid_var)] = 0
@@ -696,6 +713,14 @@ def test_matches_per_shank(pairs, avg_centroid, sid, param):
         Will return True if there is enough units per shank to do per shank drift correction
     """
 
+    pairs = np.asarray(pairs)
+    if pairs.size == 0:
+        return False
+    if pairs.ndim == 1:
+        pairs = np.expand_dims(pairs, axis=0)
+    if pairs.ndim != 2 or pairs.shape[1] != 2:
+        raise ValueError("pairs must have shape (n_pairs, 2).")
+
     do_per_shank_correction = True
 
     centroid_a = np.nanmean( avg_centroid[:,pairs[:,0],:], axis = 2)
@@ -718,10 +743,10 @@ def test_matches_per_shank(pairs, avg_centroid, sid, param):
 
             if np.all(correct_shank_a == correct_shank_b) != True:
                 #delete pairs which are on different shanks
-                bad_idx = np.argwhere(correct_shank_a != correct_shank_b)[0]
+                bad_idx = np.flatnonzero(correct_shank_a != correct_shank_b)
                 print(f'These pairs may be bad {bad_idx}, so are excluded from drift correction')
-                correct_shank_a[bad_idx]=False
-                correct_shank_b[bad_idx]=False
+                correct_shank_a[bad_idx] = False
+                correct_shank_b[bad_idx] = False
                 
             shank_id_tmp[correct_shank_a] = i
 
@@ -771,8 +796,10 @@ def drift_n_sessions(candidate_pairs, session_switch, avg_centroid, avg_waveform
     n_sessions = param['n_sessions']
     best_pairs = np.argwhere(candidate_pairs == 1)
 
-    #make it like the matlab code, (small unit idx, larger unit idx)
-    best_pairs[:, [0,1]] = best_pairs[:, [1,0]]
+    # Ensure each pair is ordered (small idx, large idx) regardless of matrix orientation
+    best_pairs = np.sort(best_pairs, axis=1)
+    if best_pairs.size > 0:
+        best_pairs = np.unique(best_pairs, axis=0)
 
     drifts = np.zeros( (n_sessions - 1, 3))
 
@@ -799,6 +826,68 @@ def drift_n_sessions(candidate_pairs, session_switch, avg_centroid, avg_waveform
     return drifts, avg_centroid, avg_waveform_per_tp
 
 
+def drift_correct_session_pair(candidate_pairs, session_switch, avg_centroid, avg_waveform_per_tp, did, param):
+    """
+    This function applies drift correction between n_sessions, currently this is done by aligning session 2 to session 1,
+    then session 3 to session 2 etc.   
+    This function, calls another function to apply the drift correction, to be able to apply different type of drift correction 
+    easily.
+
+    Parameters
+    ----------
+    candidate_pairs : ndarray
+        An array of likely matches
+    session_switch : ndarray
+        What units does the session switch
+    avg_centroid : ndarray
+        The average centroid for each unit
+    avg_waveform_per_tp : ndarray
+        The average waveform per time point for each unit
+    did : int
+        The session id
+    param : dict
+        The param dictionary
+
+    Returns
+    -------
+    ndarray
+        avg_waveform_per_tp arrays drift corrected
+    """
+    session_switch = np.asarray(session_switch).astype(int)
+    n_units = avg_centroid.shape[1]
+    if candidate_pairs.shape != (n_units, n_units):
+        raise ValueError("candidate_pairs must have shape (n_units, n_units) matching avg_centroid/avg_waveform_per_tp.")
+    if session_switch.ndim != 1 or session_switch.size < 3:
+        raise ValueError("session_switch must be a 1D array with at least 3 entries (start, boundary, end).")
+    if session_switch[0] != 0 or session_switch[-1] != n_units:
+        raise ValueError("session_switch must be relative to the provided arrays (session_switch[0]==0 and session_switch[-1]==n_units).")
+    if did < 0 or (did + 2) >= session_switch.size:
+        raise IndexError("did out of range for session_switch.")
+
+    best_pairs = np.argwhere(candidate_pairs == 1)
+
+    # Ensure each pair is ordered (small idx, large idx) regardless of matrix orientation
+    best_pairs = np.sort(best_pairs, axis=1)
+    if best_pairs.size > 0:
+        best_pairs = np.unique(best_pairs, axis=0)
+
+    idx = np.argwhere( ( (best_pairs[:,0] >= session_switch[did]) * (best_pairs[:,0] < session_switch[did + 1]) *
+                        (best_pairs[:,1] >= session_switch[did + 1]) * (best_pairs[:,1] < session_switch[did + 2]) ) == True)
+
+    pairs = best_pairs[idx,:].squeeze()
+    if pairs.ndim == 1:
+        pairs = np.expand_dims(pairs, axis = 0)
+
+    #Test to see if there are enough matches to do drift correction per shank
+    if test_matches_per_shank(pairs, avg_centroid, did, param) == True:
+        _, avg_waveform_per_tp,_ = apply_drift_correction_per_shank(pairs, did, session_switch, avg_centroid, avg_waveform_per_tp, param)
+        print(f'Done drift correction per shank for session pair {did+1} and {did+2}')
+    elif len(pairs)>0: #if there exist pairs across sessions:
+        _, avg_waveform_per_tp,_ = apply_drift_correction_basic(pairs, did, session_switch, avg_centroid, avg_waveform_per_tp)
+    elif len(pairs)==0:
+        print('No pairs across sessions to perform drift correction.')
+    return avg_waveform_per_tp
+
 
 def get_total_score(scores_to_include, param):
     """

{unitmatchpy-3.2.8 → unitmatchpy-3.3.0}/UnitMatchPy/param_functions.py

@@ -175,6 +175,7 @@ def decay_and_average_waveform(waveform, channel_pos, good_idx, max_site, max_si
     new_peak_loc = param['peak_loc']
     waveidx = param['waveidx']
     channel_radius = param['channel_radius']
+    maxfev = param.get('curve_fit_maxfev', 10000)
     session_id = clus_info['session_id']
 
     spatial_decay_fit = np.zeros((n_units,2))
@@ -196,7 +197,14 @@ def decay_and_average_waveform(waveform, channel_pos, good_idx, max_site, max_si
             dist_to_max_chan = dist_to_max_chan[dist_to_max_chan != 0]
 
             # there is variation in how different programming languages/options fit to a curve
-            popt, pcurve = sp.optimize.curve_fit(exponential_func, dist_to_max_chan.T , tmp_amp, p0 = (np.max(tmp_amp), 0.05), method = 'trf', maxfev=2000)
+            popt, pcurve = sp.optimize.curve_fit(
+                exponential_func,
+                dist_to_max_chan.T,
+                tmp_amp,
+                p0=(np.max(tmp_amp), 0.05),
+                method='trf',
+                maxfev=maxfev,
+            )
             #popt, pcurve = sp.optimize.least_squares(exponential_func, Dist2MaxChan, TmpAmp, p0 = (np.max(TmpAmp), 0.05) )
 
             spatial_decay_fit[i,cv] = popt[1]
@@ -406,4 +414,4 @@ def get_avg_waveform_per_tp(waveform, channel_pos, d_10, max_site_mean, amplitud
                 avg_waveform_per_tp[dim, uid, good_wave_idxs[uid,:,cv].astype(bool), cv] = gaussian_filter(avg_waveform_per_tp[dim, uid, good_wave_idxs[uid,:,cv].astype(bool), cv], 1, radius = 2, axes = 0)
         
     return waveform_duration, avg_waveform_per_tp, good_wave_idxs
-        
+        

unitmatchpy-3.3.0/UnitMatchPy.egg-info/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: UnitMatchPy
+Version: 3.3.0
+Summary: Automatic matching of neurons across sessions
+Author: Enny van Beest, Célian Bimbard, Suyash Agarwal, Wentao Qiu
+License: CC BY-NC-SA 4.0 International
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.13,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.0,>=1.21
+Requires-Dist: scipy<2.0,>=1.9
+Requires-Dist: pandas<3.0,>=1.5
+Requires-Dist: matplotlib<4.0,>=3.6
+Requires-Dist: joblib<2.0,>=1.2
+Requires-Dist: tqdm<5.0,>=4.64
+Requires-Dist: h5py<4.0,>=3.8
+Requires-Dist: scikit-learn<2.0,>=1.2
+Requires-Dist: mtscomp
+Requires-Dist: torch<3.0,>=2.1
+Provides-Extra: full
+Requires-Dist: mat73<1.0,>=0.62; extra == "full"
+Requires-Dist: spikeinterface<0.120,>=0.100; extra == "full"
+Provides-Extra: notebooks
+Requires-Dist: ipykernel<7,>=6; extra == "notebooks"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# UnitMatchPy (UMPy) and DeepUnitMatch (DUM)
+
+This repository contains:
+- **UnitMatchPy (UMPy)**: automatic matching of neurons across sessions (Python package).
+- **DeepUnitMatch (DUM)**: DeepUnitMatch pipeline and demos (see preprint below).
+
+## References
+
+- **UnitMatch (UMPy):** https://www.nature.com/articles/s41592-024-02440-1
+- **DeepUnitMatch (DUM) preprint:** https://www.biorxiv.org/content/10.64898/2026.01.30.702777v1
+
+## Versions
+
+- **UnitMatchPy version:** `3.2.9` (from `pyproject.toml`)
+- **DeepUnitMatch:** code lives under `DeepUnitMatch/` (see **DeepUnitMatch (DUM)** section)
+
+## Installation
+
+`pip install` (including `pip install -e .`) installs into whatever Python environment your `pip` points to (system Python, a conda env, or a virtualenv). `pip` does **not** create or name environments.
+
+We recommend using Anaconda/Miniconda (conda) to create an isolated environment first:
+
+```bash
+# Create a new environment (pick any name you like; example: UMPy)
+conda create -n UMPy python=3.11 pip #(press y when prompted)
+conda activate UMPy
+```
+
+Then install using pip (options below).
+
+### Option A: Install the released package (PyPI)
+
+```bash
+pip install UnitMatchPy
+```
+
+Optional extras (heavier dependencies used by some notebooks and integration with SpikeInterface):
+
+```bash
+pip install "UnitMatchPy[full,notebooks]"
+```
+
+### Option B: Install a local, editable copy (for development / modified code)
+
+First, open a terminal and navigate to this folder (the one containing `pyproject.toml`). The `pip install -e` command must be run from here:
+
+```bash
+# Windows (PowerShell)
+cd $HOME\Documents\GitHub\DeepUnitMatch\UnitMatchPy
+
+# macOS / Linux
+cd ~/Documents/GitHub/DeepUnitMatch/UnitMatchPy
+```
+
+```bash
+pip install -e .
+```
+
+Optional extras (e.g. if you'd like to run the notebooks or integrate with SpikeInterface):
+
+```bash
+pip install -e ".[full,notebooks]"
+```
+
+## Demo notebooks
+
+All demo notebooks are in `Demo Notebooks/`.
+
+### Run UnitMatchPy (UMPy)
+
+To run UMPy, standard spike sorting data is needed (channel positions and extracted raw waveforms for each unit). Waveforms can be extracted externally (e.g. [BombCell](https://github.com/Julie-Fabre/bombcell)) or using the demo notebooks:
+- `Demo Notebooks/extract_raw_data_demo.ipynb` (compressed `.cbin`/`.ch` or raw)
+- `Demo Notebooks/extract_raw_data_demo_open_ephys.ipynb` (Open Ephys)
+- `Demo Notebooks/UMPy_spike_interface_demo.ipynb` ([SpikeInterface](https://spikeinterface.readthedocs.io/en/latest/) workflow)
+
+Example notebooks:
+- `Demo Notebooks/UMPy_example.ipynb` (recommended starting point)
+- `Demo Notebooks/UMPy_example_detailed.ipynb` (more modular / advanced)
+
+The GUI is an optional step to curate and explore UnitMatch outputs; see `Demo Notebooks/GUI_Reference_Guide.md` for usage tips and shortcuts.
+
+## DeepUnitMatch (DUM)
+
+To try the DeepUnitMatch version, start with:
+- `Demo Notebooks/DeepUnitMatch.ipynb`
+
+If you want to train / fine-tune a model on your own data, see:
+- `Demo Notebooks/DUM_training.ipynb`
+
+Important note: DeepUnitMatch current trained model is for Npix 2.0 4-shank only. You will need to train a new model with your own data if you have any other type of probe. (For example, Mouse2 from the figshare data is a Npix 1 dataset, you'll notice the trained model won't give good results on this mouse for that reason.)

{unitmatchpy-3.2.8 → unitmatchpy-3.3.0}/pyproject.toml

@@ -4,12 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "UnitMatchPy"
-version = "3.2.8"  # bump on each release 
+version = "3.3.0"  # bump on each release 
 description = "Automatic matching of neurons across sessions"
 readme = "README.md"         # keep a README.md inside UnitMatchPy/
-requires-python = ">=3.9"
+requires-python = ">=3.9,<3.13"
 authors = [
   { name = "Enny van Beest" },
+  { name = "Célian Bimbard" },
   { name = "Suyash Agarwal" },
   { name = "Wentao Qiu" },
 ]

unitmatchpy-3.2.8/PKG-INFO

@@ -1,69 +0,0 @@
-Metadata-Version: 2.4
-Name: UnitMatchPy
-Version: 3.2.8
-Summary: Automatic matching of neurons across sessions
-Author: Enny van Beest, Suyash Agarwal, Wentao Qiu
-License: CC BY-NC-SA 4.0 International
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy<2.0,>=1.21
-Requires-Dist: scipy<2.0,>=1.9
-Requires-Dist: pandas<3.0,>=1.5
-Requires-Dist: matplotlib<4.0,>=3.6
-Requires-Dist: joblib<2.0,>=1.2
-Requires-Dist: tqdm<5.0,>=4.64
-Requires-Dist: h5py<4.0,>=3.8
-Requires-Dist: scikit-learn<2.0,>=1.2
-Requires-Dist: mtscomp
-Requires-Dist: torch<3.0,>=2.1
-Provides-Extra: full
-Requires-Dist: mat73<1.0,>=0.62; extra == "full"
-Requires-Dist: spikeinterface<0.120,>=0.100; extra == "full"
-Provides-Extra: notebooks
-Requires-Dist: ipykernel<7,>=6; extra == "notebooks"
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: mypy; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Dynamic: license-file
-
-# Unit Match - Python
-
-## Run UMPy
-
-To run UMPy standard spike sorting data is needed; channel positions and 2 extracted raw waveforms for each unit. This can be calculated externally [BombCell](https://github.com/Julie-Fabre/bombcell) or using *extract_raw_demo.ipynb* to extract these waveforms from compressed data (.cbin and .ch) or raw data. There is also a [Spike Interface](https://spikeinterface.readthedocs.io/en/latest/) integrated notebook *UMPy_spike_interface_demo.ipynb* which uses spike interface to get this data.
-Be careful not to mix and match the different ways of extracting raw waveforms, as there are difference between the methods.
-
-There are to example notebooks for running UMPy *UMPy_example.ipynb* and *UMPy_example_detailed.ipynb*. These notebooks will guide you through running Unit Match all you need to supply is paths to the data. *UMPy_example.ipynb* is recommended to use first as it is simpler, however *UMPy_example_detailed.ipynb* may be useful in unique cases as it is more modular.
-
-The GUI is a optional step to curated and investigate the information Unit Match has calculated; for efficient usage of the GUI please look at *GUI_Reference_Guide.md* in the Demo Notebooks folder.
-
-## Dependencies
-
-This version relies on many core python packages: [numpy](https://numpy.org/), [scipy](https://scipy.org/), [JobLib](https://joblib.readthedocs.io/en/stable/), [pandas](https://pandas.pydata.org/), [tkinter](https://docs.python.org/3/library/tkinter.html) and [matplotlib](https://matplotlib.org/). All of these libaries come with a [Anaconda](https://www.anaconda.com/download/) version of python. 
-For extracting raw data, the library [mtscomp](https://github.com/int-brain-lab/mtscomp) is needed, and can be installed by `pip install mtscomp`.
-
-
-## Installation 
-
-After creating an python environment
-
-```
-conda create --name UnitMatch python==3.9 
-conda activate UnitMatch
-```
-
-You can install UnitMatchPy with pip. It will automatically install all the dependencies.
-
-```
-pip install UnitMatchPy
-```