evaluma.metric_registry

Metric name registry: maps names to optimization direction and natural bounds.

Attributes

KNOWN_METRICS
_METRIC_ERROR_OPTIMUM
_KNOWN_LIST

Functions

get_direction(→ str)	Return "min" or "max" for a known metric name.
get_natural_bounds(→ tuple)	Return (natural_low, natural_high) for a known metric name.
get_error_optimum(→ float)	Return the theoretical error optimum for a known metric name.

Module Contents

evaluma.metric_registry.KNOWN_METRICS

evaluma.metric_registry._METRIC_ERROR_OPTIMUM

evaluma.metric_registry._KNOWN_LIST = ''

evaluma.metric_registry.get_direction(metric_name: str) → str

Return "min" or "max" for a known metric name.

Parameters:

metric_name – Metric identifier (case-insensitive).

Returns:

"min" (lower is better) or "max" (higher is better).

Return type:

str

Raises:

ValueError – If metric_name is not in the registry. The message lists all known names and suggests using metric_direction for custom metrics.

evaluma.metric_registry.get_natural_bounds(metric_name: str) → tuple

Return (natural_low, natural_high) for a known metric name.

natural_high is None for unbounded metrics (e.g. rmse, mae), meaning the upper bound must be supplied by the caller.

Parameters:

metric_name – Metric identifier (case-insensitive).

Returns:

(float, float | None) natural lower and upper bounds.

Return type:

tuple

Raises:

ValueError – If metric_name is not in the registry.

evaluma.metric_registry.get_error_optimum(metric_name: str) → float

Return the theoretical error optimum for a known metric name.

This is the metric’s perfect-score value in raw score space (1.0 for bounded max metrics and r2, 0.0 for min metrics), used to reconstruct raw error independently of normalization bounds.

Parameters:

metric_name – Metric identifier (case-insensitive).

Returns:

The theoretical optimum score for the metric.

Return type:

float

Raises:

ValueError – If metric_name has no defined optimum. The message lists all known names and explains the current improvability fallback.