NWBAlignment

class ethograph.io.nwb_alignment.NWBAlignment(nwb_path)

Bases: object

Session metadata backed by an NWB file.

All external media (video, audio, pose) are stored as ImageSeries in acquisition with {stream}_{device} naming. Timing comes from rate or timestamps on the ImageSeries.

Methods

close()
devices(stream)	Discover devices from trials table columns AND acquisition items.
electrical_series()	Discover ElectricalSeries in acquisition.
file_time_spans(stream[, device])	Return [(filepath, t_start, t_end), ...] for each external file in the stream.
from_nwb_object(nwb_obj)	Create alignment from an already-opened pynwb NWBFile object.
get_media(trial, stream[, device])	Return the trial table's media filename for stream/device.
get_stream_rate(stream[, device])	Read the sampling rate for a stream from its acquisition ImageSeries.
print_session()
resolve_media_path(trial, stream[, device, ...])	Resolve the full path for a media file.
restrict(obj, trial)
set_stream_rate(rate, stream[, device])
start_time(trial)
stop_time(trial)
stream_offset_for_trial(trial, stream[, device])	Trial-relative time of sample 0 of the file that holds trial.
stream_rates()	Return {acq_name: (starting_time, rate)} for all acquisition streams.
trial_epoch(trial)

devices(stream)

Discover devices from trials table columns AND acquisition items.

Three sources, checked in order:

1. Trials table columns (video_cam_1 -> device cam_1).

2. Acquisition ImageSeries following {stream}_{device} naming.

3. Acquisition ImageSeries whose external_file extensions match known media types (e.g. .mp4 -> video, .wav -> audio).

Return type:

list[str]

electrical_series()

Discover ElectricalSeries in acquisition. Returns list of {name, path, n_channels, rate}.

Return type:

list[dict]

file_time_spans(stream, device=None)

Return [(filepath, t_start, t_end), …] for each external file in the stream.

Files whose end cannot be determined are skipped.

Return type:

list[tuple[str, float, float]]

classmethod from_nwb_object(nwb_obj)

Create alignment from an already-opened pynwb NWBFile object.

Return type:

NWBAlignment

get_media(trial, stream, device=None)

Return the trial table’s media filename for stream/device.

A stored value that is an absolute local path (e.g. baked in by a template authored on a different machine) is reduced to its basename, so callers can always safely join it onto their own video/audio/pose folder instead of resolving to a path that only existed on the authoring machine.

Return type:

str | None

get_stream_rate(stream, device=None)

Read the sampling rate for a stream from its acquisition ImageSeries.

Return type:

float | None

property has_real_timing: bool

Whether the trials table has meaningful start/stop times.

Returns False when all trials have identical placeholder timing (e.g. start=0.0, stop=1.0 for every row), which indicates the NWB was generated without real session timing.

media_filename(trial, stream, device=None)

The name of the file trial plays for stream/device.

Picks the same file resolve_media_path() would, but names it without resolving it on disk — the trials table reads the same whether or not the media folder is currently attached.

Return type:

str | None

property pose_keys: list[str]

Pose estimation container names from acquisition ImageSeries.

reload()

Drop the open handle and every cached table.

Required around writing to this same file: pynwb holds it open for reading and HDF5 refuses a second, writable handle — and afterwards the cached trials table would still describe the pre-write file.

Return type:

None

resolve_media_path(trial, stream, device=None, fallback_folder=None)

Resolve the full path for a media file.

1. Try the ImageSeries external_file path for this trial (if on disk).

2. Fallback: trial table filename + fallback_folder.

3. Returns None if unresolvable.

Return type:

str | None

stream_offset_for_trial(trial, stream, device=None)

Trial-relative time of sample 0 of the file that holds trial.

0.0 for per-trial files, negative for a session-wide file that started before the trial. The file is found by time (the trial’s start falls in its span), never by position – see _file_for_trial.

Return type:

float

stream_rates()

Return {acq_name: (starting_time, rate)} for all acquisition streams.

Only returns rate and starting_time from NWB ImageSeries metadata. Does not compute duration — external files must be probed for that.

Return type:

dict[str, tuple[float, float | None]]

property trials_ep

Pynapple IntervalSet built from the NWB trials table.