Loading Data#

EthoGraph supports three loading paths depending on your data format:

Source	How to load
`.nc` (NetCDF)	`TrialTree` (multi-trial) or single `xarray.Dataset`
`.nwb` (NWB)	NWB file from DANDI, NeuroConv, or custom pynwb script
`.npz` / folder (Pynapple)	Pynapple-saved data

Create a session from your own data#

Click Create with own data in the I/O widget. A dialog guides you through creating a session from several supported sources. After generation the I/O fields are auto-populated so you can click Load immediately.

The dialog handles single-file workflows. For multiple trials, multiple cameras, or multiple microphone files, use the Multiple trials tab in the wizard, or write a short Python script.

Format	When to use	Guide
Pose file	DLC, SLEAP, LightningPose `.h5`/`.csv`	From a pose file
Audio file	Vocal / acoustic data	From an audio file
Numpy file	Pre-computed feature array	From a numpy file
Ephys recording	Raw electrophysiology +/- Kilosort	From an ephys recording
Custom script	Multi-trial, multi-cam, multi-mic	Multi-trial setup

Load a pre-made session#

NetCDF (.nc)

If you already have a session.nc file (e.g. from an ethograph pipeline or Multi-trial setup):

In the I/O widget, select your session data file (.nc)
Select the video folder containing camera recordings (.mp4)
[Optional] Select the audio folder containing microphone recordings (.wav, .mp3, .mp4)
[Optional] Select the tracking folder containing pose estimation files (.h5, .csv)
[Optional] Select an ephys file (.rhd, .abf, …) containing raw multi-channel data
[Optional] Select a Kilosort folder to display single neurons
Click Load

Media paths are resolved from .ethograph/alignment.nwb if present, with fallback to the folders selected above.

NWB (.nwb)

NWB files are self-contained — EthoGraph reads trials, behavioural time series (e.g. PoseEstimationSeries), and media references directly:

In the I/O widget, select your .nwb file
[Optional] Select a local video folder if the paths stored in ImageSeries .external_file no longer point to the correct location
Click Load

Pynapple (.npz / folder)

Pynapple data saved with save_file() or pynapple folders:

In the I/O widget, select your .npz file or pynapple folder
[Optional] Select video/audio/tracking folders
[Optional] Select a pynapple folder containing spike-sorted units to display single neurons
Click Load

xarray: Dataset vs TrialTree#

You can save your session.nc as either a plain xarray.Dataset or a TrialTree. The GUI accepts both.

Plain Dataset — a single xr.Dataset saved with xarray.Dataset.to_netcdf(). When loaded, it is automatically treated as a single trial:

import xarray as xr

ds = xr.Dataset(...)
ds.to_netcdf("session.nc")
# → GUI loads this as one trial

TrialTree — wraps multiple datasets (one per trial) into a single .nc file. Use this when your experiment has multiple trials:

import ethograph as eto

# Multiple trials: one Dataset per trial
dt = eto.from_datasets([ds_trial1, ds_trial2, ds_trial3])
dt.save("session.nc")

# Access individual trials
ds = dt.trial(1)      # by ID
ds = dt.itrial(0)     # by index

If you have a session-long xr.Dataset that you want to split into trials, see Splitting a continuous recording in the multi-trial guide.

See TrialTree for full TrialTree usage.

Folder structure#

xarray (.nc)

~/.ethograph/                          # Global user defaults
    ├── mapping.txt                    # Default integer label_id → name mapping
    ├── space.yaml                     # Extra config for space plot
    └── gui_settings.yaml              # Across-session GUI state

my_project/
    ├── session.nc                     # Behavioural dataset (TrialTree or plain Dataset)
    ├── .ethograph/
    │   ├── alignment.nwb              # Media paths, trial timing, stream offsets
    │   └── local_settings.yaml        # Session-specific GUI state
    │
    ├── labels/
    │   ├── session_labels.tsv         # Current labels
    │   └── backups/
    │       └── session_labels_20240315_101230.tsv
    ├── predictions_asformer_20240215/
    │   ├── trial1.npy
    │   └── trial2.npy
    │
    ├── video/
    │   ├── camera1_trial001.mp4
    │   └── camera2_trial001.mp4
    ├── tracking/                      # External pose files (DLC, SLEAP, ...)
    │   ├── trial001_pose.h5
    │   └── ...
    ├── audio/
    │   ├── mic1_trial001.wav
    │   └── ...
    └── ephys/
        ├── recording.rhd
        └── kilosort4/
            ├── params.py
            ├── spike_times.npy
            ├── spike_clusters.npy
            ├── channel_positions.npy
            ├── channel_map.npy
            ├── templates.npy
            └── cluster_info.tsv

NWB (.nwb)

~/.ethograph/                          # Global user defaults
    ├── mapping.txt
    ├── space.yaml
    └── gui_settings.yaml

my_project/
    ├── session.nwb                    # Self-contained: trials, time series,
    │                                  # pose (PoseEstimationSeries), video
    │                                  # refs (ImageSeries.external_file)
    ├── .ethograph/
    │   ├── alignment.nwb              # Sidecar for stream offsets & overrides
    │   └── local_settings.yaml
    │
    ├── labels/
    │   ├── session_labels.tsv
    │   └── backups/
    │       └── ...
    ├── predictions_asformer_20240215/
    │   ├── trial1.npy
    │   └── trial2.npy
    │
    └── video/                         # Only needed if ImageSeries paths
        ├── camera1_trial001.mp4       # no longer point to the right location
        └── camera2_trial001.mp4

Pose estimation and other behavioural time series are stored inside the .nwb file — no external tracking folder needed.

Pynapple (.npz / folder)

~/.ethograph/                          # Global user defaults
    ├── mapping.txt
    ├── space.yaml
    └── gui_settings.yaml

my_project/
    ├── position.npz                   # Pynapple Tsd/TsdFrame objects
    ├── speed.npz
    ├── units.npz                      # TsGroup of spike times
    ├── .ethograph/
    │   ├── alignment.nwb              # Media paths, trial timing, stream offsets
    │   └── local_settings.yaml
    │
    ├── labels/
    │   ├── session_labels.tsv
    │   └── backups/
    │       └── ...
    ├── predictions_asformer_20240215/
    │   ├── trial1.npy
    │   └── trial2.npy
    │
    ├── video/
    │   ├── camera1_trial001.mp4
    │   └── ...
    └── audio/
        ├── mic1_trial001.wav
        └── ...

The .ethograph/alignment.nwb sidecar is created automatically by the GUI on first load when media files are present.