Overview of quality metrics and options - Julie-Fabre/bombcell GitHub Wiki

Running bombcell's quality metrics

Bombcell is available in both Python and MATLAB. Both versions share the same core functionality and output formats, making it easy to switch between them or integrate with your existing workflow.

Python Version

Bombcell organization: quality_metrics dict and param dict

The Python version is organized around two main dictionaries: quality_metrics and param.

quality_metrics is a dictionary returned by run_bombcell(). Each key is a quality metric name, and each value is a numpy array containing the metric value for each unit.
param is a dictionary created by get_default_parameters() containing parameters for computing quality metrics and classifying units.

A run-through of a typical workflow

Take a look at the demo notebooks in py_bombcell/demos/ for complete examples:

BC_demo_toy_data.ipynb - Quick start with toy data
BC_demo_spikeGLX.ipynb - SpikeGLX recordings
BC_demo_open_ephys.ipynb - OpenEphys recordings

Basic workflow:

import bombcell as bc

# 1. Set up parameters
param = bc.get_default_parameters(
    kilosort_path='/path/to/kilosort/output',
    raw_file='/path/to/raw_data.ap.bin',        # optional: for raw waveform extraction
    meta_file='/path/to/raw_data.ap.meta',      # optional: for gain/sampling rate
    kilosort_version=4                           # 4 for KS4, else for earlier versions
)

# 2. Run bombcell (extracts waveforms, computes metrics, classifies units)
quality_metrics, param, unit_type, unit_type_string = bc.run_bombcell(
    ks_dir='/path/to/kilosort/output',
    save_path='/path/to/save/results',
    param=param
)

# 3. Explore results with the GUI
bc.unit_quality_gui(
    kilosort_path='/path/to/kilosort/output',
    save_path='/path/to/save/results'
)

Plotting quality metrics

# Enable summary plots (on by default)
param["plotGlobal"] = True    # Summary histograms and upset plots
param["plotDetails"] = False  # Per-unit detailed plots (use sparingly)
param["savePlots"] = True     # Save plots to disk
param["plotsSaveDir"] = "/path/to/plots"  # Custom save location

The GUI provides interactive exploration of units and their quality metrics:

# Interactive GUI for browsing units
bc.unit_quality_gui(kilosort_path, save_path)

# Or for more control:
gui = bc.InteractiveUnitQualityGUI(kilosort_path, save_path)
gui.show()

MATLAB Version

Bombcell organization: qMetric and param structures

The MATLAB version is organized around two main structures: qMetrics and param.

qMetrics is a structure generated by bc.qm.runAllQualityMetrics. Its fields are different quality metrics, and each field contains a quality metric value for each unit.
param is a structure generated by bc.qm.qualityParamValues containing parameters for computing quality metrics and classifying units.

All Bombcell functions are packaged in namespace folders to avoid conflicts.

A run-through of a typical workflow

Take a look at gettingStarted.mlx for an interactive example.

Load ephys data:

[spikeTimes_samples, spikeTemplates, templateWaveforms, templateAmplitudes, pcFeatures, ...
    pcFeatureIdx, channelPositions] = bc.load.loadEphysData(ephysKilosortPath)

Run all quality metrics and classify cells:

[qMetric, unitType] = bc.qm.runAllQualityMetrics(param, spikeTimes_samples, spikeTemplates, ...
    templateWaveforms, templateAmplitudes, pcFeatures, pcFeatureIdx, channelPositions, savePath)

Explore with the GUI:

unitQualityGuiHandle = bc.viz.unitQualityGUI_synced(memMapData, ephysData, qMetric, forGUI, ...
    rawWaveforms, param, probeLocation, unitType, loadRawTraces)

Plotting quality metrics (MATLAB)

Set param.plotGlobal = 1 to plot summary histograms and upset plots
Set param.plotThis = 1 to plot per-unit detailed figures (generates many plots, use sparingly)

Loading and saving data (Both versions)

All Bombcell outputs are saved in the ONE format, using .npy or .parquet files for cross-language compatibility.

Output files:

_bc_parameters._bc_qMetrics.parquet - Parameters used
templates._bc_qMetrics.parquet - Quality metrics for all units
templates._bc_fractionRefractoryPeriodViolationsPerTauR.parquet - RPV across tauR values
templates._bc_rawWaveforms.npy - Extracted raw waveforms
templates._bc_rawWaveformPeakChannels.npy - Peak channels for raw waveforms
templates._bc_baselineNoiseAmplitude.npy - Baseline noise amplitudes
(optional) Unit$CLUSTER_ID$_RawSpikes.npy - Individual raw spikes (if saveMultipleRaw=True)
cluster_bc_unitType.tsv - Unit classifications for Phy integration

Loading saved results:

# Python
from bombcell.loading_utils import load_saved_metrics
param, quality_metrics = load_saved_metrics(save_path)

% MATLAB
[param, qMetric] = bc.load.loadSavedMetrics(savePath)

Setting appropriate quality metric parameters and thresholds

We suggest first computing quality metrics with the default parameter values. You can fine-tune thresholds based on your specific brain region and requirements by:

Exploring individual units in the interactive GUI - Do "good"-classified units actually look good?
Examining distribution histograms - Natural threshold locations often appear as bimodal distributions
Reviewing rejection counts - The upset plots show how many units are removed by each metric
Correlating with your measurements - Plot your dependent variable as a function of each quality metric (see Fig. 2 Harris et al., Nat. Neuro, 2016)

Running speed and bottlenecks

Depending on your settings, Bombcell takes between 2-35 minutes for a typical 1-hour Neuropixels recording on a computer with 32GB RAM. Running time varies based on:

Raw waveform extraction (first run only): Extracted waveforms are cached in .npy files. Subsequent runs skip this step. Controlled by nRawSpikesToExtract (default: 100, increase for UnitMatch).
Drift computation (computeDrift=True): Adds ~10 minutes per run. Disabled by default.
Distance metrics (computeDistanceMetrics=True): Adds ~10 minutes per run. Disabled by default as amplitude correlates well with these metrics and is faster to compute.