align_media_from_streams

ethograph.io.nwb_alignment.align_media_from_streams(trials, streams, output_path)

Create an alignment.nwb for unaligned / complex scenarios.

The trials table contains only timing (no filenames). All file references go into ImageSeries acquisition items.

Parameters:

• trials (DataFrame) – DataFrame with trial, start_time, stop_time.

• streams (list[dict]) –

  List of stream dicts, each with:

  {
      "name": "video_cam-1",       # acquisition item name
      "files": ["t1.mp4", ...],    # one per trial (full paths)
      "rate": 30.0,                # sampling rate
  }
  

  For session-wide files (one file spanning all trials):

  {
      "name": "audio_mic-1",
      "files": ["session.wav"],
      "rate": 44100.0,
      "starting_time": 0.0,        # when file starts in session time
  }
  

  For streams with explicit timestamps (irregular):

  {
      "name": "ephys_probe-1",
      "files": ["session.dat"],
      "timestamps": np.array([0.0, 0.001, ...]),
  }
  

• output_path (str | Path) – Where to write the .nwb file.

Return type:

Path to the created NWB file.

Examples

Per-trial video + pose, session-wide audio:

>>> trials = pd.DataFrame({
...     "trial": [1, 2, 3],
...     "start_time": [0.0, 10.5, 22.3],
...     "stop_time": [8.2, 19.1, 30.0],
... })
>>> streams = [
...     {"name": "video_cam-1", "files": ["t1.mp4", "t2.mp4", "t3.mp4"], "rate": 30.0},
...     {"name": "pose_cam-1", "files": ["t1.h5", "t2.h5", "t3.h5"], "rate": 30.0},
...     {"name": "audio_mic-1", "files": ["session.wav"], "rate": 48000.0, "starting_time": 0.0},
... ]
>>> eto.create_alignment_from_streams(trials, streams, ".ethograph/alignment.nwb")