update table colors and styling

Author: SvenKlaassen

doc/index.qmd

@@ -28,9 +28,26 @@ $$
 for a nominal coverage level is $1-\alpha$.
 The corresponding coverage results are highlighted according to the following color scheme:
 
-* <span style="background-color: #00FF00; color: black; padding: 2px 5px; border-radius: 3px;">Green</span> if the deviation to the nominal level is below $5\%$
-* <span style="background-color: #FFFF00; color: black; padding: 2px 5px; border-radius: 3px;">Yellow</span> if the deviation to the nominal level is above $5\%$ and below $10\%$
-* <span style="background-color: #FF0000; color: black; padding: 2px 5px; border-radius: 3px;">Red</span> if the deviation to the nominal level is above $10\%$
+```{python}
+#| echo: false
+#| output: asis
+from utils.styling import get_html_color_span
+
+# Generate color legend using centralized configuration
+good_span = get_html_color_span("good")
+medium_span = get_html_color_span("medium")
+poor_span = get_html_color_span("poor")
+
+from IPython.display import Markdown, display
+
+markdown_output = f"""
+* {good_span} if the deviation to the nominal level is below 5%
+* {medium_span} if the deviation to the nominal level is above 5% and below 10%
+* {poor_span} if the deviation to the nominal level is above 10%
+"""
+
+display(Markdown(markdown_output))
+```
 
 For simulations with multiple parameters of interest, usually pointwise and uniform coverage is assessed.
 
