Turn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 250,000+ scientists worldwide. 177 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.
Python agent-skillsai-scientistbioinformaticschemoinformaticsclaudeclaude-skillsclaudecodeclinical-researchcomputational-biologydata-analysisdrug-discoverygenomicsmaterials-sciencemetabolomicsproteomicsscientific-computingscientific-visualization
"""Synthetic recording, curation and sorter-routing regression checks."""
from __future__ import annotations
import sys
import tempfile
import unittest
from pathlib import Path
import pytest
import skill_contract
SKILL_ROOT = Path(__file__).resolve().parents[2] / "skills" / "neuropixels-analysis"
SCRIPTS = SKILL_ROOT / "scripts"
sys.path.insert(0, str(SCRIPTS))
pytest.importorskip("spikeinterface", reason="neuropixels-analysis needs spikeinterface")
pd = pytest.importorskip("pandas", reason="neuropixels-analysis needs pandas")
matplotlib = pytest.importorskip("matplotlib", reason="neuropixels-analysis needs matplotlib")
# explore_recording imports pyplot at module scope, so fix the backend first.
matplotlib.use("Agg")
import matplotlib.pyplot as plt # noqa: E402
import compute_metrics # noqa: E402
import explore_recording # noqa: E402
import neuropixels_pipeline # noqa: E402
import run_sorting # noqa: E402
CliHelpTests = skill_contract.cli.help_test_case(SKILL_ROOT)
CURATION_METHODS = ("allen", "ibl", "strict")
#: A unit that passes every criterion of every preset.
EXEMPLARY = {
"snr": 10.0,
"presence_ratio": 0.99,
"isi_violations_ratio": 0.0,
"amplitude_cutoff": 0.0,
"firing_rate": 5.0,
}
def metrics_table(*units: dict) -> pd.DataFrame:
"""A quality-metrics frame shaped like SpikeInterface's, one row per unit."""
rows = [{**EXEMPLARY, **unit} for unit in units]
return pd.DataFrame(rows, index=range(len(rows)))
class CurationLabelTests(unittest.TestCase):
"""`curate_units` decides which units reach a figure."""
def label(self, method: str, **overrides) -> str:
return neuropixels_pipeline.curate_units(metrics_table(overrides), method=method)[0]
def test_an_exemplary_unit_is_good_under_every_preset(self) -> None:
# The permissive direction: a validator that rejected this unit would
# reject every real single unit too.
for method in CURATION_METHODS:
with self.subTest(method=method):
self.assertEqual(self.label(method), "good")
def test_low_snr_is_noise_whatever_else_the_unit_scores(self) -> None:
# The noise gate runs before the presets and short-circuits, so a unit
# with perfect refractory behaviour and no amplitude clipping is still
# noise if there is no signal to speak of.
for method in CURATION_METHODS:
with self.subTest(method=method):
self.assertEqual(self.label(method, snr=1.0), "noise")
def test_the_noise_threshold_excludes_its_own_boundary(self) -> None:
# `row['snr'] < 1.5`, so exactly 1.5 is not noise.
self.assertEqual(self.label("allen", snr=1.49), "noise")
self.assertNotEqual(self.label("allen", snr=1.5), "noise")
def test_allen_tolerates_refractory_violations_that_ibl_calls_multi_unit(self) -> None:
# This is the documented difference between the two local presets: Allen
# accepts isi_violations_ratio < 0.5, IBL only < 0.1.
self.assertEqual(self.label("allen", isi_violations_ratio=0.3), "good")
self.assertEqual(self.label("ibl", isi_violations_ratio=0.3), "mua")
def test_the_allen_refractory_boundary_is_strict_on_both_sides(self) -> None:
self.assertEqual(self.label("allen", isi_violations_ratio=0.49), "good")
# Exactly 0.5 passes neither `< 0.5` nor `> 0.5`, so it is neither good
# nor multi-unit -- it lands in the "needs a human" bucket.
self.assertEqual(self.label("allen", isi_violations_ratio=0.5), "unsorted")
self.assertEqual(self.label("allen", isi_violations_ratio=0.51), "mua")
def test_presence_ratio_is_a_strict_minimum(self) -> None:
# `presence_ratio > 0.9`: a unit present for exactly 90% of the
# recording is not automatically good.
self.assertEqual(self.label("allen", presence_ratio=0.91), "good")
self.assertEqual(self.label("allen", presence_ratio=0.9), "unsorted")
def test_amplitude_clipping_downgrades_without_calling_the_unit_multi_unit(self) -> None:
# A truncated amplitude distribution means missed spikes, which is a
# completeness problem, not contamination -- so it must not be labelled
# 'mua' when the refractory period is clean.
self.assertEqual(self.label("allen", amplitude_cutoff=0.2), "unsorted")
def test_ibl_additionally_requires_a_minimum_firing_rate(self) -> None:
# A unit that fires a handful of times cannot support a rate estimate.
self.assertEqual(self.label("ibl", firing_rate=0.05), "unsorted")
self.assertEqual(self.label("ibl", firing_rate=0.2), "good")
# Allen's criteria do not mention firing rate, so the same unit passes.
self.assertEqual(self.label("allen", firing_rate=0.05), "good")
def test_strict_demands_high_snr_and_a_nearly_clean_refractory_period(self) -> None:
self.assertEqual(self.label("strict", snr=4.0), "unsorted")
self.assertEqual(self.label("strict", snr=5.1), "good")
self.assertEqual(self.label("strict", presence_ratio=0.94), "unsorted")
self.assertEqual(self.label("strict", isi_violations_ratio=0.02), "unsorted")
self.assertEqual(self.label("strict", isi_violations_ratio=0.06), "mua")
def test_every_unit_gets_exactly_one_label(self) -> None:
# A unit missing from the returned mapping disappears from the export
# rather than being reported as rejected.
table = metrics_table(
{},
{"snr": 1.0},
{"isi_violations_ratio": 0.9},
{"presence_ratio": 0.5},
)
for method in CURATION_METHODS:
with self.subTest(method=method):
labels = neuropixels_pipeline.curate_units(table, method=method)
self.assertEqual(sorted(labels), list(table.index))
self.assertLessEqual(set(labels.values()), {"good", "mua", "noise", "unsorted"})
def test_an_unknown_method_raises_instead_of_dropping_units(self) -> None:
# Silently returning a partial mapping would make export_results()
# report zero good units from a perfectly good sorting.
for method in ("Allen", "allen ", "ibl2", ""):
with self.subTest(method=method):
with self.assertRaisesRegex(ValueError, "unknown curation method"):
neuropixels_pipeline.curate_units(metrics_table({}), method=method)
def test_an_empty_metrics_table_yields_no_labels(self) -> None:
empty = pd.DataFrame(columns=list(EXEMPLARY), index=[])
self.assertEqual(neuropixels_pipeline.curate_units(empty, method="allen"), {})
class CurationCriteriaTests(unittest.TestCase):
"""The threshold table in compute_metrics.py, against the documented values."""
def test_the_presets_are_the_three_the_cli_offers(self) -> None:
self.assertEqual(set(compute_metrics.CURATION_CRITERIA), set(CURATION_METHODS))
def test_every_preset_carries_the_same_criteria(self) -> None:
# The curation loop reads each threshold with `criteria.get(name)`, so a
# renamed or missing key silently disables that criterion instead of
# failing loudly.
expected = {"snr", "isi_violations_ratio", "presence_ratio", "amplitude_cutoff"}
for name, criteria in compute_metrics.CURATION_CRITERIA.items():
with self.subTest(preset=name):
self.assertEqual(set(criteria), expected | ({"firing_rate"} if name == "ibl" else set()))
def test_no_threshold_is_zero_or_none(self) -> None:
# Same truthiness trap: `if criteria.get('snr')` treats 0.0 and None as
# "no threshold set", so a legitimate-looking 0 would be ignored.
for name, criteria in compute_metrics.CURATION_CRITERIA.items():
for key, value in criteria.items():
with self.subTest(preset=name, criterion=key):
self.assertIsNotNone(value)
self.assertGreater(value, 0)
def test_the_allen_thresholds_are_the_documented_visual_coding_ones(self) -> None:
allen = compute_metrics.CURATION_CRITERIA["allen"]
self.assertEqual(allen["isi_violations_ratio"], 0.5)
self.assertEqual(allen["presence_ratio"], 0.9)
self.assertEqual(allen["amplitude_cutoff"], 0.1)
def test_the_ibl_thresholds_are_the_documented_legacy_local_screen(self) -> None:
ibl = compute_metrics.CURATION_CRITERIA["ibl"]
self.assertEqual(ibl["isi_violations_ratio"], 0.1)
self.assertEqual(ibl["presence_ratio"], 0.9)
self.assertEqual(ibl["amplitude_cutoff"], 0.1)
def test_the_presets_are_ordered_from_permissive_to_strict(self) -> None:
# snr and presence_ratio are minima, so stricter means larger; the other
# two are maxima, so stricter means smaller. Swapping two presets' names
# -- the kind of edit that looks harmless -- breaks this ordering.
minima = ("snr", "presence_ratio")
maxima = ("isi_violations_ratio", "amplitude_cutoff")
for looser, tighter in (("allen", "ibl"), ("ibl", "strict")):
for key in minima:
with self.subTest(pair=(looser, tighter), criterion=key):
self.assertLessEqual(
compute_metrics.CURATION_CRITERIA[looser][key],
compute_metrics.CURATION_CRITERIA[tighter][key],
)
for key in maxima:
with self.subTest(pair=(looser, tighter), criterion=key):
self.assertGreaterEqual(
compute_metrics.CURATION_CRITERIA[looser][key],
compute_metrics.CURATION_CRITERIA[tighter][key],
)
def test_the_two_scripts_agree_on_which_standard_is_stricter(self) -> None:
# neuropixels_pipeline.curate_units hardcodes its refractory thresholds
# rather than reading this table, so they can drift apart. Prove the
# relationship holds in both: a unit Allen calls good, IBL calls mua.
table = compute_metrics.CURATION_CRITERIA
self.assertGreater(
table["allen"]["isi_violations_ratio"], table["ibl"]["isi_violations_ratio"]
)
between = (table["ibl"]["isi_violations_ratio"] + table["allen"]["isi_violations_ratio"]) / 2
labels = {
method: neuropixels_pipeline.curate_units(
metrics_table({"isi_violations_ratio": between}), method=method
)[0]
for method in ("allen", "ibl")
}
self.assertEqual(labels, {"allen": "good", "ibl": "mua"})
class SorterDefaultTests(unittest.TestCase):
def test_the_presets_match_the_sorters_the_cli_offers(self) -> None:
self.assertEqual(
set(run_sorting.SORTER_DEFAULTS),
{"kilosort4", "kilosort3", "spykingcircus2", "mountainsort5"},
)
def test_every_sorter_that_can_preprocess_has_it_switched_off(self) -> None:
# run_sorting.py consumes an already filtered, referenced, bad-channel
# removed recording. Letting a sorter filter or re-reference it a second
# time distorts the waveforms it then tries to cluster.
defaults = run_sorting.SORTER_DEFAULTS
self.assertIs(defaults["kilosort3"]["car"], False)
self.assertIs(defaults["spykingcircus2"]["apply_preprocessing"], False)
self.assertIs(defaults["mountainsort5"]["filter"], False)
self.assertIs(defaults["mountainsort5"]["whiten"], True) # Input is filtered, not whitened.
def test_the_kilosort4_thresholds_are_positive_spike_amplitudes(self) -> None:
kilosort4 = run_sorting.SORTER_DEFAULTS["kilosort4"]
self.assertGreater(kilosort4["Th_universal"], 0)
self.assertGreater(kilosort4["Th_learned"], 0)
# The universal (template-matching) threshold sits above the learned one
# in Kilosort4's own defaults, so detection is broader than acceptance.
self.assertGreater(kilosort4["Th_universal"], kilosort4["Th_learned"])
self.assertGreater(kilosort4["batch_size"], 0)
def test_an_unlisted_sorter_gets_no_parameters_rather_than_a_wrong_set(self) -> None:
# `SORTER_DEFAULTS.get(sorter, {})` -- a sorter with no entry must fall
# back to that sorter's own upstream defaults, never to another one's.
self.assertEqual(run_sorting.SORTER_DEFAULTS.get("tridesclous2", {}), {})
class MotionRoutingTests(unittest.TestCase):
def test_corrected_input_disables_the_relevant_sorter_motion_stage(self) -> None:
from unittest.mock import MagicMock, patch
flags = {
"kilosort2_5": "do_correction",
"kilosort3": "do_correction",
"kilosort4": "do_correction",
"spykingcircus2": "apply_motion_correction",
"mountainsort5": None,
}
for sorter, flag in flags.items():
for corrected in (True, False):
with self.subTest(sorter=sorter, corrected=corrected):
with patch.object(neuropixels_pipeline.si, "run_sorter") as run:
neuropixels_pipeline.run_spike_sorting(
MagicMock(), "output", sorter, motion_corrected=corrected
)
kwargs = run.call_args.kwargs
expected = {flag: False} if corrected and flag else {}
actual = {key: kwargs[key] for key in set(flags.values()) - {None}
if key in kwargs}
self.assertEqual(actual, expected)
def test_template_disables_motion_for_corrected_sorter_inputs(self) -> None:
import ast
from unittest.mock import MagicMock
source = (SKILL_ROOT / "assets" / "analysis_template.py").read_text()
main = next(node for node in ast.parse(source).body
if isinstance(node, ast.FunctionDef) and node.name == "main")
start = next(i for i, node in enumerate(main.body)
if isinstance(node, ast.Assign)
and any(isinstance(target, ast.Name) and target.id == "sorter_params"
for target in node.targets))
routing = ast.Module(body=main.body[start:start + 3], type_ignores=[])
flags = {"kilosort3": "do_correction", "kilosort4": "do_correction",
"spykingcircus2": "apply_motion_correction", "mountainsort5": None}
for sorter, flag in flags.items():
for enabled in (True, False):
with self.subTest(sorter=sorter, enabled=enabled):
user_params = {flag: True} if flag else {}
namespace = dict(SORTER=sorter, CORRECT_MOTION=enabled,
SORTER_PARAMS=user_params, rec=MagicMock(),
output_path=Path("output"), si=MagicMock())
exec(compile(routing, "analysis_template.py", "exec"), namespace)
kwargs = namespace["si"].run_sorter.call_args.kwargs
expected = {flag: not enabled} if flag else {}
actual = {key: kwargs[key] for key in set(flags.values()) - {None}
if key in kwargs}
self.assertEqual(actual, expected)
self.assertEqual(user_params, {flag: True} if flag else {})
def test_pipeline_routes_the_actual_correction_state_without_depth_threshold(self) -> None:
from unittest.mock import MagicMock, patch
for enabled in (True, False):
with self.subTest(enabled=enabled), tempfile.TemporaryDirectory() as output:
rec = MagicMock()
preprocessed = rec.save.return_value
corrected = MagicMock()
with patch.multiple(
neuropixels_pipeline,
load_recording=MagicMock(return_value=rec),
preprocess=MagicMock(return_value=(rec, [])),
check_drift=MagicMock(return_value={"peaks": [], "peak_locations": []}),
correct_motion=MagicMock(return_value=corrected),
run_spike_sorting=MagicMock(),
postprocess=MagicMock(return_value=(MagicMock(), metrics_table({}))),
curate_units=MagicMock(return_value={}),
export_results=MagicMock(),
):
neuropixels_pipeline.run_pipeline("input", output, apply_motion_correction=enabled)
run = neuropixels_pipeline.run_spike_sorting
self.assertIs(run.call_args.args[0], corrected if enabled else preprocessed)
self.assertIs(run.call_args.kwargs["motion_corrected"], enabled)
self.assertEqual(neuropixels_pipeline.correct_motion.call_count, int(enabled))
class TracePlotTests(unittest.TestCase):
"""`plot_traces` must stay readable on a full 384-channel Neuropixels probe."""
@classmethod
def setUpClass(cls) -> None:
import spikeinterface.full as si
cls.si = si
def setUp(self) -> None:
self._temporary = tempfile.TemporaryDirectory()
self.addCleanup(self._temporary.cleanup)
self.addCleanup(plt.close, "all")
self.root = Path(self._temporary.name)
def recording(self, channels: int):
return self.si.generate_recording(
num_channels=channels, durations=[0.5], sampling_frequency=30000.0
)
def drawn_lines(self, channels: int) -> int:
target = self.root / f"traces{channels}.png"
explore_recording.plot_traces(
self.recording(channels), duration=0.05, output_path=str(target)
)
self.assertTrue(target.is_file())
# plot_traces builds its own figure and does not return it.
return len(plt.gcf().axes[0].lines)
def test_a_wide_probe_is_subsampled_to_twenty_traces(self) -> None:
self.assertEqual(self.drawn_lines(64), 20)
def test_a_narrow_probe_draws_every_channel_it_has(self) -> None:
# min(20, n) -- with fewer than 20 channels nothing is dropped, and the
# linspace must not produce duplicate indices.
self.assertEqual(self.drawn_lines(6), 6)
def test_the_time_axis_covers_the_requested_duration(self) -> None:
target = self.root / "traces.png"
recording = self.recording(8)
explore_recording.plot_traces(recording, duration=0.05, output_path=str(target))
line = plt.gcf().axes[0].lines[0]
times = line.get_xdata()
self.assertEqual(len(times), int(0.05 * recording.get_sampling_frequency()))
self.assertAlmostEqual(float(times[0]), 0.0)
self.assertLess(float(times[-1]), 0.05)
if __name__ == "__main__":
unittest.main()