ethograph

Ethograph is a graphical user interface for visualizing and segmenting multimodal timeseries behavioural data. It builds upon a number of open-source libraries to load and quickly render video and pose files, audio and spectrograms, ephys recordings in various formats, and arbitrary multi-dimensional timeseries — all on one shared timeline.

Note this GUI is still in development. I welcome people testing it and providing feedback!

📖 Documentation

🎥 Watch the demo

Quickstart

First install uv, a fast Python package manager:

# macOS / Linux (except WSL)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
winget install astral-sh.uv

Then install the GUI as a standalone tool — one command, no environment to create or activate:

uv tool install --python 3.12 --compile-bytecode "ethograph[gui,audio]"

To open the GUI, run:

ethograph check # Linux only : Check for missing libraries
ethograph launch

ethograph not recognized? uv has not added its bin directory to your PATH yet. Run uv tool update-shell, then open a new terminal.

To upgrade later, run the same command with --force --refresh:

uv tool install --python 3.12 --compile-bytecode --force --refresh "ethograph[gui,audio]"

For installing into a dedicated virtual environment,segmentation models, and troubleshooting, see installation guide.

After launching, there are some example datasets you can explore the GUI with. To learn more about all the functionalities, I recommend the user manual.

Support

Ethograph is built on top of a number of open-source projects: PyAV, audioio, Neo, crowsetta, Neurodata Without Borders, xarray, pynapple, movement, phy, PyQtGraph, and pygfx (via pynaviz). The models that segment behaviour build on DLC2Action, FERAL and E2E-Spot.

Ethograph is GPL-3.0-or-later. The code it vendors or adapts from other projects, and each one's licence, is listed in THIRD_PARTY_NOTICES.md.