Installing Python code

The Spotlight Python tools are in the separate spotlight-tools repository. They implement:

• Arena registration model fitting
• Full postprocessing pipeline (behavior alignment, muscle warping, visualization)

We use uv for package management (previously Poetry). uv is significantly faster and still uses pyproject.toml.

Installation

# Install uv if not already installed (see https://docs.astral.sh/uv/)

# Clone and install spotlight-tools
cd spotlight-tools/
uv sync

Running scripts

After installation, entry points are available directly in your shell (or via uv run <command>):

# Fit the arena registration model
fit-arena-registration -a ~/Spotlight/arenas/arena146

# Post-process a recording
postprocess-recording --recording-dir ~/data/spotlight/20250613-fly1b-002/

# Visualize stage trajectory
visualize-stage-trajectory --behavior-frame-metadata-path .../processed/behavior_frames_metadata.csv --output-path .../stage_trajectory.png

Entry points are defined in the [project.scripts] section of spotlight-tools/pyproject.toml.

For maintainers

Update dependencies by editing pyproject.toml version bounds and running:

uv pip install -e .