### Install SpikeInterface

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/load_data.ipynb

Install SpikeInterface with the full suite of dependencies to handle various data formats.

```bash
pip install spikeinterface[full]
```

--------------------------------

### Install and Launch Kilosort4 GUI

Source: https://context7.com/mouseland/kilosort/llms.txt

Install Kilosort4 with GUI dependencies and launch the interactive GUI. The GUI facilitates data loading, parameter configuration, and result visualization.

```bash
pip install kilosort[gui]
```

```bash
python -m kilosort
```

```bash
cd /data/recording/kilosort4
phy template-gui params.py
```

--------------------------------

### Install Minimal Kilosort Version

Source: https://github.com/mouseland/kilosort/blob/main/README.md

Install only the core Kilosort package without the GUI.

```bash
python -m pip install kilosort
```

--------------------------------

### run_kilosort with multi-shank probes

Source: https://context7.com/mouseland/kilosort/llms.txt

This example shows how to sort data from multi-shank probes by specifying the `shank_idx` parameter, which saves results for each shank into separate subdirectories.

```APIDOC
## `run_kilosort` with multi-shank probes

Use `shank_idx` to sort individual shanks (or all shanks sequentially) from a multi-shank probe. Results for each shank are saved to separate subdirectories.

```python
from kilosort import run_kilosort

settings = {'n_chan_bin': 385, 'fs': 30000}

# Sort all 4 shanks of a Neuropixels 2.0 4-shank probe sequentially
ops, st, clu, tF, Wall, similar_templates, is_ref, est_contam_rate, kept_spikes = \
    run_kilosort(
        settings=settings,
        filename='/data/np2_recording.bin',
        probe_name='neuropixels2_kilosortChanMap.mat',
        shank_idx=[0, 1, 2, 3],   # sorts each shank; results in shank_0/, shank_1/, ...
        results_dir='/data/sorted',
    )
```
```

--------------------------------

### Install Kilosort with GUI

Source: https://github.com/mouseland/kilosort/blob/main/README.md

Install Kilosort along with its graphical user interface. For zsh servers, use quotes around the package name.

```bash
python -m pip install kilosort[gui]
```

```bash
python -m pip install "kilosort[gui]"
```

--------------------------------

### Download Example Data with Progress Bar

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/kilosort4.ipynb

Downloads a zip-compressed electrophysiological recording using a custom progress bar. Unzips the data and removes the archive. Use this to download the cropped dataset for testing.

```python
import urllib.request
from tqdm import tqdm
import zipfile
from pathlib import Path

class DownloadProgressBar(tqdm):
    """ from https://stackoverflow.com/a/53877507 """
    def update_to(self, b=1, bsize=1, tsize=None):
        if tsize is not None:
            self.total = tsize
        self.update(b * bsize - self.n)

def download_url(url, output_path):
    # Download zip-compressed data file.
    zip_file = Path(output_path).with_suffix('.zip')
    with DownloadProgressBar(unit='B', unit_scale=True,
                             miniters=1, desc=url.split('/')[-1]) as t:
        urllib.request.urlretrieve(url, filename=zip_file, reporthook=t.update_to)
    # Unzip to specified `output_path`.
    with zipfile.ZipFile(zip_file, "r") as zip_ref:
        zip_ref.extractall(output_path.parent)
    # Remove zip archive after unzipping.
    zip_file.unlink()

## FULL DATASET (download locally then decompress)
# compressed using mtscomp (https://github.com/int-brain-lab/mtscomp)
# URL = 'https://ibl.flatironinstitute.org/public/mainenlab/Subjects/ZFM-02370/2021-04-28/001/raw_ephys_data/probe00/_spikeglx_ephysData_g0_t0.imec0.ap.e510da60-53e0-4e00-b369-3ea16c45623a.cbin'

## CROPPED DATASET
URL = 'https://osf.io/download/67effd64f74150d8738b7f34/'
download_url(URL, Path.home())
```

--------------------------------

### Clone Kilosort Repository and Install

Source: https://github.com/mouseland/kilosort/blob/main/README.md

Clone the Kilosort repository and install it in editable mode. This command also installs pytest and the CUDA version of PyTorch using the provided environment file.

