Summary output plots - Julie-Fabre/bombcell GitHub Wiki

Summary output plots

Bombcell generates 3 types of summary plots that help you quickly assess performance and identify if any thresholds need adjustment.

Enabling summary plots

Python

# Enable global summary plots (default: True)
param["plotGlobal"] = True

# Save plots to disk (default: False)
param["savePlots"] = True
param["plotsSaveDir"] = "/path/to/save/plots"  # Optional, defaults to kilosort_path/bombcell_plots/

# Run bombcell - plots are generated automatically
quality_metrics, param, unit_type, unit_type_string = bc.run_bombcell(ks_dir, save_path, param)

# Or get figure objects for further customization
quality_metrics, param, unit_type, unit_type_string, figures = bc.run_bombcell(
    ks_dir, save_path, param, return_figures=True
)
# figures['waveforms_overlay'], figures['upset_plots'], figures['histograms']

MATLAB

% Enable global summary plots
param.plotGlobal = 1;

% Run bombcell - plots are generated automatically
[qMetric, unitType] = bc.qm.runAllQualityMetrics(param, spikeTimes_samples, spikeTemplates, ...
    templateWaveforms, templateAmplitudes, pcFeatures, pcFeatureIdx, channelPositions, savePath);

Plot types

1. Waveform overlay

This plot shows overlaid template waveforms for each unit classification category, allowing you to quickly verify whether noise and non-somatic units are being classified correctly.

Categories shown:

  • Noise
  • Somatic, good
  • Somatic, MUA
  • Non-somatic (or split into good/MUA if splitGoodAndMua_NonSomatic=True)

What to look for:

  • Noise units should have irregular, non-stereotypical waveforms
  • Good units should have clean, consistent waveform shapes
  • Non-somatic units often have positive-going waveforms or unusual peak patterns

Waveform overlay example

Saved as: waveforms_overlay.png

2. Upset plots

Upset plots visualize the intersections between metrics that caused units to be classified into each category. They show both the size and composition of these intersections in a compact format.

Bombcell generates separate upset plots for:

  • Noise units - shows which waveform shape metrics triggered classification
  • Non-somatic units - shows which non-somatic criteria were met
  • MUA units - shows which MUA metrics triggered classification

If splitGoodAndMua_NonSomatic=True, separate plots are generated for "NON-SOMA GOOD" and "NON-SOMA MUA".

What to look for:

  • Which metrics are removing the most units
  • Whether multiple metrics are correlated (large intersection bars)
  • If a single metric is dominating classification (may indicate threshold needs adjustment)
Noise Non-somatic MUA
Noise upset Non-somatic upset MUA upset

Saved as: upset_plot_noise.png, upset_plot_non_soma.png, upset_plot_mua.png

Note: Python upset plots may look slightly different from MATLAB (no colors) but contain the same information. Requires the upsetplot-bombcell package.

3. Quality metric histograms

Distribution histograms for each computed quality metric, with threshold lines and classification labels.

Color coding:

  • Colored horizontal lines indicate classification regions
  • Vertical black lines indicate threshold values
  • Labels show which region corresponds to which classification (e.g., "Noise" vs "Neuronal", "MUA" vs "Good")

What to look for:

  • Bimodal distributions may suggest natural threshold locations
  • If most units fall on one side of a threshold, consider adjusting it
  • Metrics with very few units in the "bad" region may not be necessary for your data

Histograms example

Saved as: quality_metrics_histograms.png

Troubleshooting

Upset plots not appearing:

  • If no units are classified as a given type, the plot will be skipped
  • Python: ensure upsetplot-bombcell is installed (pip install upsetplot-bombcell)

Plots not saving (Python):

  • Set param["savePlots"] = True
  • Check that param["plotsSaveDir"] is a valid writable path

Histograms look sparse:

  • Metrics with all NaN values are skipped
  • Very few units may result in sparse histograms - this is expected for small datasets