update(raincloud-basic): altair — fix orientation consistency (#4227)

## Summary

Updated **altair** implementation for **raincloud-basic**.

**Changes:** Fix cloud/rain orientation so cloud (half-violin/KDE)
extends UPWARD and rain (jittered points) falls DOWNWARD from each
category line.

### Changes
- Fixed orientation: cloud now extends upward (positive y-direction),
rain falls downward
- Updated spec to use absolute directional terms instead of ambiguous
"TOP"/"BELOW"
- Preserved existing review strengths

## 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

Fixes #3745

---
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/raincloud-basic/implementations/altair.py

@@ -1,7 +1,7 @@
 """ pyplots.ai
 raincloud-basic: Basic Raincloud Plot
-Library: altair 6.0.0 | Python 3.13.11
-Quality: 90/100 | Created: 2025-12-25
+Library: altair 6.0.0 | Python 3.14
+Quality: 94/100 | Created: 2025-12-25
 """
 
 import altair as alt
@@ -12,15 +12,9 @@
 # Data: Reaction times (ms) for different treatment conditions
 np.random.seed(42)
 
-# Create realistic reaction time data with different distributions
 control = np.random.normal(450, 60, 80)
-treatment_a = np.random.normal(380, 50, 80)  # Faster responses
-treatment_b = np.concatenate(
-    [
-        np.random.normal(350, 30, 50),  # Bimodal distribution
-        np.random.normal(450, 40, 30),
-    ]
-)
+treatment_a = np.random.normal(380, 50, 80)
+treatment_b = np.concatenate([np.random.normal(340, 25, 50), np.random.normal(460, 35, 30)])
 
 data = pd.DataFrame(
     {
@@ -29,43 +23,89 @@
     }
 )
 
-# Map conditions to numeric positions - HORIZONTAL: y=categories, x=values
+# Map conditions to numeric y positions with spacing
 condition_order = ["Control", "Treatment A", "Treatment B"]
-condition_map = {c: i for i, c in enumerate(condition_order)}
+condition_map = {c: i * 1.5 for i, c in enumerate(condition_order)}
 data["condition_num"] = data["condition"].map(condition_map)
 
-# Create jittered y positions for strip plot (rain BELOW the cloud)
-np.random.seed(42)
-data["jitter"] = np.random.uniform(-0.35, -0.15, len(data))
-data["jitter_pos"] = data["condition_num"] + data["jitter"]
+# Jitter positions for rain — BELOW baseline
+data["jitter_pos"] = data["condition_num"] + np.random.uniform(-0.30, -0.08, len(data))
+
+# Box plot statistics per condition (streamlined)
+box_rows = []
+for cond in condition_order:
+    vals = data.loc[data["condition"] == cond, "reaction_time"]
+    q1, med, q3 = vals.quantile([0.25, 0.5, 0.75])
+    iqr = q3 - q1
+    box_rows.append(
+        {
+            "condition": cond,
+            "condition_num": condition_map[cond],
+            "q1": q1,
+            "median": med,
+            "q3": q3,
+            "lower_w": max(q1 - 1.5 * iqr, vals.min()),
+            "upper_w": min(q3 + 1.5 * iqr, vals.max()),
+        }
+    )
+box_df = pd.DataFrame(box_rows)
+
+# Color palette: Python Blue, dark gold (high contrast), fresh green
+colors = ["#306998", "#D4A017", "#4CAF50"]
 
-# Half-violin (cloud) - positioned on TOP (positive y offset from center)
+# Tighten x domain to actual data range
+x_min = data["reaction_time"].min()
+x_max = data["reaction_time"].max()
+x_pad = (x_max - x_min) * 0.06
+x_scale = alt.Scale(domain=[round(x_min - x_pad, -1), round(x_max + x_pad, -1)])
+y_domain = [-0.5, 3.9]
+x_axis = alt.Axis(
+    titleFontSize=22,
+    titleFontWeight="bold",
+    titleColor="#333333",
+    labelFontSize=18,
+    labelColor="#555555",
+    grid=True,
+    gridOpacity=0.25,
+    gridColor="#d0d0d0",
+    gridDash=[3, 3],
+    domainColor="#999999",
+    tickColor="#999999",
+    tickCount=8,
+)
+
+# Half-violin cloud — extends ABOVE baseline
 violin = (
     alt.Chart(data)
     .transform_density(
-        "reaction_time", as_=["reaction_time", "density"], groupby=["condition", "condition_num"], extent=[200, 600]
-    )
-    .transform_calculate(
-        # Scale density and offset to create half-violin on TOP (positive y direction)
-        violin_pos="datum.condition_num + 0.05 + datum.density * 180"
+        "reaction_time",
+        as_=["reaction_time", "density"],
+        groupby=["condition", "condition_num"],
+        extent=[round(x_min - x_pad, -1), round(x_max + x_pad, -1)],
     )
-    .mark_area(orient="vertical", opacity=0.7)
+    .transform_calculate(violin_pos="datum.condition_num + 0.04 + datum.density * 105")
+    .mark_area(orient="vertical", opacity=0.55, interpolate="monotone")
     .encode(
-        x=alt.X("reaction_time:Q"),
-        y=alt.Y("condition_num:Q", axis=None).scale(domain=[-0.6, 2.6]),
+        x=alt.X("reaction_time:Q", title="Reaction Time (ms)", scale=x_scale, axis=x_axis),
+        y=alt.Y("condition_num:Q", axis=None, scale=alt.Scale(domain=y_domain)),
         y2="violin_pos:Q",
         color=alt.Color(
             "condition:N",
-            scale=alt.Scale(domain=condition_order, range=["#306998", "#FFD43B", "#4CAF50"]),
+            scale=alt.Scale(domain=condition_order, range=colors),
             legend=alt.Legend(
                 title="Condition",
                 titleFontSize=20,
+                titleFontWeight="bold",
                 labelFontSize=18,
-                orient="right",
+                orient="none",
+                legendX=1350,
+                legendY=50,
                 fillColor="white",
                 strokeColor="#cccccc",
-                padding=12,
-                cornerRadius=4,
+                padding=14,
+                cornerRadius=6,
+                symbolSize=200,
+                direction="vertical",
             ),
         ),
         tooltip=[
@@ -75,66 +115,151 @@
     )
 )
 
-# Box plot - HORIZONTAL orientation (values on x, categories on y)
-boxplot = (
-    alt.Chart(data)
-    .transform_calculate(box_pos="datum.condition_num + 0.02")
-    .mark_boxplot(
-        size=30,
-        orient="horizontal",
-        median={"color": "white", "strokeWidth": 3},
-        box={"strokeWidth": 2},
-        outliers={"opacity": 0},  # Hide outliers, shown as jittered points
+# Box plot — WHITE fill with dark outline to distinguish from cloud
+box_iqr = (
+    alt.Chart(box_df)
+    .mark_bar(height=18, stroke="#333333", strokeWidth=2, cornerRadius=2, fill="white", fillOpacity=0.85)
+    .encode(
+        x=alt.X("q1:Q", scale=x_scale),
+        x2="q3:Q",
+        y=alt.Y("condition_num:Q", axis=None, scale=alt.Scale(domain=y_domain)),
     )
+)
+
+# Median line — contrasting red
+box_median = (
+    alt.Chart(box_df)
+    .mark_tick(thickness=3.5, color="#E8413C", orient="vertical")
+    .encode(x=alt.X("median:Q", scale=x_scale), y=alt.Y("condition_num:Q", axis=None, scale=alt.Scale(domain=y_domain)))
+)
+
+# Whisker lines
+box_whiskers = (
+    alt.Chart(box_df)
+    .mark_rule(strokeWidth=1.5, color="#555555")
     .encode(
-        x=alt.X("reaction_time:Q", title="Reaction Time (ms)", scale=alt.Scale(domain=[200, 600])),
-        y=alt.Y("box_pos:Q", axis=None),
-        color=alt.Color(
-            "condition:N", scale=alt.Scale(domain=condition_order, range=["#306998", "#FFD43B", "#4CAF50"])
-        ),
+        x=alt.X("lower_w:Q", scale=x_scale),
+        x2="upper_w:Q",
+        y=alt.Y("condition_num:Q", axis=None, scale=alt.Scale(domain=y_domain)),
     )
 )
 
-# Jittered strip plot (rain) - positioned clearly BELOW the center
+# Whisker caps
+whisker_cap_data = pd.concat(
+    [
+        box_df[["condition_num", "lower_w"]].rename(columns={"lower_w": "x"}),
+        box_df[["condition_num", "upper_w"]].rename(columns={"upper_w": "x"}),
+    ]
+)
+whisker_cap_data["y1"] = whisker_cap_data["condition_num"] - 0.06
+whisker_cap_data["y2"] = whisker_cap_data["condition_num"] + 0.06
+whisker_caps = (
+    alt.Chart(whisker_cap_data)
+    .mark_rule(strokeWidth=1.5, color="#555555")
+    .encode(x=alt.X("x:Q", scale=x_scale), y=alt.Y("y1:Q", axis=None, scale=alt.Scale(domain=y_domain)), y2="y2:Q")
+)
+
+# Jittered strip — rain BELOW baseline
 strip = (
     alt.Chart(data)
-    .mark_circle(size=40, opacity=0.6)
+    .mark_circle(size=45, opacity=0.5, stroke="#444444", strokeWidth=0.4)
     .encode(
-        x=alt.X("reaction_time:Q"),
+        x=alt.X("reaction_time:Q", scale=x_scale),
         y=alt.Y("jitter_pos:Q", axis=None),
-        color=alt.Color(
-            "condition:N", scale=alt.Scale(domain=condition_order, range=["#306998", "#FFD43B", "#4CAF50"])
-        ),
+        color=alt.Color("condition:N", scale=alt.Scale(domain=condition_order, range=colors)),
         tooltip=[
             alt.Tooltip("condition:N", title="Condition"),
             alt.Tooltip("reaction_time:Q", title="Reaction Time (ms)", format=".1f"),
         ],
     )
 )
 
-# Main chart layer with raincloud elements
-main_chart = (
-    alt.layer(violin, boxplot, strip).properties(width=1600, height=850).interactive()  # Enable zoom and pan
+# Annotation: highlight Treatment B bimodality
+annotation_data = pd.DataFrame(
+    [{"x": 340, "y": 3.0 + 0.65, "text": "Peak 1"}, {"x": 460, "y": 3.0 + 0.50, "text": "Peak 2"}]
+)
+bimodal_labels = (
+    alt.Chart(annotation_data)
+    .mark_text(fontSize=16, fontStyle="italic", color="#444444", fontWeight="bold")
+    .encode(x=alt.X("x:Q"), y=alt.Y("y:Q", axis=None), text="text:N")
+)
+
+arrow_data = pd.DataFrame([{"x": 355, "y": 3.0 + 0.58, "x2": 445, "y2": 3.0 + 0.53}])
+bimodal_arrow = (
+    alt.Chart(arrow_data)
+    .mark_rule(strokeDash=[4, 3], color="#777777", strokeWidth=1.5)
+    .encode(x=alt.X("x:Q"), y=alt.Y("y:Q", axis=None), x2="x2:Q", y2="y2:Q")
 )
 
-# Y-axis labels as a separate chart on the left
-y_axis_data = pd.DataFrame({"condition": condition_order, "y_pos": [0, 1, 2]})
+note_data = pd.DataFrame([{"x": 400, "y": 3.0 + 0.78, "text": "Bimodal distribution"}])
+bimodal_note = (
+    alt.Chart(note_data)
+    .mark_text(fontSize=15, color="#555555", fontStyle="italic")
+    .encode(x=alt.X("x:Q"), y=alt.Y("y:Q", axis=None), text="text:N")
+)
+
+# Median value annotations on box plots
+median_labels = (
+    alt.Chart(box_df)
+    .transform_calculate(label_y="datum.condition_num + 0.18")
+    .mark_text(fontSize=14, color="#E8413C", fontWeight="bold", dy=-14)
+    .encode(
+        x=alt.X("median:Q", scale=x_scale),
+        y=alt.Y("condition_num:Q", axis=None, scale=alt.Scale(domain=y_domain)),
+        text=alt.Text("median:Q", format=".0f"),
+    )
+)
 
-y_axis_labels = (
-    alt.Chart(y_axis_data)
-    .mark_text(fontSize=20, fontWeight="bold", align="right", baseline="middle")
-    .encode(y=alt.Y("y_pos:Q", scale=alt.Scale(domain=[-0.6, 2.6]), axis=None), text="condition:N")
-    .properties(width=120, height=850)
+# Y-axis tick labels
+y_label_data = pd.DataFrame({"condition": condition_order, "y_pos": [0, 1.5, 3.0]})
+y_labels = (
+    alt.Chart(y_label_data)
+    .transform_calculate(x=str(round(x_min - x_pad, -1)))
+    .mark_text(fontSize=20, fontWeight="bold", align="right", baseline="middle", dx=-25, clip=False, color="#333333")
+    .encode(x=alt.X("x:Q"), y=alt.Y("y_pos:Q", axis=None, scale=alt.Scale(domain=y_domain)), text="condition:N")
 )
 
-# Combine using horizontal concatenation
+# Compose all layers
 chart = (
-    alt.hconcat(y_axis_labels, main_chart, spacing=5)
-    .properties(title=alt.Title("raincloud-basic · altair · pyplots.ai", fontSize=28, anchor="middle"))
-    .configure_axis(labelFontSize=18, titleFontSize=22, gridOpacity=0.3)
+    alt.layer(
+        violin,
+        box_whiskers,
+        whisker_caps,
+        box_iqr,
+        box_median,
+        median_labels,
+        strip,
+        bimodal_labels,
+        bimodal_arrow,
+        bimodal_note,
+        y_labels,
+    )
+    .resolve_scale(y="shared", x="shared")
+    .properties(
+        width=1600,
+        height=900,
+        title=alt.Title(
+            "raincloud-basic · altair · pyplots.ai",
+            fontSize=28,
+            anchor="middle",
+            offset=20,
+            color="#333333",
+            fontWeight="bold",
+        ),
+    )
+    .configure(padding={"left": 140, "right": 20, "top": 10, "bottom": 40})
+    .configure_axis(
+        labelFontSize=18,
+        titleFontSize=22,
+        gridColor="#d0d0d0",
+        gridOpacity=0.25,
+        domainColor="#999999",
+        tickColor="#999999",
+    )
     .configure_view(strokeWidth=0)
+    .interactive()
 )
 
-# Save outputs
+# Save
 chart.save("plot.png", scale_factor=3.0)
 chart.save("plot.html")