```bash
git clone git@github.com:MouseLand/Kilosort.git
conda env create -f environment.yml
conda activate kilosort
pip install -e Kilosort[gui]
```

--------------------------------

### Install mtscomp

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/benchmark.ipynb

Install the mtscomp package using pip. This is required for decompressing binary electrophysiology data files.

```bash
pip install mtscomp
```

--------------------------------

### Install Kilosort4

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/kilosort4.ipynb

Install the Kilosort4 package using pip. This command ensures you have the latest version.

```python
!pip install kilosort
```

--------------------------------

### Install PyTorch with CUDA 12.4

Source: https://github.com/mouseland/kilosort/blob/main/README.md

Use this command to install PyTorch with CUDA 12.4 support on Linux and Windows. Ensure your environment is activated.

```bash
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
```

--------------------------------

### Download Example Data

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/basic_example.ipynb

Downloads a cropped electrophysiological recording and associated channel maps. Ensure the SAVE_PATH is updated if you wish to download to a specific location. This function handles the download and extraction of a zip-compressed data file.

```python
import urllib.request
import zipfile
from pathlib import Path
from tqdm import tqdm

from kilosort.utils import DOWNLOADS_DIR


# NOTE: Be sure to update this filepath if you want the data downloaded to
#       a specific location.
SAVE_PATH = DOWNLOADS_DIR / '.test_data' / 'ZFM-02370_mini.imec0.ap.short.bin'

class DownloadProgressBar(tqdm):
    """ from https://stackoverflow.com/a/53877507 """
    def update_to(self, b=1, bsize=1, tsize=None):
        if tsize is not None:
            self.total = tsize
        self.update(b * bsize - self.n)

def download_url(url, output_path):
    # Download zip-compressed data file.
    zip_file = Path(output_path).with_suffix('.zip')
    with DownloadProgressBar(unit='B', unit_scale=True,
                             miniters=1, desc=url.split('/')[-1]) as t:
        urllib.request.urlretrieve(url, filename=zip_file, reporthook=t.update_to)
    # Unzip to specified `output_path`.
    with zipfile.ZipFile(zip_file, "r") as zip_ref:
        zip_ref.extractall(output_path.parent)
    # Remove zip archive after unzipping.
    zip_file.unlink()


## CROPPED DATASET
URL = 'https://osf.io/download/67effd64f74150d8738b7f34/'
download_url(URL, SAVE_PATH)
```

```python
from kilosort.utils import download_probes
download_probes()
```

--------------------------------

### Initialize Unit Labels

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/good_unit_criteria.ipynb

Sets up the initial boolean array for 'good' units, either by copying Kilosort4's default 'is_ref' labels or by starting with all units marked as potentially good.

```python
# Option 1: Use existing labels as a starting point.
#           KS4 assigns "good" where is_ref is True, and "mua" otherwise.
label_good = is_ref.copy()

# Option 2: Ignore KS4's labels and only use your own criteria.
# label_good = np.ones(cluster_labels.size)
```

--------------------------------

### Install PyTorch for GPU (CUDA 11.8)

Source: https://github.com/mouseland/kilosort/blob/main/README.md

Install the GPU-enabled version of PyTorch. This requires uninstalling the CPU version first. Ensure your CUDA version is compatible.

```bash
pip uninstall torch
```

```bash
pip3 install torch --index-url https://download.pytorch.org/whl/cu118
```

--------------------------------

### run_kilosort with concatenated files and bad channel exclusion

Source: https://context7.com/mouseland/kilosort/llms.txt

This example demonstrates how to run Kilosort on multiple concatenated binary files and exclude specified bad channels from the analysis.

```APIDOC
## `run_kilosort` with concatenated files and bad channel exclusion

Pass a list of filenames to treat them as one contiguous recording; pass `bad_channels` to exclude noisy electrodes.

```python
from kilosort import run_kilosort
from pathlib import Path

files = [
    Path('/data/session1/recording.bin'),
    Path('/data/session2/recording.bin'),
]

