personalitylinmult.data.sources¶

Readers for each on-disk feature format produced by preprocess/fi.

Every reader returns the same thing — a FeatureSample of features plus a mask — so the builder can treat WavLM pickles, DINOv2 safetensors and RoBERTa HDF5 datasets identically.

Masks. Only the track-based extractors (EmotiEffNet, FaRL, MARLIN) record a real mask, because the protagonist is not detected on every frame. The other formats are dense by construction and get an all-True mask synthesised here. Producing a mask unconditionally is what lets the rest of the pipeline hold a single contract: every sequence feature has a mask, True = valid.

AppleDouble files. This repository lives on a non-native filesystem where macOS writes ._{name} resource-fork sidecars next to real files. A naive glob("*.st") returns twice as many paths as there are clips, and reading one raises SafetensorError: header too large. iter_feature_files() filters them; use it rather than globbing directly.

Exceptions¶

SourceError

Raised when a feature file is missing, unreadable, or malformed.

Classes¶

`FeatureSample`	One clip's features for one modality.
`FeatureReader`	Reads one feature for arbitrary clips, holding open handles as needed.

Functions¶

`is_hidden_sidecar`(→ bool)	Whether a path is a macOS AppleDouble resource fork.
`iter_feature_files`(→ list[pathlib.Path])	List real feature files in a directory, skipping AppleDouble sidecars.
`read_pickle_layers`(→ FeatureSample)	Read selected transformer layers from a pickled list of per-layer arrays.
`read_npy`(→ FeatureSample)	Read a plain `(T, D)` array.
`read_safetensors`(→ FeatureSample)	Read a safetensors feature file, honouring its mask when present.
`read_hdf5_entry`(→ FeatureSample)	Read one clip's `(T, D)` sequence entry from a per-id HDF5 feature file.

Module Contents¶

class personalitylinmult.data.sources.FeatureSample¶

One clip’s features for one modality.

Parameters:

features (np.ndarray) – (T, D) for a sequence, or (L, T, D) for a multi-layer sequence.
mask (np.ndarray) – (T,) bool, True where the timestep is valid.

property time_dim: int¶

Length of the time axis.

Returns:: T.
Return type:: int

exception personalitylinmult.data.sources.SourceError¶

Bases: RuntimeError

Raised when a feature file is missing, unreadable, or malformed.

Initialize self. See help(type(self)) for accurate signature.

personalitylinmult.data.sources.is_hidden_sidecar(path: pathlib.Path) → bool¶

Whether a path is a macOS AppleDouble resource fork.

Parameters:: path (Path) – Candidate path.
Returns:: True for ._* sidecars, which are not real feature files.
Return type:: bool

personalitylinmult.data.sources.iter_feature_files(directory: pathlib.Path, suffix: str) → list[pathlib.Path]¶

List real feature files in a directory, skipping AppleDouble sidecars.

Parameters:

directory (Path) – Directory to scan.
suffix (str) – File suffix including the dot, e.g. ".st".

Returns:

Sorted real files.

Return type:

list[Path]

Raises:

SourceError – If the directory does not exist.

personalitylinmult.data.sources.read_pickle_layers(path: pathlib.Path, layers: tuple[int, Ellipsis]) → FeatureSample¶

Read selected transformer layers from a pickled list of per-layer arrays.

Used for WavLM. layers always names model layers (9 means WavLM’s layer 9), never positions in the file, so the same config reads both supported on-disk formats:

{"layers": [...], "features": [...]} — what personalitylinmult.preprocess.fi.acoustic_wavlm writes now: only the extracted layers, each tagged with its model layer id.
a bare list of every layer — the older, fatter format, where position happens to equal the layer id.

The distinction matters because the current extractor stores one layer per clip: in a bare list that array would sit at index 0 and be indistinguishable from layer 0. Carrying the ids makes the file self-describing instead.

The pickles are produced locally by personalitylinmult.preprocess.fi from the operator’s own audio, so they are trusted input.

Parameters:

path (Path) – Path to the .pkl file.
layers (tuple[int, ...]) – Model layer ids to keep, in order.

Returns:

(T, D) when one layer is selected, (L, T, D) when several. The mask is dense.

Return type:

FeatureSample

Raises:

SourceError – If the file is unreadable or a requested layer is absent.

personalitylinmult.data.sources.read_npy(path: pathlib.Path) → FeatureSample¶

Read a plain (T, D) array.

Parameters:: path (Path) – Path to the .npy file.
Returns:: The array with a dense mask.
Return type:: FeatureSample
Raises:: SourceError – If the file is unreadable or not 2-D.

personalitylinmult.data.sources.read_safetensors(path: pathlib.Path) → FeatureSample¶

Read a safetensors feature file, honouring its mask when present.

DINOv2 runs on full frames and emits no mask key; the track-based extractors emit one. Both are normalised to a mask here.

Parameters:: path (Path) – Path to the .st file.
Returns:: (T, D) features and a (T,) mask.
Return type:: FeatureSample
Raises:: SourceError – If the file is unreadable, lacks features, or its mask length disagrees with its feature length.

personalitylinmult.data.sources.read_hdf5_entry(h5_file: h5py.File, video_id: str) → FeatureSample¶

Read one clip’s (T, D) sequence entry from a per-id HDF5 feature file.

Parameters:

h5_file (h5py.File) – Open feature file, keyed by video_id.
video_id (str) – Clip identifier.

Returns:

The entry, with a dense all-valid mask.

Return type:

FeatureSample

Raises:

SourceError – If the id is absent or the entry is not a 2-D (T, D) sequence.

class personalitylinmult.data.sources.FeatureReader(spec: personalitylinmult.data.schema.FeatureSpec, root: pathlib.Path)¶

Reads one feature for arbitrary clips, holding open handles as needed.

hdf5_per_id features live in a single file keyed by video_id, so the handle is opened once and reused; the per-clip formats are opened on demand. Use as a context manager so the handle is always released.

Parameters:

spec (FeatureSpec) – The feature to read.
root (Path) – Repository root that spec.source_dir is relative to.

__enter__() → FeatureReader¶

Open any shared handle.

Returns:: This reader.
Return type:: FeatureReader

__exit__(*exc_info: object) → None¶: Release any shared handle.

available_ids() → set[str]¶

Clip ids this feature actually has on disk.

The builder compares this against label.csv and fails loudly on a shortfall, rather than silently zero-filling clips whose features were never extracted.

Returns:: Available video_id values.
Return type:: set[str]
Raises:: SourceError – If the source directory or file is missing.

read(video_id: str) → FeatureSample¶

Read one clip’s feature.

Parameters:: video_id (str) – Clip identifier.
Returns:: Features plus mask.
Return type:: FeatureSample
Raises:: SourceError – If the clip’s feature cannot be read.