blinklinmult.data.inspect

Read-only helpers for inspecting a built corpus.

Separated from the notebook that uses them so they can be tested: a # %% script runs its top-level cells on import, which makes it untestable as a module. notebooks.corpus_report imports these and adds only plotting.

Nothing here writes to a corpus. It opens, reads, and measures.

Attributes

SPLIT_ORDER

Splits in the order a report should present them.

Functions

populated_splits(→ list[str])	Splits that hold at least one sample, in conventional order.
sample_keys(→ list[str])	Keys spread evenly across a split, starting at an offset.
read_field(→ numpy.ndarray | None)	One field of one sample, float16 upcast to float32.
gather_field(→ numpy.ndarray)	Every frame's value of one field across a split.
occlusion_share(→ float)	Fraction of frames a yaw threshold would mask as self-occluded.
count_events(→ int)	Distinct annotated blink events in a split.

Module Contents

blinklinmult.data.inspect.SPLIT_ORDER: tuple[str, ...] = ('train', 'valid', 'test')

Splits in the order a report should present them.

blinklinmult.data.inspect.populated_splits(handle: h5py.File) → list[str]

Splits that hold at least one sample, in conventional order.

Not every corpus fills every split: TalkingFace is held out entirely as a test set, so anything hard-coded to train fails on it.

Parameters:

handle (h5py.File) – Open corpus.

Returns:

Populated split names.

Return type:

list[str]

blinklinmult.data.inspect.sample_keys(handle: h5py.File, split: str, count: int, offset: int = 0) → list[str]

Keys spread evenly across a split, starting at an offset.

Evenly rather than a head slice: the keys are sorted, so the first N are one recording and their statistics are not the corpus’s. The offset is what lets an interactive browser show a different set on each re-run, wrapping around rather than running out.

Parameters:

• handle (h5py.File) – Open corpus.

• split (str) – Which split.

• count (int) – How many keys to return.

• offset (int) – How many sets to skip.

Returns:

Sample keys; empty when the split is.

Return type:

list[str]

blinklinmult.data.inspect.read_field(handle: h5py.File, split: str, key: str, name: str) → numpy.ndarray | None

One field of one sample, float16 upcast to float32.

Parameters:

• handle (h5py.File) – Open corpus.

• split (str) – Which split.

• key (str) – Sample key.

• name (str) – Field name.

Returns:

The value, or None when this corpus omits the field – which is normal, since corpora declare different subsets.

Return type:

np.ndarray | None

blinklinmult.data.inspect.gather_field(handle: h5py.File, split: str, name: str, limit: int = 4000) → numpy.ndarray

Every frame’s value of one field across a split.

Capped at limit samples so a 40 GB corpus stays interactive; the keys are spread evenly, so the cap costs coverage rather than representativeness.

Parameters:

• handle (h5py.File) – Open corpus.

• split (str) – Which split.

• name (str) – Field name.

• limit (int) – Cap on samples read.

Returns:

Flattened values, empty when the corpus omits the field.

Return type:

np.ndarray

blinklinmult.data.inspect.occlusion_share(yaw_degrees: numpy.ndarray, threshold: float) → float

Fraction of frames a yaw threshold would mask as self-occluded.

Parameters:

• yaw_degrees (np.ndarray) – Yaw per frame, in degrees.

• threshold (float) – Absolute yaw above which the far eye is occluded.

Returns:

Share in [0, 1]; 0 for an empty input.

Return type:

float

blinklinmult.data.inspect.count_events(handle: h5py.File, split: str, limit: int = 3000) → int

Distinct annotated blink events in a split.

Counted as (recording, event id) pairs, because ids are numbered per recording and would otherwise collide across them.

Parameters:

• handle (h5py.File) – Open corpus.

• split (str) – Which split.

• limit (int) – Cap on samples read.

Returns:

Distinct event count; 0 when the corpus has no blink_ids.

Return type:

int