settings = {
    'n_chan_bin': 385,
    'fs': 30000,
    'nblocks': 5,         # non-rigid drift correction (good for 1-shank Neuropixels)
    'Th_universal': 9,
    'Th_learned': 7,      # slightly lower to catch more spikes
    'duplicate_spike_ms': 0.25,  # remove duplicate spikes within 0.25ms
}

ops, st, clu, tF, Wall, similar_templates, is_ref, est_contam_rate, kept_spikes = \
    run_kilosort(
        settings=settings,
        filename=files,
        probe_name='neuropixPhase3B1_kilosortChanMap.mat',
        bad_channels=[191, 384],    # exclude broken or reference channels
        results_dir='/data/sorted_output',
        save_preprocessed_copy=True,  # save drift-corrected temp_wh.dat for Phy
    )
```
```

--------------------------------

### run_kilosort with a file_object (in-memory / non-standard formats)

Source: https://context7.com/mouseland/kilosort/llms.txt

This example shows how to use `file_object` to sort data that is already loaded into memory or accessed through a custom array interface, bypassing the need for a physical `.bin` file.

```APIDOC
## `run_kilosort` with a `file_object` (in-memory / non-standard formats)

Use `file_object` to sort data already loaded into memory or accessed through a custom array interface (e.g., via SpikeInterface or a NumPy memmap), without requiring a real `.bin` file.

```python
import numpy as np
from kilosort import run_kilosort
from pathlib import Path

# Simulate a 64-channel, 30s recording at 30kHz (int16)
n_samples = 30000 * 30
n_chans   = 64
data = np.random.randint(-100, 100, size=(n_chans, n_samples), dtype=np.int16)

# file_object must support shape, dtype, and array-like indexing
# A dummy filename is required even though data is not read from it
dummy_path = Path('/tmp/dummy.bin')
dummy_path.touch()

settings = {'n_chan_bin': 64, 'fs': 30000}

probe = {
    'chanMap':  np.arange(64, dtype=np.int32),
    'xc':       np.zeros(64, dtype=np.float32),
    'yc':       np.arange(64, dtype=np.float32) * 20,
    'kcoords':  np.zeros(64, dtype=np.float32),
    'n_chan':   64,
}

ops, st, clu, tF, Wall, similar_templates, is_ref, est_contam_rate, kept_spikes = \
    run_kilosort(
        settings=settings,
        filename=dummy_path,
        probe=probe,
        file_object=data,     # array with shape (n_chans, n_samples)
    )

print(f"Spikes found: {len(st)}, Clusters: {clu.max()+1}")
```
```

--------------------------------

### Load Intan Data with SpikeInterface

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/load_data.ipynb

Load Intan data using `read_intan`. You will need to select the appropriate data stream using `stream_id`. If `stream_id` is not specified, an error message will guide you on stream correspondence.

```python
from spikeinterface.extractors import read_intan
# NOTE: You will need to select the appropriate data stream. If you run without
#       specifying `stream_id`, you will get an error message explaining what
#       each stream corresponds to.
filepath = Path(".../intan_rhs_test_1.rhs")
recording = read_intan(filepath, stream_id='0')
```

--------------------------------

### Run Kilosort GUI

Source: https://github.com/mouseland/kilosort/wiki/1.-The-GUI

Navigate to the Kilosort directory and execute the 'kilosort' command to launch the GUI. Ensure you are in the correct directory.

```bash
>> cd \my\kilosort2\directory\
>> kilosort
```

--------------------------------

### Load Sorting Results and Set Up Paths

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/good_unit_criteria.ipynb

Initializes paths for results and backups, loads sorting data, and extracts essential parameters like cluster labels and sampling rate.

```python
from pathlib import Path
import shutil

import numpy as np

from kilosort.run_kilosort import load_sorting

# Path to load existing sorting results from.
results_dir = Path('c:/users/jacob/.kilosort/.test_data/kilosort4/')
# Paths where new labels will be saved for use with Phy.
save_1 = results_dir / 'cluster_KSLabel.tsv'
save_2 = results_dir / 'cluster_group.tsv'
# Save a backup of KS4's original labels before overwriting (recommended).
shutil.copyfile(save_1, results_dir / 'cluster_KSLabel_backup.tsv')

# Load sorting results
ops, st, clu, similar_templates, is_ref, est_contam_rate, kept_spikes = \
    load_sorting(results_dir)

cluster_labels = np.unique(clu)  # integer label for each cluster
fs = ops['fs']                   # sampling rate
```

