feat(altair): implement subplot-grid-custom (#2883)

## Implementation: `subplot-grid-custom` - altair

Implements the **altair** version of `subplot-grid-custom`.

**File:** `plots/subplot-grid-custom/implementations/altair.py`

**Parent Issue:** #2856

---
:robot: *[impl-generate
workflow](https://github.com/MarkusNeusinger/pyplots/actions/runs/20608471998)*

---------

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: github-actions[bot]

plots/subplot-grid-custom/implementations/altair.py

@@ -0,0 +1,126 @@
+""" pyplots.ai
+subplot-grid-custom: Custom Subplot Grid Layout
+Library: altair 6.0.0 | Python 3.13.11
+Quality: 91/100 | Created: 2025-12-30
+"""
+
+import altair as alt
+import numpy as np
+import pandas as pd
+
+
+# Data
+np.random.seed(42)
+
+# Time series data for main chart (spanning 2 columns)
+dates = pd.date_range("2024-01-01", periods=120, freq="D")
+base_price = 100 + np.cumsum(np.random.randn(120) * 2)
+price_df = pd.DataFrame({"date": dates, "price": base_price})
+
+# Volume data for bar chart
+volume_df = pd.DataFrame({"date": dates, "volume": np.random.randint(500, 2000, 120)})
+
+# Daily returns for histogram
+returns = np.diff(base_price) / base_price[:-1] * 100
+returns_df = pd.DataFrame({"returns": returns})
+
+# Correlation scatter data
+scatter_df = pd.DataFrame({"feature_a": np.random.randn(80) * 15 + 50, "feature_b": np.random.randn(80) * 10 + 40})
+scatter_df["feature_b"] = scatter_df["feature_a"] * 0.6 + scatter_df["feature_b"]
+
+# Category breakdown for pie-like (arc) chart
+category_df = pd.DataFrame(
+    {"category": ["Product A", "Product B", "Product C", "Product D"], "value": [35, 28, 22, 15]}
+)
+
+# Main time series chart (spans full width - equivalent to colspan=2)
+main_chart = (
+    alt.Chart(price_df)
+    .mark_line(strokeWidth=4, color="#306998")
+    .encode(
+        x=alt.X("date:T", title="Date", axis=alt.Axis(labelFontSize=16, titleFontSize=18)),
+        y=alt.Y("price:Q", title="Price ($)", axis=alt.Axis(labelFontSize=16, titleFontSize=18)),
+    )
+    .properties(width=900, height=350, title=alt.Title("Daily Price Trend (Main View)", fontSize=22))
+)
+
+# Volume bar chart
+volume_chart = (
+    alt.Chart(volume_df)
+    .mark_bar(color="#FFD43B", opacity=0.85)
+    .encode(
+        x=alt.X("date:T", title="Date", axis=alt.Axis(labelFontSize=14, titleFontSize=16)),
+        y=alt.Y("volume:Q", title="Volume", axis=alt.Axis(labelFontSize=14, titleFontSize=16)),
+    )
+    .properties(width=440, height=200, title=alt.Title("Trading Volume", fontSize=18))
+)
+
+# Returns histogram
+histogram_chart = (
+    alt.Chart(returns_df)
+    .mark_bar(color="#306998", opacity=0.75)
+    .encode(
+        x=alt.X(
+            "returns:Q",
+            bin=alt.Bin(maxbins=20),
+            title="Daily Return (%)",
+            axis=alt.Axis(labelFontSize=14, titleFontSize=16),
+        ),
+        y=alt.Y("count():Q", title="Frequency", axis=alt.Axis(labelFontSize=14, titleFontSize=16)),
+    )
+    .properties(width=440, height=200, title=alt.Title("Return Distribution", fontSize=18))
+)
+
+# Scatter plot for correlation
+scatter_chart = (
+    alt.Chart(scatter_df)
+    .mark_circle(size=120, color="#306998", opacity=0.65)
+    .encode(
+        x=alt.X("feature_a:Q", title="Feature A", axis=alt.Axis(labelFontSize=14, titleFontSize=16)),
+        y=alt.Y("feature_b:Q", title="Feature B", axis=alt.Axis(labelFontSize=14, titleFontSize=16)),
+    )
+    .properties(width=440, height=200, title=alt.Title("Feature Correlation", fontSize=18))
+)
+
+# Category breakdown using arc chart (donut)
+arc_chart = (
+    alt.Chart(category_df)
+    .mark_arc(innerRadius=50, outerRadius=90)
+    .encode(
+        theta=alt.Theta("value:Q"),
+        color=alt.Color(
+            "category:N",
+            scale=alt.Scale(
+                domain=["Product A", "Product B", "Product C", "Product D"],
+                range=["#306998", "#FFD43B", "#4B8BBE", "#E6B800"],
+            ),
+            legend=alt.Legend(labelFontSize=14, titleFontSize=16, orient="right", title="Category"),
+        ),
+    )
+    .properties(width=440, height=200, title=alt.Title("Category Breakdown", fontSize=18))
+)
+
+# Create custom grid layout using vconcat and hconcat
+# Row 1: Main chart spanning full width (equivalent to colspan=2)
+# Row 2: Volume and Histogram side by side
+# Row 3: Scatter and Arc chart side by side
+
+top_row = main_chart
+
+middle_row = alt.hconcat(volume_chart, histogram_chart).resolve_scale(x="independent", y="independent")
+
+bottom_row = alt.hconcat(scatter_chart, arc_chart).resolve_scale(x="independent", y="independent")
+
+# Combine all rows vertically with main title
+combined = (
+    alt.vconcat(top_row, middle_row, bottom_row)
+    .resolve_scale(x="independent", y="independent")
+    .configure(background="white")
+    .configure_title(anchor="start", fontSize=24, offset=10)
+    .configure_concat(spacing=25)
+    .properties(title=alt.Title("subplot-grid-custom · altair · pyplots.ai", fontSize=30, anchor="middle", offset=15))
+)
+
+# Save outputs
+combined.save("plot.png", scale_factor=3.0)
+combined.save("plot.html")

plots/subplot-grid-custom/metadata/altair.yaml

@@ -0,0 +1,28 @@
+library: altair
+specification_id: subplot-grid-custom
+created: '2025-12-30T23:54:59Z'
+updated: '2025-12-31T00:01:20Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 20608471998
+issue: 2856
+python_version: 3.13.11
+library_version: 6.0.0
+preview_url: https://storage.googleapis.com/pyplots-images/plots/subplot-grid-custom/altair/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/subplot-grid-custom/altair/plot_thumb.png
+preview_html: https://storage.googleapis.com/pyplots-images/plots/subplot-grid-custom/altair/plot.html
+quality_score: 91
+review:
+  strengths:
+  - Excellent implementation of dashboard-style grid using Altair's native vconcat/hconcat
+    composition
+  - Strong visual hierarchy with main chart appropriately larger than detail panels
+  - Good use of consistent color scheme (Python blue/gold theme)
+  - Comprehensive financial dashboard scenario with meaningful interconnected data
+  - Clean declarative code structure showcasing Altair's strengths
+  weaknesses:
+  - Legend for category breakdown appears isolated from the donut chart (top-right
+    instead of near the chart)
+  - Could demonstrate rowspan capability (e.g., a tall sidebar chart) in addition
+    to colspan
+  - Tick labels on x-axis of main chart are dense and could benefit from rotation
+    or fewer ticks