update(heatmap-basic): letsplot — comprehensive quality review (#4260)

## Summary

Updated **letsplot** implementation for **heatmap-basic**.

**Changes:** Comprehensive quality review — fix weaknesses from prior
reviews, preserve strengths, improve quality across all dimensions.

### Changes
- Addressed review weaknesses from prior quality assessment
- Improved data choice and visual design
- Enhanced library-specific feature usage
- Updated to current library and Python versions
- Quality self-assessment: pending CI review

## Test Plan

- [x] Preview images uploaded to GCS staging
- [x] Implementation file passes ruff format/check
- [x] Metadata YAML updated with current versions
- [ ] Automated review triggered

---
Generated with [Claude Code](https://claude.com/claude-code) `/update`
command

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: MarkusNeusinger

plots/heatmap-basic/implementations/letsplot.py

@@ -1,21 +1,27 @@
 """ pyplots.ai
 heatmap-basic: Basic Heatmap
-Library: letsplot 4.8.1 | Python 3.13.11
-Quality: 91/100 | Created: 2025-12-23
+Library: letsplot 4.8.2 | Python 3.14.3
+Quality: 91/100 | Updated: 2026-02-15
 """
 
 import numpy as np
-import pandas as pd
 from lets_plot import (
     LetsPlot,
     aes,
+    element_blank,
+    element_rect,
     element_text,
     geom_text,
     geom_tile,
     ggplot,
     ggsize,
+    guide_colorbar,
     labs,
-    scale_fill_gradient2,
+    layer_tooltips,
+    scale_color_identity,
+    scale_fill_viridis,
+    scale_x_discrete,
+    scale_y_discrete,
     theme,
     theme_minimal,
 )
@@ -24,55 +30,67 @@
 
 LetsPlot.setup_html()
 
-# Data - Department performance scores by quarter
+# Data - Monthly energy consumption (kWh) by building zone
 np.random.seed(42)
-departments = ["Sales", "Marketing", "R&D", "Operations", "Finance", "HR"]
-quarters = ["Q1", "Q2", "Q3", "Q4", "Q5", "Q6", "Q7", "Q8"]
+months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+zones = ["Lobby", "Offices", "Lab", "Server Room", "Cafeteria", "Warehouse"]
 
-# Generate performance scores with some patterns
-n_rows = len(quarters)
-n_cols = len(departments)
-base_scores = np.random.rand(n_rows, n_cols) * 60 + 20  # Range 20-80
+# Realistic patterns: seasonal variation + zone-specific baselines
+baselines = np.array([120, 280, 350, 520, 180, 90])
+seasonal = np.array([1.3, 1.2, 1.0, 0.8, 0.7, 0.75, 0.85, 0.9, 0.8, 0.9, 1.1, 1.25])
 
-# Add some trend patterns to make data more interesting
-trend = np.linspace(0, 15, n_rows).reshape(-1, 1)  # Slight upward trend
-values = base_scores + trend
-values = np.clip(values, 15, 95)  # Keep in realistic range
-values = np.round(values, 1)
+values = np.outer(seasonal, baselines)
+noise = np.random.normal(0, 15, (len(months), len(zones)))
+values = np.round(values + noise, 0).astype(int)
 
-# Create long-form DataFrame for lets-plot
-rows = []
-for i, quarter in enumerate(quarters):
-    for j, dept in enumerate(departments):
-        rows.append({"Department": dept, "Quarter": quarter, "Score": values[i, j]})
+# Build long-form data using vectorized operations
+n_months, n_zones = len(months), len(zones)
+zone_col = np.tile(zones, n_months).tolist()
+month_col = np.repeat(months, n_zones).tolist()
+kwh_col = values.flatten().tolist()
 
-df = pd.DataFrame(rows)
+# Adaptive text color: white on dark cells, dark on light cells
+median_val = int(np.median(kwh_col))
+text_color = ["#ffffff" if v > median_val else "#1a1a2e" for v in kwh_col]
 
-# Preserve category order (reverse quarters for top-to-bottom display)
-df["Department"] = pd.Categorical(df["Department"], categories=departments, ordered=True)
-df["Quarter"] = pd.Categorical(df["Quarter"], categories=quarters[::-1], ordered=True)
+data = {"Zone": zone_col, "Month": month_col, "kWh": kwh_col, "label_color": text_color}
 
-# Create heatmap using geom_tile with value annotations
+# Heatmap with perceptually-uniform viridis colormap and interactive tooltips
 plot = (
-    ggplot(df, aes(x="Department", y="Quarter", fill="Score"))
-    + geom_tile(width=0.95, height=0.95)
-    + geom_text(aes(label="Score"), size=14, color="white", fontface="bold")
-    + scale_fill_gradient2(low="#306998", mid="#FFD43B", high="#DC2626", midpoint=55, name="Performance\nScore")
-    + labs(x="Department", y="Quarter", title="heatmap-basic · letsplot · pyplots.ai")
+    ggplot(data, aes(x="Zone", y="Month", fill="kWh"))
+    + geom_tile(
+        width=0.92,
+        height=0.92,
+        tooltips=layer_tooltips()
+        .line("@Zone | @Month")
+        .line("Energy: @kWh kWh")
+        .line("Median: " + str(median_val) + " kWh"),
+    )
+    + geom_text(aes(label="kWh", color="label_color"), size=14, fontface="bold")
+    + scale_color_identity()
+    + scale_fill_viridis(
+        option="viridis", direction=-1, name="Energy (kWh)", guide=guide_colorbar(barwidth=18, barheight=300, nbin=256)
+    )
+    + scale_x_discrete(limits=zones)
+    + scale_y_discrete(limits=months[::-1])
+    + labs(x="Building Zone", y="Month", title="heatmap-basic · letsplot · pyplots.ai")
     + theme_minimal()
     + theme(
-        axis_title=element_text(size=20),
-        axis_text=element_text(size=16),
-        axis_text_x=element_text(angle=45),
-        plot_title=element_text(size=24),
+        plot_title=element_text(size=26, face="bold", color="#1a1a2e"),
+        axis_title=element_text(size=20, color="#2d2d44"),
+        axis_text_x=element_text(size=16, face="bold", color="#2d2d44"),
+        axis_text_y=element_text(size=16, color="#2d2d44"),
         legend_text=element_text(size=14),
-        legend_title=element_text(size=16),
+        legend_title=element_text(size=16, face="bold"),
+        panel_grid=element_blank(),
+        plot_background=element_rect(fill="#fafafa", color="#fafafa"),
+        plot_margin=[40, 20, 20, 20],
     )
     + ggsize(1600, 900)
 )
 
 # Save PNG (scale=3 gives 4800x2700)
 ggsave(plot, "plot.png", path=".", scale=3)
 
-# Save HTML for interactivity
+# Save HTML for interactive tooltips (lets-plot distinctive feature)
 ggsave(plot, "plot.html", path=".")