--------------------------------

### Launch Kilosort GUI

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/load_data.ipynb

Launch the Kilosort GUI to visually inspect data and probe loading, and to adjust settings before running the analysis.

```bash
kilosort -m kilosort
```

--------------------------------

### Run Kilosort GUI

Source: https://github.com/mouseland/kilosort/blob/main/README.md

Launch the Kilosort graphical user interface to load data, select probe configurations, and run the analysis pipeline.

```bash
python -m kilosort
```

--------------------------------

### Run Kilosort4 with Minimal Settings

Source: https://context7.com/mouseland/kilosort/llms.txt

This snippet demonstrates the minimal required settings to run the full Kilosort4 spike sorting pipeline on a Neuropixels recording. Ensure `n_chan_bin` is set to the total number of channels in your binary file.

```python
from pathlib import Path
from kilosort import run_kilosort

# Minimal usage: sort a Neuropixels 1.0 recording (385 total channels)
settings = {
    'n_chan_bin': 385,       # REQUIRED: total channels in binary file
    'fs': 30000,             # sampling rate in Hz (default 30000)
    'Th_universal': 9,       # detection threshold for universal templates
    'Th_learned': 8,         # detection threshold for learned templates
    'nblocks': 1,            # number of drift correction blocks (0 = no drift correction)
    'batch_size': 60000,     # samples per batch (~2s at 30kHz)
    'tmin': 0,               # start of data to sort (seconds)
    'tmax': float('inf'),    # end of data to sort (seconds)
}

ops, st, clu, tF, Wall, similar_templates, is_ref, est_contam_rate, kept_spikes = \
    run_kilosort(
        settings=settings,
        filename='/data/recording/my_data.bin',
        probe_name='neuropixPhase3B1_kilosortChanMap.mat',   # from default PROBE_DIR
        results_dir='/data/recording/kilosort4',
        data_dtype='int16',     # default dtype for binary files
        do_CAR=True,            # apply common average reference (recommended)
        invert_sign=False,      # flip sign if spikes are positive-going
        save_extra_vars=True,   # also save tF and Wall to disk
    )

# Results summary
print(f"Total spikes detected: {kept_spikes.sum()}")
print(f"Total clusters: {clu.max() + 1}")
print(f"Good (refractory) units: {is_ref.sum()}")

# st[:, 0]  -> spike times in samples
# st[:, 1]  -> template index
# st[:, 2]  -> amplitude threshold used
# clu       -> cluster assignment per spike
# est_contam_rate -> per-cluster contamination fraction (< 0.2 = "good")

```

--------------------------------

### Install PyTorch Nightly with CUDA 12.8

Source: https://github.com/mouseland/kilosort/blob/main/README.md

Install nightly builds of PyTorch for newer CUDA versions like 12.8, which may be required for the latest GPUs. This is useful when stable releases do not yet support your hardware.

```bash
pip install --pre torch --index-url https://download.pytorch.org/whl/nightly/cu128
```

--------------------------------

### Enable Interactive Matplotlib Plotting

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/plotting_example.ipynb

Enables interactive plotting for 3D visualizations, allowing rotation. Requires `ipympl` to be installed.

```python
# Recommended: `pip install ipympl` then use this command to enable
#              interactive plotting, so that the 3D plot below can be rotated.
%matplotlib ipympl
```

--------------------------------

### Configure Kilosort4 Settings

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/kilosort4.ipynb

Set the data directory and number of channels before running Kilosort4. Ensure the data directory is correctly mounted.

```python
settings['data_dir'] = '/content/'
settings['n_chan_bin'] = 385
```

--------------------------------

### Kilosort4 Spike Extraction Completion

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/kilosort4.ipynb

Reports the number of spikes extracted and the total time taken for this step. It also indicates the start of the first clustering phase.

```text
197494 spikes extracted in  59.16s; total  117.08s

First clustering
```

