{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": "# User Manual\n\n`ethograph` visualizes behavioural recordings across modalities:\n\n| Data | Shown as | File formats / loaders |\n|------|----------|------------------------|\n| **Video** | Napari viewer | `.mp4` (recommended), `.avi`, `.mov` (via [pyav](https://pyav.org/docs/stable/)) |\n| **Pose/ BoundingBox** | Overlay on video | `.h5`, `.csv` (DLC, SLEAP, LightningPose, ... via [movement](https://movement.neuroinformatics.dev)) |\n| **Audio** | Waveform + spectrogram | `.wav`, `.mp3` (via [audioio](https://github.com/bendalab/audioio)) |\n| **Electrophysiology** | Multi-channel trace | `.dat`, `.bin`, `.raw` via [phylib](https://github.com/cortex-lab/phylib) and [supported extensions](https://akseli-ilmanen.github.io/ethograph/getting_started/loading_ephys.html#supported-formats) via [Neo](https://neo.readthedocs.io) |\n| **Spike-sorted units** | Raster / PSTH | [Kilosort](https://github.com/MouseLand/Kilosort) folder, `.nwb` file, {class}`pynapple.TsGroup`|\n| **Features** | Lineplot / heatmap | Kinematics, firing rates, latent variables, model outputs, ... |\n\n```{note}\n`.avi` and `.mov` files have inaccurate frame seeking (off by 1–2 frames). For best results, transcode to `.mp4` with H.264. See {doc}`troubleshooting`.\n```\n\n---\n\n\nFeature data can be loaded via three backends:\n\n| Backend | Object | File format |\n|---------|--------|-------------|\n| **xarray** | {class}`xarray.Dataset` / {class}`~ethograph.io.trialtree.TrialTree` | `.nc` |\n| **Pynapple** | {class}`~pynapple.Tsd` / {class}`~pynapple.TsdFrame` | `.npz` or folder |\n| **NWB** | `.nwb` (loaded via {mod}`pynapple`) | `.nwb` |\n\nUnlike a plain numpy array, all three formats carry explicit timestamps with each value.\nThis allows `ethograph` to automatically align data of different sampling rates and\nmodalities (video, audio & electrophysiology).\n"
},
{
"cell_type": "markdown",
"source": "## Labelling\n\nEthograph is a labelling GUI for marking the onset and offset of behavioural\nevents. Press a number key to select a label class, click on the timeseries plot to\nmark the onset, click again to mark the offset, then press **V** to play back\nthe segment you just labelled.\n\n```{image} /_static/videos/label_basic.gif\n:alt: Labelling workflow — select class, click onset, click offset, press V to review\n:width: 100%\n```",
"metadata": {}
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Feature dropdowns\n",
"\n",
"To showcase some `ethograph` functionalities, we will use pose data from a carrion crow performing a tool-use task (Moll et al., 2025¹). The {class}`xarray.Dataset` is from one behavioural trial, and shows position, velocity, speed, and acceleration for 3 keypoints tracked in 3D.\n",
"\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"execution": {
"iopub.execute_input": "2026-04-13T22:36:26.885749Z",
"iopub.status.busy": "2026-04-13T22:36:26.885749Z",
"iopub.status.idle": "2026-04-13T22:36:29.012346Z",
"shell.execute_reply": "2026-04-13T22:36:29.012346Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"