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])
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 for a stream's file.
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.

Handles both NWB timing schemes (timestamps and rate). Files with unresolvable timing are silently 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_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.

property pose_keys: list[str]

Pose estimation container names from acquisition ImageSeries.

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 for a stream’s file.

For per-trial aligned media returns 0.0. For session-wide media returns the file’s start relative to the trial. Reads timing from the acquisition ImageSeries.

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.