--------------------------------

### kilosort.run_kilosort.initialize_ops

Source: https://github.com/mouseland/kilosort/blob/main/docs/api.md

Packages settings and probe information into a single ops dictionary for Kilosort operations.

```APIDOC
## kilosort.run_kilosort.initialize_ops(settings, probe, data_dtype, do_CAR, invert_sign, device, save_preprocessed_copy, gui_mode=False)

### Description
Package settings and probe information into a single ops dictionary.

### Method
Call

### Parameters
#### Path Parameters
- **settings** (any) - Description not available
- **probe** (any) - Description not available
- **data_dtype** (any) - Description not available
- **do_CAR** (any) - Description not available
- **invert_sign** (any) - Description not available
- **device** (any) - Description not available
- **save_preprocessed_copy** (any) - Description not available
- **gui_mode** (bool, optional) - Description not available. Defaults to False.
```

--------------------------------

### Inspect and Compare Kilosort Settings

Source: https://context7.com/mouseland/kilosort/llms.txt

Access default parameter values and identify settings that differ from defaults. 'n_chan_bin' must be passed directly if not in DEFAULT_SETTINGS.

```python
from kilosort.parameters import DEFAULT_SETTINGS, compare_settings

print(DEFAULT_SETTINGS)

my_settings = {
    'n_chan_bin': 385,
    'fs': 30000,
    'Th_learned': 6,
    'nblocks': 5,
    'batch_size': 60000,
}
modified, extra_keys = compare_settings(my_settings)
print(modified)
print(extra_keys)
```

--------------------------------

### Kilosort4 Preprocessing and Drift Computation

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/kilosort4.ipynb

Indicates the time taken for computing preprocessing filters and the start of drift computation. It also notes that universal templates are being re-computed from the data.

```text
Preprocessing filters computed in  1.50s; total  1.51s

computing drift
Re-computing universal templates from data.
```

--------------------------------

### run_kilosort — Run the full spike sorting pipeline

Source: https://context7.com/mouseland/kilosort/llms.txt

The main entry point for sorting. Runs preprocessing, drift correction, spike detection, clustering, and saves results in Phy-compatible format. Requires `n_chan_bin` in settings.

```APIDOC
## `run_kilosort` — Run the full spike sorting pipeline

### Description
The main entry point for sorting. Runs preprocessing (high-pass filtering, whitening, common average reference), drift correction, two-stage spike detection (universal templates then learned templates), graph-based clustering, duplicate spike removal, and saves all results to disk in Phy-compatible format. The only required setting is `n_chan_bin`.

### Parameters
#### Path Parameters
- **filename** (string) - Required - Path to the binary data file.
- **probe_name** (string) - Optional - Name of the probe file (e.g., '.mat', '.prb', '.json').
- **results_dir** (string) - Optional - Directory to save results.

#### Query Parameters
None explicitly documented.

#### Request Body
None explicitly documented.

#### Settings Dictionary
- **n_chan_bin** (int) - Required - Total channels in the binary file.
- **fs** (int) - Optional - Sampling rate in Hz (default: 30000).
- **Th_universal** (int) - Optional - Detection threshold for universal templates.
- **Th_learned** (int) - Optional - Detection threshold for learned templates.
- **nblocks** (int) - Optional - Number of drift correction blocks (0 = no drift correction).
- **batch_size** (int) - Optional - Samples per batch.
- **tmin** (float) - Optional - Start of data to sort (seconds).
- **tmax** (float) - Optional - End of data to sort (seconds).

#### Other Parameters
- **probe** (dict) - Optional - A dictionary defining the probe geometry.
- **data_dtype** (string) - Optional - Data type of the binary file (default: 'int16').
- **do_CAR** (bool) - Optional - Apply common average reference (recommended, default: True).
- **invert_sign** (bool) - Optional - Flip sign if spikes are positive-going (default: False).
- **save_extra_vars** (bool) - Optional - Also save tF and Wall to disk (default: False).

### Returns
- **ops** (object) - Kilosort operations object.
- **st** (numpy.ndarray) - Spike times and template indices.
- **clu** (numpy.ndarray) - Cluster assignment per spike.
- **tF** (numpy.ndarray) - Template features.
- **Wall** (numpy.ndarray) - Wall time information.
- **similar_templates** (numpy.ndarray) - Information about similar templates.
- **is_ref** (numpy.ndarray) - Boolean array indicating good (refractory) units.
- **est_contam_rate** (numpy.ndarray) - Per-cluster contamination fraction.
- **kept_spikes** (numpy.ndarray) - Boolean array indicating kept spikes.

### Request Example
```python
from pathlib import Path
from kilosort import run_kilosort

