ethograph.labels.ml

Dense (array-based) label operations for ML pipelines.

This module provides tools for converting between the interval-based label format (used by the GUI and TSV storage) and dense integer arrays (used by ML models). It also contains post-processing operations commonly applied to model predictions before evaluation or storage.

Typical ML workflow

1. Load labels from TSV → pd.DataFrame with onset_s, offset_s, labels, individual (plus n_samples per-trial metadata).

2. Convert to dense → intervals_to_dense(df, sample_rate, individuals, n_samples) gives an (n_samples, n_individuals) int8 array ready for training.

3. Run model → get a dense prediction array of shape (T,) or (T, n_classes).

4. Convert back → dense_to_intervals(pred, individuals, sample_rate=sr) gives an intervals DataFrame for storage or evaluation.

5. Post-process on the intervals — purge, stitch, snap — through ethograph.features.changepoints.correct_changepoints(); there is no dense post-processing.

The n_samples value stored in the TSV file (per-trial metadata) tells you exactly how long the dense array should be — you only need to additionally know the sample_rate to drive the conversion.

Functions

dense_to_intervals	Convert a dense label array to an intervals DataFrame.
intervals_to_dense	Convert an intervals DataFrame to a dense label array.
get_labels_start_end_indices	Return segment boundaries as sample indices (exclusive end).