bower_building_ethology

Post-hoc analysis pipeline for bower-building cichlid behavior (200+ species). The CLI is bbe. This is the analysis half of the old CichlidBowerTracking monolith; the data-collection half lives in cichlid-tracking.

Install

This repo is conda-based on dev machines and the analysis server.

conda create -n bbe python=3.11
conda activate bbe
pip install -e ".[dev]"

OpenCV needs system OpenGL libraries for the interactive cropping windows; on a headless box (e.g. CI) install libgl1 first.

Architecture

• State subsystem (state/) — replaces the fragile CSV string-sentinel state with typed JSON plus a derived summary CSV. state_helpers.py is the pure bottom layer (stage registry, completion rule, sentinel codec).
• Preparers (preparers/) — one per analysis stage. BasePreparer is the template: each stage declares its inputs, outputs, and completion_files, and the base class handles download/verify, provenance logging, and upload. PrepPreparer is the first concrete stage.

Status

Implemented: state_helpers, BasePreparer, PrepPreparer (incl. interactive crop/register and summary figures). See CHANGELOG.md for the build order and what's next (state_models/AnalysisConfig, state_manager, the CLI dispatcher, and the remaining preparers).