Vertical Marker Helper

GitHub Link to Code.

Shared helpers for vertical marker validation and legend preparation.

class mdxplain.plots.helper.vertical_marker_helper.VerticalMarkerHelper

Utility methods for marker parsing, validation, and legend entries.

static validate_markers(marker_positions: Dict[int | str, float | List[float] | Tuple[float, ...]] | None, key_context: str) → None

Validate marker dictionary structure.

Parameters

marker_positionsdict or None

Marker position dictionary.

key_contextstr

Human-readable key context for error messages.

Returns

None

Validation helper; returns only when values are valid.

Raises

ValueError

If marker_positions is not a dictionary, contains invalid keys, or contains invalid position values.

static validate_labels(marker_positions: Dict[int | str, float | List[float] | Tuple[float, ...]] | None, marker_labels: str | Dict[int | str, str] | None) → None

Validate marker label structure.

Parameters

marker_positionsdict or None

Marker position dictionary.

marker_labelsstr or dict or None

Marker legend labels.

Returns

None

Validation helper; returns only when values are valid.

Raises

ValueError

If label structure is invalid, references unknown marker keys, or contains non-string label values.

static validate_label_colors(marker_labels: str | Dict[int | str, str] | None, label_colors: str | Dict[str, str] | None) → None

Validate optional label-to-color overrides.

Parameters

marker_labelsstr or dict or None

Marker legend labels.

label_colorsstr or dict or None

Legend color override:

• str: one shared color for all marker legend labels

• dict[label] = color: per-label legend colors

Returns

None

Validation helper; returns only when values are valid.

Raises

ValueError

If color override structure is invalid, contains non-string values, or references labels that are not present in marker_labels.

static normalize_positions(raw_positions: float | List[float] | Tuple[float, ...], selector_key: int | str) → List[float]

Normalize one marker value entry to a list of numeric x-positions.

Parameters

raw_positionsfloat or List[float] or Tuple[float, …]

Marker position definition for one key.

selector_keyint or str

Key used for error context in validation messages.

Returns

List[float]

Normalized marker positions as float values.

Raises

ValueError

If raw_positions is neither numeric nor a list/tuple of numerics.

static resolve_markers(marker_positions: Dict[int | str, float | List[float] | Tuple[float, ...]] | None, marker_labels: str | Dict[int | str, str] | None, color_resolver: Callable[[int | str], List[str]], legend_entries: Dict[str, str] | None = None, label_colors: str | Dict[str, str] | None = None) → List[Tuple[float, str, str | None]]

Resolve marker dictionaries to unique (x, color, label) tuples.

Parameters

marker_positionsMarkerPositions

Marker definition dictionary mapping keys to x-position values.

marker_labelsMarkerLabels

Marker labels as shared string or per-key string dictionary.

color_resolverCallable[[int or str], List[str]]

Callback that resolves one marker key to one or many colors.

legend_entriesDict[str, str], optional

Optional output mapping populated with unique legend entries in first-seen order (label -> color).

label_colorsstr or dict or None, optional

Optional legend color override: shared color string or dictionary (label -> color).

Returns

List[ResolvedMarker]

Resolved marker tuples for plotting and legend generation.

Notes

Markers are deduplicated by (x_position, color). When duplicates are encountered, labeled variants take precedence over unlabeled ones.

static build_legend_handles(resolved_markers: List[Tuple[float, str, str | None]], legend_entries: Dict[str, str] | None = None, line_width: float = 1.5, alpha: float = 0.85) → List[Line2D]

Build unique legend handles for resolved markers that have labels.

Parameters

resolved_markersList[ResolvedMarker]

Normalized marker tuples.

legend_entriesDict[str, str], optional

Optional pre-resolved legend entries (label -> color). When provided, handles are built from this mapping directly.

line_widthfloat, default=1.5

Legend line width for marker handles.

alphafloat, default=0.85

Legend line transparency.

Returns

List[Line2D]

Legend handles with unique labels in first-seen order.