settings = {
    'n_chan_bin': 385,       # REQUIRED: total channels in binary file
    'fs': 30000,             # sampling rate in Hz (default 30000)
    'Th_universal': 9,       # detection threshold for universal templates
    'Th_learned': 8,         # detection threshold for learned templates
    'nblocks': 1,            # number of drift correction blocks (0 = no drift correction)
    'batch_size': 60000,     # samples per batch (~2s at 30kHz)
    'tmin': 0,               # start of data to sort (seconds)
    'tmax': float('inf'),    # end of data to sort (seconds)
}

ops, st, clu, tF, Wall, similar_templates, is_ref, est_contam_rate, kept_spikes = \
    run_kilosort(
        settings=settings,
        filename='/data/recording/my_data.bin',
        probe_name='neuropixPhase3B1_kilosortChanMap.mat',   # from default PROBE_DIR
        results_dir='/data/recording/kilosort4',
        data_dtype='int16',     # default dtype for binary files
        do_CAR=True,            # apply common average reference (recommended)
        invert_sign=False,      # flip sign if spikes are positive-going
        save_extra_vars=True,   # also save tF and Wall to disk
    )

# Results summary
print(f"Total spikes detected: {kept_spikes.sum()}")
print(f"Total clusters: {clu.max() + 1}")
print(f"Good (refractory) units: {is_ref.sum()}")
```

### Response
#### Success Response (200)
Returns the results of the spike sorting pipeline as described in the 'Returns' section.

#### Response Example
```
Total spikes detected: 150000
Total clusters: 128
Good (refractory) units: 100
```
```

--------------------------------

### Load Probe and Run Kilosort

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/make_probe.ipynb

Load a probe configuration file and then use it to run Kilosort. This is useful for analyses requiring specific electrode geometries.

```python
p = load_probe('.../test_prb.prb')
results = run_kilosort(..., probe=p)
```

--------------------------------

### Kilosort4 Spike Extraction (Cluster Waveforms) Completion

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/kilosort4.ipynb

Reports the number of spikes extracted using cluster waveforms and the total time taken. It also indicates the start of the final clustering phase.

```text
290888 spikes extracted in  17.93s; total  162.49s

Final clustering
```

--------------------------------

### Kilosort4 First Clustering Completion

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/kilosort4.ipynb

Reports the number of clusters found and the total time taken for the first clustering phase. It also indicates the start of extracting spikes using cluster waveforms.

```text
447 clusters found, in  27.48s; total  144.55s

Extracting spikes using cluster waveforms
```

--------------------------------

### View Results with Phy

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/load_data.ipynb

After running Kilosort, use the Phy GUI to explore the spike-sorting results. This command opens the template GUI, pointing to the Kilosort parameters file.

```bash
phy template-gui <DATA_DIRECTORY>/kilosort4/params.py
```

--------------------------------

### Integrate Kilosort with Phy GUI

Source: https://github.com/mouseland/kilosort/blob/main/README.md

Run this command within your activated Phy environment to launch the Phy template GUI, using Kilosort's output parameters.

```bash
phy template-gui params.py
```

--------------------------------

### Load and Save Probe Configurations

Source: https://context7.com/mouseland/kilosort/llms.txt

Load probe configurations from a JSON file or save a custom probe dictionary. Ensure the suffix is '.json' when saving to avoid RuntimeWarnings.

