pdstools.utils.metric_limits¶

Metric limits and NBAD configuration utilities.

The MetricLimits.csv in resources defines min/max and best practice values for CDH/DSM metrics. It currently is sourced from an Excel file that gets exported to CSV (no special options, just straight export) and copied into this library.

This module provides access methods to this data and validation functions that turn metric values into “RAG” indicators that can be used to highlight values in tables.

Attributes¶

`RAGValue`
`ValueMapping`
`MetricSpec`
`SINGLE_CHANNEL_NBAD_CONFIGURATIONS`
`POTENTIALLY_MULTI_CHANNEL_NBAD_CONFIGURATIONS`
`ALL_NBAD_CONFIGURATIONS`
`STANDARD_NBAD_CHANNELS`
`_NBAD_PREDICTION_DATA`
`SINGLE_CHANNEL_NBAD_PREDICTIONS`
`MULTI_CHANNEL_NBAD_PREDICTIONS`
`ALL_NBAD_PREDICTIONS`

Classes¶

`MetricLimits`	Singleton for accessing metric limits from MetricLimits.csv.
`MetricFormats`	Registry of predefined number formats for common metrics.

Functions¶

`_convert_excel_csv_value`(→ Union[float, bool, None])	Convert Excel/CSV value to Python type (float, bool, or None).
`_normalize_name`(→ str)	Normalize a name by removing whitespace, dashes, underscores and lowercasing.
`_matches_NBAD_configuration`(→ bool)	Check if item matches any config in the list.
`is_standard_NBAD_configuration`(→ polars.Expr)	Polars expression to check if a configuration is a known NBAD config.
`standard_NBAD_configurations_rag`(→ Optional[RAGValue])	RAG status for NBAD configuration names.
`get_standard_NBAD_channels`(→ list[str])	Get the list of standard NBAD channel names.
`standard_NBAD_channels_rag`(→ Optional[RAGValue])	RAG status for NBAD channel names.
`standard_NBAD_directions_rag`(→ Optional[RAGValue])	RAG status for NBAD direction names. GREEN for Inbound/Outbound, AMBER otherwise.
`get_predictions_channel_mapping`(→ polars.DataFrame)	Get prediction to channel/direction mapping as a DataFrame.
`is_standard_NBAD_prediction`(→ polars.Expr)	Polars expression to check if a prediction is a known NBAD prediction.
`standard_NBAD_predictions_rag`(→ Optional[RAGValue])	RAG status for NBAD prediction names.
`exclusive_0_1_range_rag`(→ Optional[RAGValue])	RAG for percentage values. GREEN if 0 < value < 1, RED otherwise.
`positive_values`(→ Optional[RAGValue])
`strict_positive_values`(→ Optional[RAGValue])
`add_rag_columns`(→ polars.DataFrame)	Add RAG status columns to a DataFrame.

Module Contents¶

RAGValue¶

ValueMapping¶

MetricSpec¶

_convert_excel_csv_value(value: str) → float | bool | None¶

Convert Excel/CSV value to Python type (float, bool, or None).

Parameters:: value (str)
Return type:: Union[float, bool, None]

_normalize_name(name: str) → str¶

Normalize a name by removing whitespace, dashes, underscores and lowercasing.

Parameters:: name (str)
Return type:: str

class MetricLimits¶

Singleton for accessing metric limits from MetricLimits.csv.

_instance: MetricLimits | None = None¶

classmethod get_limits() → polars.DataFrame¶

Get all metric limits as a DataFrame.

Return type:: polars.DataFrame

classmethod get_limit_for_metric(metric_id: str) → dict¶

Get limits for a specific metric. Returns empty dict if not found.

Parameters:: metric_id (str)
Return type:: dict

classmethod _get_limit_or_raise(metric_id: str) → dict¶

Get limits for a metric, raising KeyError if not found.

Parameters:: metric_id (str)
Return type:: dict

classmethod minimum(metric_id: str) → float | None¶

Get the minimum (hard limit) for a metric.

Raises KeyError if metric_id is not found in MetricLimits.csv.

Parameters:: metric_id (str)
Return type:: Optional[float]

classmethod maximum(metric_id: str) → float | None¶

Get the maximum (hard limit) for a metric.

Raises KeyError if metric_id is not found in MetricLimits.csv.

Parameters:: metric_id (str)
Return type:: Optional[float]

classmethod best_practice_min(metric_id: str) → float | bool | None¶

Get the best practice minimum for a metric.

Raises KeyError if metric_id is not found in MetricLimits.csv.

Parameters:: metric_id (str)
Return type:: Optional[Union[float, bool]]

classmethod best_practice_max(metric_id: str) → float | bool | None¶

Get the best practice maximum for a metric.

Raises KeyError if metric_id is not found in MetricLimits.csv.

Parameters:: metric_id (str)
Return type:: Optional[Union[float, bool]]

classmethod evaluate_metric_rag(metric_id: str, value) → RAGValue | None¶

Evaluate RAG status for a metric value.

Parameters:

metric_id (str) – The metric identifier from MetricLimits.csv.
value (Any) – The value to evaluate (numeric or boolean).

Returns:

“RED”, “AMBER”, “GREEN”, or None if metric not found or value is None.

Return type:

Optional[RAGValue]

Raises:

TypeError – If the value is not a valid type for the metric (e.g., string instead of numeric).

Notes

For boolean metrics: - If TRUE is in Minimum or Maximum (hard limit): TRUE → GREEN, FALSE → RED - If TRUE is in Best Practice Min or Max (soft limit): TRUE → GREEN, FALSE → AMBER

classmethod get_metric_RAG_code(column: str, metric_id: str) → polars.Expr¶

Generate a Polars expression that evaluates metric status as RED/AMBER/GREEN.

