pdstools.utils.color_mapping

Generic color mapping utilities for categorical data in Streamlit apps.

This module provides utilities for creating consistent color mappings for categorical dimensions across Streamlit applications. Color consistency is critical for user experience when filtering/interacting with visualizations.

Functions

create_categorical_color_mappings(→ dict[str, ...)

Create consistent color mappings for categorical columns.

Module Contents

create_categorical_color_mappings(data: polars.LazyFrame, columns: list[str], colorway: list[str], column_mapping: dict[str, str] | None = None) → dict[str, dict[str, str]]

Create consistent color mappings for categorical columns.

Computes color assignments for categorical dimensions based on all unique values in the dataset, sorted alphabetically. This ensures colors remain consistent throughout a session regardless of filtering.

Parameters:

  • data (pl.LazyFrame) – Source data containing the categorical columns.

  • columns (list[str]) – List of column names to create color mappings for. Can be display names if column_mapping is provided.

  • colorway (list[str]) – List of color hex codes to assign (e.g., [“#001F5F”, “#10A5AC”, …]). Colors are assigned using modulo indexing if there are more unique values than colors.

  • column_mapping (dict[str, str], optional) – Optional mapping from display names to internal column names. Example: {“Issue”: “pyIssue”, “Group”: “pyGroup”}

Returns:

Nested dictionary mapping column names to color dictionaries. Example: {

”Issue”: {“Retention”: “#001F5F”, “Sales”: “#10A5AC”}, “Group”: {“Cards”: “#001F5F”, “Loans”: “#10A5AC”},

}

Return type:

dict[str, dict[str, str]]

Examples

>>> data = pl.LazyFrame({"Category": ["A", "B", "C"]})
>>> colors = ["#FF0000", "#00FF00"]
>>> mappings = create_categorical_color_mappings(data, ["Category"], colors)
>>> mappings["Category"]["A"]
'#FF0000'
>>> mappings["Category"]["C"]  # Wraps around
'#FF0000'

Notes

  • Missing columns are skipped silently

  • Null values are dropped from unique value computation

  • Empty columns return empty color dictionaries

  • Values are sorted alphabetically for deterministic color assignment

  • Colors wrap using modulo indexing when categories exceed colorway length