ethograph.labels.intervals.load_label_mapping#

ethograph.labels.intervals.load_label_mapping(mapping_file='mapping.txt')[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". Missing trailing columns inherit their defaults.
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'
>>> mappings[1]["color"].shape
(3,)

Use the RGB colors to draw labelled rectangles 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"]  # (3,) RGB in [0, 1]
    ax.axvspan(row["onset_s"], row["offset_s"], alpha=0.5, color=color)

# Build a legend from the mapping
handles = [
    mpatches.Patch(color=m["color"], label=m["name"])
    for m in mappings.values()
]
ax.legend(handles=handles)
plt.show()