```python
from kilosort.io import load_probe, save_probe
import numpy as np

probe_json = load_probe('/path/to/my_probe.json')

custom_probe = {
    'chanMap':  np.arange(32, dtype=np.int32),
    'xc':       np.zeros(32, dtype=np.float32),
    'yc':       np.arange(32, dtype=np.float32) * 50.0,
    'kcoords':  np.zeros(32, dtype=np.float32),
    'n_chan':   32,
}
save_probe(custom_probe, '/path/to/my_probe.json')
```

--------------------------------

### Kilosort4 Final Clustering and Merging

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/kilosort4.ipynb

Reports the number of clusters found in the final clustering and the total time taken. It also indicates the start of merging clusters and the number of units found with good refractory periods.

```text
416 clusters found, in  30.28s; total  192.77s

Merging clusters
405 units found, in  0.72s; total  193.49s

Saving to phy and computing refractory periods
259 units found with good refractory periods

Total runtime: 194.90s = 00:03:14 h:m:s
```

--------------------------------

### Run Kilosort Algorithm

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/basic_example.ipynb

Executes the Kilosort spike-sorting algorithm. The 'n_chan_bin' setting is required and must match the total number of channels in the binary file. Other settings can be found in `kilosort.run_kilosort.default_settings`. Optionally, set `save_preprocessed_copy=True` to save intermediate processing steps.

```python
from kilosort import run_kilosort

# NOTE: 'n_chan_bin' is a required setting, and should reflect the total number
#       of channels in the binary file. For information on other available
#       settings, see `kilosort.run_kilosort.default_settings`.
settings = {'filename': SAVE_PATH, 'n_chan_bin': 385}

ops, st, clu, tF, Wall, similar_templates, is_ref, est_contam_rate, kept_spikes = \
    run_kilosort(
        settings=settings, probe_name='NeuroPix1_default.mat',
        # save_preprocessed_copy=True
        )
```

--------------------------------

### Initialize Kilosort4 Settings

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/kilosort4.ipynb

Import and access the default settings for Kilosort4. These settings can be modified before running the sorting process.

```python
from kilosort import run_kilosort, DEFAULT_SETTINGS

settings = DEFAULT_SETTINGS
```

--------------------------------

### Probe Loading and Saving

Source: https://context7.com/mouseland/kilosort/llms.txt

Utilities for loading probe configurations from JSON files and saving custom probe dictionaries.

```APIDOC
## `io.load_probe` / `io.save_probe`

Load probe configurations from a JSON file or save a custom probe dictionary.

```python
from kilosort.io import load_probe, save_probe
import numpy as np

# Load from a .json file (saved by save_probe)
probe_json = load_probe('/path/to/my_probe.json')

# Save a custom probe dict for reuse
custom_probe = {
    'chanMap':  np.arange(32, dtype=np.int32),
    'xc':       np.zeros(32, dtype=np.float32),
    'yc':       np.arange(32, dtype=np.float32) * 50.0,
    'kcoords':  np.zeros(32, dtype=np.float32),
    'n_chan':   32,
}
save_probe(custom_probe, '/path/to/my_probe.json')
# Raises RuntimeWarning if suffix is not .json
```
```

--------------------------------

### Initialize Kilosort4 Probe Dictionary Variables

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/make_probe.ipynb

Initializes the NumPy arrays and integer for the Kilosort4 probe dictionary. 'chanMap' represents channel indices, 'kcoords' denotes shank or group, and 'n_chan' is the total number of channels.

```python
import numpy as np

chanMap = np.arange(128)
kcoords = np.zeros(128)
n_chan = 128
```

--------------------------------

### Load Blackrock Data with SpikeInterface

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/load_data.ipynb

Load Blackrock data using `read_blackrock`. Ensure you provide the path to the nsX file, not the .nev file.

```python
from spikeinterface.extractors import read_blackrock
# Provide path to nsX file, not nev file.
filepath = Path(".../file_spec_3_0.ns6")
recording = read_blackrock(filepath)
```

--------------------------------

### Download Probe Maps

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/kilosort4.ipynb

Download the channel maps required for Kilosort4 to correctly interpret probe configurations. This is typically done once.

```python
# download channel maps for probes
from kilosort.utils import download_probes
download_probes()
```

--------------------------------

### Export Probe to .prb File using ProbeInterface

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/load_data.ipynb