Uses evaluate_metric_rag internally via map_elements to ensure consistent RAG logic between Python and Polars approaches.

Parameters:

column (str)
metric_id (str)

Return type:

polars.Expr

SINGLE_CHANNEL_NBAD_CONFIGURATIONS = ['Web_Click_Through_Rate', 'WebTreatmentClickModel', 'Mobile_Click_Through_Rate',...¶

POTENTIALLY_MULTI_CHANNEL_NBAD_CONFIGURATIONS = ['Default_Inbound_Model', 'Default_Outbound_Model', 'Default_Click_Through_Rate',...¶

ALL_NBAD_CONFIGURATIONS = ['Web_Click_Through_Rate', 'WebTreatmentClickModel', 'Mobile_Click_Through_Rate',...¶

_matches_NBAD_configuration(item: str, config_list: list) → bool¶

Check if item matches any config in the list.

Matches with optional prefix (e.g., MyApp_) and postfix (e.g., _GB). Pattern: ^(?:w+_)?{config}(?:_GB)?$

Parameters:

item (str)
config_list (list)

Return type:

bool

is_standard_NBAD_configuration(field: str = 'Configuration') → polars.Expr¶

Polars expression to check if a configuration is a known NBAD config.

Parameters:: field (str)
Return type:: polars.Expr

standard_NBAD_configurations_rag(value: str) → RAGValue | None¶

RAG status for NBAD configuration names.

Returns AMBER if any is a default/other/multi-channel or a non-standard configuration, GREEN if all are standard single-channel configurations.

Parameters:: value (str)
Return type:: Optional[RAGValue]

STANDARD_NBAD_CHANNELS = ['Web', 'Mobile', 'E-mail', 'Push', 'SMS', 'Retail', 'Call Center', 'Assisted']¶

get_standard_NBAD_channels() → list[str]¶

Get the list of standard NBAD channel names.

Return type:: list[str]

standard_NBAD_channels_rag(value: str) → RAGValue | None¶

RAG status for NBAD channel names.

Returns GREEN for standard channels, YELLOW for Other, AMBER for multi-channel/unknown.

Parameters:: value (str)
Return type:: Optional[RAGValue]

standard_NBAD_directions_rag(value: str) → RAGValue | None¶

RAG status for NBAD direction names. GREEN for Inbound/Outbound, AMBER otherwise.

Parameters:: value (str)
Return type:: Optional[RAGValue]

_NBAD_PREDICTION_DATA = [['PredictWebPropensity', 'Web', 'Inbound', False], ['PredictMobilePropensity', 'Mobile',...¶

SINGLE_CHANNEL_NBAD_PREDICTIONS¶

MULTI_CHANNEL_NBAD_PREDICTIONS¶

ALL_NBAD_PREDICTIONS¶

get_predictions_channel_mapping(custom_predictions: list | None = None) → polars.DataFrame¶

Get prediction to channel/direction mapping as a DataFrame.

Parameters:: custom_predictions (Optional[list])
Return type:: polars.DataFrame

is_standard_NBAD_prediction(field: str = 'Prediction') → polars.Expr¶

Polars expression to check if a prediction is a known NBAD prediction.

Parameters:: field (str)
Return type:: polars.Expr

standard_NBAD_predictions_rag(value: str) → RAGValue | None¶

RAG status for NBAD prediction names.

Returns GREEN for single-channel, YELLOW for multi-channel, AMBER for unknown.

Parameters:: value (str)
Return type:: Optional[RAGValue]

exclusive_0_1_range_rag(value: float) → RAGValue | None¶

RAG for percentage values. GREEN if 0 < value < 1, RED otherwise.

Parameters:: value (float)
Return type:: Optional[RAGValue]

positive_values(value: float) → RAGValue | None¶

Parameters:: value (float)
Return type:: Optional[RAGValue]

strict_positive_values(value: float) → RAGValue | None¶

Parameters:: value (float)
Return type:: Optional[RAGValue]

add_rag_columns(df: polars.DataFrame, column_to_metric: dict[str, MetricSpec] | None = None, strict_metric_validation: bool = True) → polars.DataFrame¶

Add RAG status columns to a DataFrame.

For each column, adds a new column with suffix ‘_RAG’ containing the RAG status (RED/AMBER/YELLOW/GREEN or None).

Parameters:

df (pl.DataFrame) – The source DataFrame.
column_to_metric (dict, optional) –
Mapping from column names (or tuples of column names) to one of:
- str: metric ID to look up in MetricLimits.csv
- callable: function(value) -> “RED”|”AMBER”|”YELLOW”|”GREEN”|None
- tuple: (metric_id, value_mapping) where value_mapping is a dict that maps column values to metric values before evaluation. Supports tuple keys: {(“Yes”, “yes”): True, “No”: False}
If a column is not in this dict, its name is used as the metric ID.
strict_metric_validation (bool, default True) – If True, raises ValueError if a metric ID is not found in MetricLimits.csv.

Returns:

DataFrame with additional _RAG columns.

Return type:

pl.DataFrame

Examples

>>> from pdstools.utils.metric_limits import add_rag_columns
>>> df_with_rag = add_rag_columns(
...     df,
...     column_to_metric={
...         "Performance": "ModelPerformance",
...         "AGB": ("UsingAGB", {"Yes": True, "No": False}),
...     }
... )

class MetricFormats¶

Registry of predefined number formats for common metrics.

Provides centralized format definitions for use across table rendering backends (great_tables, itables, etc.).

Examples

>>> MetricFormats.get("ModelPerformance").format_value(0.875)
'0.88'
>>> MetricFormats.has_format("CTR")
True
>>> MetricFormats.register("Custom", NumberFormat(decimals=4))