@@ -247,5 +264,3 @@ fig.show()
 ```
 
 :::
-
-:::

doc/utils/style_tables.py

@@ -3,17 +3,21 @@
 from pandas.io.formats.style import Styler
 from typing import Union, Optional, List, Any
 from itables import show
+from .styling import (
+    TABLE_STYLING,
+    COVERAGE_THRESHOLDS,
+    get_coverage_tier_props,
+)
 
 
-# Define highlighting tiers as a list of dictionaries or tuples
-# Each element defines: dist, props. Applied in order (later rules can override).
-# Order: from least specific (largest dist) to most specific (smallest dist)
-# or ensure the _apply_highlight_range logic correctly handles overlaps if props are different.
-# Current logic: more specific (smaller dist) rules are applied last and override.
+# Define highlighting tiers using centralized color configuration
 HIGHLIGHT_TIERS = [
-    {"dist": 1.0, "props": "color:black;background-color:red;"},
-    {"dist": 0.1, "props": "color:black;background-color:yellow;"},
-    {"dist": 0.05, "props": "color:white;background-color:darkgreen;"},
+    {"dist": COVERAGE_THRESHOLDS["poor"], "props": get_coverage_tier_props("poor")},
+    {
+        "dist": COVERAGE_THRESHOLDS["medium"],
+        "props": get_coverage_tier_props("medium", "500"),
+    },
+    {"dist": COVERAGE_THRESHOLDS["good"], "props": get_coverage_tier_props("good")},
 ]
 
 
@@ -34,6 +38,77 @@ def _apply_highlight_range(
     return np.where(condition, props, "")
 
 
+def _apply_base_table_styling(styler: Styler) -> Styler:
+    """
+    Apply base styling to the table including headers, borders, and overall appearance.
+    """
+    # Define CSS styles for clean table appearance using centralized colors
+    styles = [
+        # Table-wide styling
+        {
+            "selector": "table",
+            "props": [
+                ("border-collapse", "separate"),
+                ("border-spacing", "0"),
+                ("width", "100%"),
+                (
+                    "font-family",
+                    '"Segoe UI", -apple-system, BlinkMacSystemFont, "Roboto", sans-serif',
+                ),
+                ("font-size", "14px"),
+                ("line-height", "1.5"),
+                ("box-shadow", "0 2px 8px rgba(0,0,0,0.1)"),
+                ("border-radius", "8px"),
+                ("overflow", "hidden"),
+            ],
+        },
+        # Header styling
+        {
+            "selector": "thead th",
+            "props": [
+                ("background-color", TABLE_STYLING["header_bg"]),
+                ("color", TABLE_STYLING["header_text"]),
+                ("font-weight", "600"),
+                ("text-align", "center"),
+                ("padding", "12px 16px"),
+                ("border-bottom", f'2px solid {TABLE_STYLING["border"]}'),
+                ("position", "sticky"),
+                ("top", "0"),
+                ("z-index", "10"),
+            ],
+        },
+        # Cell styling
+        {
+            "selector": "tbody td",
+            "props": [
+                ("padding", "10px 16px"),
+                ("text-align", "center"),
+                ("border-bottom", f'1px solid {TABLE_STYLING["border"]}'),
+                ("transition", "background-color 0.2s ease"),
+            ],
+        },
+        # Row hover effect
+        {
+            "selector": "tbody tr:hover td",
+            "props": [("background-color", TABLE_STYLING["hover_bg"])],
+        },
+        # Caption styling
+        {
+            "selector": "caption",
+            "props": [
+                ("color", TABLE_STYLING["caption_color"]),
+                ("font-size", "16px"),
+                ("font-weight", "600"),
+                ("margin-bottom", "16px"),
+                ("text-align", "left"),
+                ("caption-side", "top"),
+            ],
+        },
+    ]
+
+    return styler.set_table_styles(styles)
+
+
 def color_coverage_columns(
     styler: Styler, level: float, coverage_cols: list[str] = ["Coverage"]
 ) -> Styler:
@@ -54,13 +129,15 @@ def color_coverage_columns(
     if not valid_coverage_cols:
         return styler  # No valid columns to style
 
+    # Apply base styling first
+    current_styler = _apply_base_table_styling(styler)
+
     # Apply highlighting rules from the defined tiers
     # The order in HIGHLIGHT_TIERS is important if props are meant to override.
     # Pandas Styler.apply applies styles sequentially. If a cell matches multiple
     # conditions from different .apply calls, the styles from later calls typically override
     # or merge with earlier ones, depending on the CSS properties.
     # For background-color, later calls will override.
-    current_styler = styler
     for tier in HIGHLIGHT_TIERS:
         current_styler = current_styler.apply(
             _apply_highlight_range,
@@ -70,10 +147,12 @@ def color_coverage_columns(
             subset=valid_coverage_cols,
         )
 
-    # Set font to bold for the coverage columns
+    # Apply additional styling to coverage columns for emphasis
     current_styler = current_styler.set_properties(
-        **{"font-weight": "bold"}, subset=valid_coverage_cols
+        **{"text-align": "center", "font-family": "monospace", "font-size": "13px"},
+        subset=valid_coverage_cols,
     )
+
     return current_styler
 
 

doc/utils/styling.py

@@ -0,0 +1,90 @@
+"""
+Styling utilities for DoubleML Coverage tables and documentation.
+
+This module provides helper functions for applying consistent styling
+based on the centralized theme configuration.
+"""
+
+import yaml
+from pathlib import Path
+from typing import Dict, Any
+
+
+def _load_theme_config() -> Dict[str, Any]:
+    """Load theme configuration from YAML file."""
+    config_path = Path(__file__).parent / "theme.yml"
+    with open(config_path, "r") as f:
+        return yaml.safe_load(f)
+
+
+# Load configuration once at module import
+_THEME = _load_theme_config()
+
+# Expose configuration for backward compatibility and direct access
+COVERAGE_COLORS = _THEME["coverage_colors"]
+TABLE_STYLING = _THEME["table_styling"]
+COVERAGE_THRESHOLDS = _THEME["coverage_thresholds"]
+
+
+def get_coverage_tier_props(tier: str, font_weight: str = "600") -> str:
+    """
+    Generate CSS properties string for a coverage performance tier.
+
+    Args:
+        tier: One of 'good', 'medium', 'poor'
+        font_weight: CSS font-weight value
+
+    Returns:
+        CSS properties string for use with pandas Styler
+    """
+    if tier not in COVERAGE_COLORS:
+        raise ValueError(
+            f"Unknown tier '{tier}'. Must be one of: {list(COVERAGE_COLORS.keys())}"
+        )
+
+    colors = COVERAGE_COLORS[tier]
+    return (
+        f"color:{colors['text']};"
+        f"background-color:{colors['background']};"
+        f"border-left:4px solid {colors['border']};"
+        f"font-weight:{font_weight};"
+    )
+
+
+def get_html_color_span(tier: str, text: str = None) -> str:
+    """
+    Generate HTML span element with coverage tier styling for documentation.
+
+    Args:
+        tier: One of 'good', 'medium', 'poor'
+        text: Text to display (defaults to tier description)
+
+    Returns:
+        HTML span element with inline styling
+    """
+    if tier not in COVERAGE_COLORS:
+        raise ValueError(
+            f"Unknown tier '{tier}'. Must be one of: {list(COVERAGE_COLORS.keys())}"
+        )
+
+    colors = COVERAGE_COLORS[tier]
+    display_text = text or colors["description"]
+
+    return (
+        f'<span style="background-color: {colors["background"]}; '
+        f'color: {colors["text"]}; '
+        f"padding: 2px 5px; "
+        f"border-radius: 3px; "
+        f'border-left: 3px solid {colors["border"]};">'
+        f"{display_text}</span>"
+    )
+
+
+def get_theme_config() -> Dict[str, Any]:
+    """
+    Get the complete theme configuration.
+
+    Returns:
+        Dictionary containing all theme settings
+    """
+    return _THEME.copy()

doc/utils/theme.yml

@@ -0,0 +1,31 @@
+# DoubleML Coverage Theme Configuration
+# Central color palette and styling settings
+
+coverage_colors:
+  good:
+    background: "#d1e7dd"
+    text: "#0f5132"
+    border: "#198754"
+    description: "Green"
+  medium:
+    background: "#fff3cd"
+    text: "#856404"
+    border: "#ffc107"
+    description: "Amber"
+  poor:
+    background: "#f8d7da"
+    text: "#721c24"
+    border: "#dc3545"
+    description: "Coral"
+
+table_styling:
+  header_bg: "#f8f9fa"
+  header_text: "#495057"
+  border: "#dee2e6"
+  caption_color: "#6c757d"
+  hover_bg: "#f5f5f5"
+
+coverage_thresholds:
+  good: 0.05    # Within 5% of nominal level
+  medium: 0.1   # Within 10% of nominal level
+  poor: 1.0     # Beyond 10% of nominal level