Alias Utility

Alias resolution utilities for tolerant column and key matching.

This module provides functions for resolving canonical ReaxKit keys (e.g., iter, time, D) against the actual column names present in parsed DataFrames, using a packaged alias map.

The canonical→alias definitions are stored in reaxkit/data/alias.yaml.

load_default_alias_map() cached

Load the packaged canonical→aliases mapping.

The alias map is read from reaxkit/data/alias.yaml and cached after the first call.

Returns:

Type	Description
dict[str, list[str]]	Mapping of canonical keys to accepted alias strings.

Raises:

Type	Description
FileNotFoundError	If the packaged alias.yaml cannot be found.

normalize_choice(value, domain='xaxis')

Normalize a user-provided keyword to its canonical alias key.

This is intended for tolerant CLI inputs where users may provide any alias defined in alias.yaml (e.g., Time(fs) → time).

Parameters:

Name	Type	Description	Default
value	str	User-provided keyword or alias.	required
domain	str	Reserved for future domain-specific normalization rules.	'xaxis'

Returns:

Type	Description
str	Canonical key if an alias match is found; otherwise the normalized input string.

Examples:

>>> normalize_choice("Time(fs)")
>>> normalize_choice("frm")

resolve_alias_from_columns(cols, canonical, aliases=None)

Resolve a canonical key to the matching column name in a column list.

Matching is case-insensitive and falls back to simple heuristics when an exact alias match is not found.

Parameters:

Name	Type	Description	Default
cols	iterable of str	Available column names (e.g., DataFrame columns).	required
canonical	str	Canonical key to resolve (e.g., "iter", "time", "D").	required
aliases	dict[str, list[str]]	Canonical→aliases mapping to use. If not provided, the packaged map from alias.yaml is loaded.	None

Returns:

Type	Description
str or None	The matching column name if found, otherwise None.

Examples:

>>> resolve_alias_from_columns(df.columns, "time")