Export a probe configuration to a .prb file compatible with Kilosort4. A `ProbeGroup` wrapper is necessary even for a single probe. Ensure channel indices are set for successful export.

```python
from probeinterface import ProbeGroup, write_prb

probe = ...  # From SpikeInterface tutorial, or recording.get_probe()

# Multiple probes can be added to a ProbeGroup. We only have one, but a
# ProbeGroup wrapper is still necessary for `write_prb` to work.
pg = ProbeGroup()
pg.add_probe(probe)
# CHANGE THIS PATH to wherever you want to save your probe file.
write_prb('.../test_prb.prb', pg)
```

--------------------------------

### Load SpikeGLX Data with SpikeInterface

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/load_data.ipynb

Load SpikeGLX data directly from the .bin file. This method is recommended as the data is already in binary format and compatible with Kilosort 4.

```python
# NOTE: You do not need to load SpikeGLX data this way. It is already saved in
#       binary format, so you should just point Kilosort 4 to the .bin file.
from spikeinterface.extractors import read_spikeglx
# Provide path to directory containing .bin file.
filepath = Path(".../TEST_20210920_0_g0/")
recording = read_spikeglx(filepath)
```

--------------------------------

### Run Kilosort with Multi-Shank Probes

Source: https://context7.com/mouseland/kilosort/llms.txt

Use `shank_idx` to sort individual shanks or all shanks sequentially from a multi-shank probe. Results for each shank are saved to separate subdirectories.

```python
from kilosort import run_kilosort

settings = {'n_chan_bin': 385, 'fs': 30000}

# Sort all 4 shanks of a Neuropixels 2.0 4-shank probe sequentially
ops, st, clu, tF, Wall, similar_templates, is_ref, est_contam_rate, kept_spikes = \
    run_kilosort(
        settings=settings,
        filename='/data/np2_recording.bin',
        probe_name='neuropixels2_kilosortChanMap.mat',
        shank_idx=[0, 1, 2, 3],   # sorts each shank; results in shank_0/, shank_1/, ...
        results_dir='/data/sorted',
    )
```

--------------------------------

### Download Kilosort Channel Map (NP2)

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/kilosort4.ipynb

This output indicates the download progress of the NP2_kilosortChanMap.mat file, used for probe configuration.

```text
Downloading: "https://www.kilosort.org/downloads/NP2_kilosortChanMap.mat" to /root/.kilosort/probes/NP2_kilosortChanMap.mat
```

--------------------------------

### Import Kilosort Libraries and Define Paths

Source: https://github.com/mouseland/kilosort/blob/main/docs/tutorials/benchmark.ipynb

Import necessary modules from the kilosort library and define local paths for the downloaded data, results directory, data file, probe file, and ground truth file.

```python
from pathlib import Path

from kilosort import run_kilosort
from kilosort.io import load_probe, load_ops
from kilosort.bench import load_GT, load_phy, compare_recordings

# Specify paths
# NOTE: Make sure to update `download_path` to match your local directory.
download_path = Path('D:/sim_med_drift')
results_dir = download_path / 'kilosort4'
filename = download_path / 'data.bin'
probe_path = download_path / 'sim.imec0.ap_kilosortChanMap.mat'
gt_path = download_path / 'sim.imec0.ap_params.npz'
```

--------------------------------

### Load Probe Configuration File

Source: https://context7.com/mouseland/kilosort/llms.txt

Load probe geometry from `.mat`, `.prb`, or `.json` files. The returned dictionary is the standard probe format accepted by `run_kilosort`.

```python
from kilosort.io import load_probe, save_probe
from pathlib import Path
import numpy as np

# Load from a Kilosort2-style .mat file
probe = load_probe('/path/to/neuropixPhase3B1_kilosortChanMap.mat')
print(probe.keys())
# dict_keys: ['chanMap', 'xc', 'yc', 'kcoords', 'n_chan']

# chanMap  -> int32 array of channel indices (0-indexed) mapping probe contacts to binary file rows
# xc, yc   -> float32 arrays of contact x/y positions in microns
# kcoords  -> float32 array of shank index for each contact
# n_chan   -> total number of contacts
```