ripple_detection: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

ripple_detection is a Python package for detecting sharp-wave ripple events (150-250 Hz) from local field potentials (LFPs) in neuroscience research. It implements detection algorithms from Karlsson & Frank 2009, Kay et al. 2016, Yu et al. 2017, Carey et al. 2019, FMAToolbox and buzcode, along with unpublished lab variants.

Development Commands

Setup

# uv (recommended): .venv from uv.lock with the package editable plus the dev tools
uv sync --extra examples
uv run pytest            # prefix any command with `uv run` to use that environment
uv lock                  # after changing dependencies in pyproject.toml
uvx pre-commit install   # once; each commit then runs ruff, codespell, mypy and the file checks

# Or pip into your own environment
pip install -e .[dev,examples]

# Or conda
conda env create -f environment.yml
conda activate ripple_detection
pip install -e .[dev,examples]

# Minimal install (runtime dependencies only)
pip install -e .

The dev extra and the dev dependency group in pyproject.toml list the same tools; keep them identical.

Releasing: the release skill (.claude/skills/release/SKILL.md). What each test module covers: tests/CLAUDE.md.

Testing

# Run all tests with coverage, and the docstring examples in src/ (testpaths)
pytest

# Test notebooks (as done in CI)
jupyter nbconvert --to notebook --ExecutePreprocessor.kernel_name=python3 --execute examples/detection_examples.ipynb
jupyter nbconvert --to notebook --ExecutePreprocessor.kernel_name=python3 --execute examples/test_individual_algorithm_components.ipynb
jupyter nbconvert --to notebook --ExecutePreprocessor.kernel_name=python3 --execute examples/ripple_detection_tutorial.ipynb
jupyter nbconvert --to notebook --ExecutePreprocessor.kernel_name=python3 --execute examples/simulation_study.ipynb

# Re-run the simulation study sweep the notebook reads (about two minutes)
uv run python examples/simulation_study.py

# Run every surveyed paper's packaged method on a simulated session (seconds;
# overwrites examples/literature_recipes_results.csv). Widloski 2022 has none:
# its replay is defined by decoding (literature_methods.NOT_REPRODUCED)
uv run python examples/literature_recipes.py

# The measured-data walkthrough for literature_methods (seconds; the tests run it)
uv run python examples/measured_walkthrough.py