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!

Quickstart

🔍 Is my data compatible?

Data compatibility helper

×

Are you working with NWB files?

.nwb files are self-contained — EthoGraph loads them directly.

Yes — I have .nwb filesFrom DANDI, NeuroConv, or another NWB pipeline

No — I have raw filesVideo, audio, pose, ephys, numpy…

Please select an option.

What do you want to visualise?

Select everything that applies.

Videos.mp4 camera recordings

Pose estimationDeepLabCut, SLEAP, LightningPose

Audio / spectrogram.wav, .mp3, or video with sound

ElectrophysiologyRaw ephys or spike-sorted units (Kilosort)

Custom feature arrayPre-computed signals as .npy

Other / custom formatNot listed above

Multiple cameras?

i.e. several video or pose files recorded simultaneously.

No — single camera

Yes — multiple cameras

How is your audio stored?

All three work with drag & drop; separate files per mic come with a caveat.

Single microphone

One multichannel fileAll mics in a single .wav

One file per microphone

Have you already labelled this audio elsewhere?

Existing annotations can be imported rather than redone.

No — I'll label in EthoGraph

Yes — in Audacity, Praat, evsonganaly… Or another annotation tool

Please answer every question above.

Does your data have a trial structure?

Yes if you have separate files per trial, or one continuous recording in which you want to define trial windows.

No — one continuous session

Yes — trials or epochs

Please select an option.

← Back Next →

Installation

EthoGraph is installed with uv, a fast Python package manager:

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

winget install astral-sh.uv

Works from both PowerShell and Command Prompt; winget is built into Windows 11.

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

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

To open the GUI, run:

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

Note

For installing into a dedicated virtual environment, optional extras (segmentation models, DANDI downloads, …) and troubleshooting, see the installation guide.

After launching, there are some example datasets you can explore the GUI. 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 [PyAV contributors, n.d.], audioio [Benda, n.d.], Neo [Garcia et al., 2014], crowsetta [Nicholson, 2023], Neurodata Without Borders [Rübel et al., 2022], xarray [Hoyer and Hamman, 2017], pynapple [Viejo et al., 2023], movement [Sirmpilatze et al., n.d.], phy [Rossant et al., 2016], PyQtGraph [PyQtGraph contributors, n.d.], and pygfx [Klein and others, n.d.] (via pynaviz [pynapple-org, n.d.]). The full list is on the references page.