ethograph.labels.intervals.load_label_mapping#

ethograph.labels.intervals.load_label_mapping(mapping_file='mapping.txt', order=None)[source]#

Load a label mapping with colors for visualization.

Parameters:

mapping_file (str or Path) – Path to the mapping file. Each line is <id> <name> [<branch>] [<event_type>] where branch is an optional integer (default 0) grouping labels into branches for independent labeling, and event_type is "state" (default) or "point".
order (list[int] or None) – Label IDs in the desired display sequence. If provided, overrides the default order (which follows label ID). Any ID not listed retains its default position.

Returns:

{label_id: {"name": str, "color": ndarray(3,), "order": int, "branch": int, "event_type": str}}.

Return type:

dict[int, dict]

Raises:

FileNotFoundError – If mapping_file does not exist.

Examples

>>> mappings = load_label_mapping("mapping.txt")
>>> mappings[1]["name"]
'walk'

Reorder labels for display without changing the file:

mappings = load_label_mapping("mapping.txt", order=[0, 3, 1, 2])

Draw labelled intervals on a plot:

import matplotlib.pyplot as plt
import matplotlib.patches as mpatches

mappings = load_label_mapping("mapping.txt")
fig, ax = plt.subplots()
ax.plot(time, signal)
for _, row in intervals_df.iterrows():
    color = mappings[int(row["labels"])]["color"]
    ax.axvspan(row["onset_s"], row["offset_s"], alpha=0.5, color=color)
handles = [mpatches.Patch(color=m["color"], label=m["name"]) for m in mappings.values()]
ax.legend(handles=handles)
plt.show()