Tag Helper

GitHub Link to Code.

Generic helper for trajectory tag operations.

Provides shared functionality for tag matching, color mapping, and legend creation across different plot types.

class mdxplain.plots.helper.tag_helper.TagHelper

Generic helper for trajectory tag operations.

Provides shared functionality for tag matching, color mapping, and legend creation across different plot types.

Examples

>>> # Get matching tags for trajectory
>>> matching = TagHelper.get_matching_tags(
...     trajectory_data, traj_idx=0, tags_for_coloring=["biased", "unbiased"]
... )
>>> print(matching)  # ["biased"]

>>> # Filter by priority (last wins)
>>> best = TagHelper.filter_by_priority(
...     matching_tags=["biased", "unbiased"],
...     tags_for_coloring=["biased", "unbiased", "other"]
... )
>>> print(best)  # "unbiased"

static get_matching_tags(trajectory_data: TrajectoryData, traj_idx: int, tags_for_coloring: List[str]) → List[str]

Get matching tags for trajectory.

Returns all tags from trajectory that appear in tags_for_coloring list.

Parameters

trajectory_dataTrajectoryData

Trajectory data container with tag information

traj_idxint

Trajectory index to get tags for

tags_for_coloringList[str]

List of tags to match against

Returns

List[str]

Matching tags (preserves order from tags_for_coloring)

Examples

>>> matching = TagHelper.get_matching_tags(
...     trajectory_data, 0, ["biased", "unbiased"]
... )

static filter_by_priority(matching_tags: List[str], tags_for_coloring: List[str]) → str | None

Get best matching tag based on priority (last wins).

When multiple tags match, returns the last one in tags_for_coloring list. This implements the “last wins” priority rule.

Parameters

matching_tagsList[str]

Tags that matched for a trajectory

tags_for_coloringList[str]

Ordered list of tags (priority: last is highest)

Returns

str or None

Best matching tag (last in tags_for_coloring) or None if no matches

Examples

>>> best = TagHelper.filter_by_priority(
...     ["biased", "unbiased"], ["biased", "unbiased", "other"]
... )
>>> print(best)  # "unbiased"

static prepare_tag_colors(tags_for_coloring: List[str]) → Dict[str, str]

Prepare tag-to-color mapping.

Uses ColorMappingHelper for consistent color assignment across plots.

Parameters

tags_for_coloringList[str]

List of tags to assign colors to

Returns

Dict[str, str]

Mapping from tag name to hex color string

Examples

>>> colors = TagHelper.prepare_tag_colors(["biased", "unbiased"])
>>> print(colors)  # {"biased": "#1f77b4", "unbiased": "#ff7f0e"}

static create_tag_legend_handles(tag_colors: Dict[str, str]) → List[Line2D]

Create legend handles for tags.

Generates matplotlib Line2D objects for each tag-color pair, suitable for use in figure legends.

Parameters

tag_colorsDict[str, str]

Mapping from tag to hex color

Returns

List[matplotlib.lines.Line2D]

Legend handles for each tag (sorted alphabetically)

Examples

>>> handles = TagHelper.create_tag_legend_handles(
...     {"biased": "#1f77b4", "unbiased": "#ff7f0e"}
... )