Overview of quality metrics and options

Running bombcell's quality metrics

Bombcell organization: qMetric and param structures

Bombcell is organized around two main matlab structures: qMetrics and param.

• qMetrics is a structure generated by the bc.qm.runAllQualityMetrics function. Its fields are different quality metrics, and each field contains a quality metric value for each unit.
• param is a structure generated by the function bc.qm.qualityParamValues and it contains parameters both to compute quality metrics with bc.qm.runAllQualityMetrics and to then classify cells with bc.qm.getQualityUnitType.

Additionally, in order to avoid possible conflicts, all Bombcell functions are packaged in namespace folders.

A run-through of a typical workflow

Take a look at bombcell_pipeline to see an example workflow.

1. Load ephys data, eg:

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

2. Run all quality metrics and classify cells with the function bc.qm.runAllQualityMetrics, eg:

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

3. Look at global output plots and flip through cells with the GUI:

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

4. Refine classification : choose quality metric thresholds (see the section Setting appropriate quality metric parameters and thresholds below).

Plotting quality metrics

We have added automatic plotting function at each step, in order to aid in trouble-shooting and evaluating Bombcells' output:

• Set param.plotGlobal = 1 to plot summary of the noise units' waveforms compared to single multi-units, distribution histograms of the units' quality metrics and numbers of units removed by each quality metric. See the detailed overview of global output plots section for examples of these plots.

• Set param.plotThis = 1 to plot figures for each quality metric and for each cell (plot examples displayed below). This generates a considerable amount of plots. We suggest you only use when de-bugging or to generate example cell plots. See the detailed overview of the quality metrics section for examples of these plots.

In addition, Bombcells' GUI allows you to flip through cells and their quality metrics. This is useful in evaluating where to set your quality metric classification thresholds and checking how Bombcell behaves. See the quality metrics GUI guide section for more information.

Loading and saving data

All Bombcell outputs are saved in the ONE format, in .npy or .parquet files. .npy files can be read in matlab using the npy-matlab toolbox, and .parquet files can be read in matlab using the built-in readparquet function.

The following files are outputed by Bombcell:

• _bc_parameters._bc_qMetrics.parquet
• templates._bc_fractionRefractoryPeriodViolationsPerTauR.parquet
• templates._bc_qMetrics.parquet
• templates._bc_rawWaveforms.npy
• templates._bc_rawWaveformPeakChannels.npy
• templates._bc_baselineNoiseAmplitude.npy
• templates._bc_baselineNoiseAmplitudeIndex.npy
• (optional, if param.saveMultipleRaw is set to true) 'Unit$CLUSTER_ID$_RawSpikes.npy'

These saved files can be retrieved with the function [param, qMetric] = bc.load.loadSavedMetrics(savePath)

Additionally, optionally if param.saveMatFileForGUI is set to true, Bombcell saves a templates.qualityMetricDetailsforGUI.mat file containing various data needed for Bombcells GUI. This data can also be loaded using the function bc.load.loadMetricsForGUI.

Setting appropriate quality metric parameters and thresholds

We suggest first computing quality metrics with the default parameter values (defined by the param structure in bc.qm.qualityParamValues). You can fine-tune the thresholds based on your specific neuronal region and requirements by looking at the following:

• individual units, in the interactive GUI. Do the current quality metric threshold classify units into categories in a reasonable manner? (ie do "good"-classified units look good ?)

• the distribution histograms of the units' quality metrics (see General plots). There can be natural places to set thresholds id there are for instance bimodal distributions.

• the numbers of units removed by each quality metric.

• It may also be helpful to plot the quantity you are measuring 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' and 35' for a typical 1 hour long neuropixels recording, on a computer with 32GB of RAM. The running time varies according to three main parameters:

• if this is the first run, raw waveforms are extracted from your raw .bin or .dat ephys file. These are then saved in two .npy files. Subsequent runs load in the already extracted waveforms and thus take ~10-15' less. Initial running time increases or decreases as the number of spikes extracted per unit, defined by param.nRawSpikesToExtract, increases or decreases.
• if param.computeDrift is true, drift is computed. This can add ~10' per run, and is disabled by default.
• if param.computeDistanceMetrics is true, several distance metrics are computed. This can add ~10' per run. Distance metrics are susceptible to probe drift, and correlate well with a units raw waveform amplitude. As a result, we suggest using a units amplitude instead of distance metrics and this parameter is disabled by default.