feat(altair): implement logistic-regression (#3564)

## Implementation: `logistic-regression` - altair

Implements the **altair** version of `logistic-regression`.

**File:** `plots/logistic-regression/implementations/altair.py`

**Parent Issue:** #3550

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

---------

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

Author: github-actions[bot]

plots/logistic-regression/implementations/altair.py

@@ -0,0 +1,123 @@
+""" pyplots.ai
+logistic-regression: Logistic Regression Curve Plot
+Library: altair 6.0.0 | Python 3.13.11
+Quality: 91/100 | Created: 2026-01-09
+"""
+
+import altair as alt
+import numpy as np
+import pandas as pd
+
+
+# Data - Study hours vs exam pass/fail
+np.random.seed(42)
+n_samples = 150
+
+# Generate study hours with different distributions for pass/fail
+hours_fail = np.random.normal(3, 1.5, 60)
+hours_pass = np.random.normal(7, 1.5, 90)
+hours = np.concatenate([hours_fail, hours_pass])
+hours = np.clip(hours, 0.5, 10)
+
+outcome = np.concatenate([np.zeros(60), np.ones(90)])
+
+# Fit logistic regression using gradient descent
+X_b = np.column_stack([np.ones(n_samples), hours])
+w = np.zeros(2)
+
+for _ in range(1000):
+    z = X_b @ w
+    predictions = 1 / (1 + np.exp(-z))
+    gradient = X_b.T @ (predictions - outcome) / n_samples
+    w -= 0.1 * gradient
+
+b0, b1 = w[0], w[1]
+
+# Generate smooth curve points
+x_curve = np.linspace(0, 10.5, 200)
+y_proba = 1 / (1 + np.exp(-(b0 + b1 * x_curve)))
+
+# Calculate confidence intervals
+se = np.sqrt(y_proba * (1 - y_proba) / n_samples) * 2.5
+ci_lower = np.clip(y_proba - 1.96 * se, 0, 1)
+ci_upper = np.clip(y_proba + 1.96 * se, 0, 1)
+
+# Create curve DataFrame
+curve_df = pd.DataFrame({"Study Hours": x_curve, "Probability": y_proba, "CI Lower": ci_lower, "CI Upper": ci_upper})
+
+# Add jitter to data points for visibility
+jitter = np.random.uniform(-0.03, 0.03, len(outcome))
+y_jittered = outcome + jitter
+
+# Create data points DataFrame
+points_df = pd.DataFrame(
+    {
+        "Study Hours": hours,
+        "Outcome": outcome,
+        "Outcome Jittered": y_jittered,
+        "Class": ["Fail" if o == 0 else "Pass" for o in outcome],
+    }
+)
+
+# Decision threshold line
+threshold_df = pd.DataFrame({"Study Hours": [0, 10.5], "Probability": [0.5, 0.5]})
+
+# Create the confidence interval band
+ci_band = (
+    alt.Chart(curve_df)
+    .mark_area(opacity=0.25, color="#306998")
+    .encode(x=alt.X("Study Hours:Q"), y=alt.Y("CI Lower:Q"), y2=alt.Y2("CI Upper:Q"))
+)
+
+# Create the logistic curve
+curve = (
+    alt.Chart(curve_df)
+    .mark_line(strokeWidth=4, color="#306998")
+    .encode(x=alt.X("Study Hours:Q"), y=alt.Y("Probability:Q"))
+)
+
+# Create the data points
+points = (
+    alt.Chart(points_df)
+    .mark_circle(size=200, opacity=0.6, strokeWidth=1, stroke="white")
+    .encode(
+        x=alt.X("Study Hours:Q", title="Study Hours", scale=alt.Scale(domain=[0, 10.5])),
+        y=alt.Y("Outcome Jittered:Q", title="Probability / Outcome", scale=alt.Scale(domain=[-0.05, 1.05])),
+        color=alt.Color(
+            "Class:N",
+            scale=alt.Scale(domain=["Fail", "Pass"], range=["#306998", "#FFD43B"]),
+            legend=alt.Legend(title="Exam Result", titleFontSize=20, labelFontSize=18, symbolSize=300),
+        ),
+        tooltip=["Study Hours", "Class"],
+    )
+)
+
+# Decision threshold line
+threshold = (
+    alt.Chart(threshold_df)
+    .mark_line(strokeDash=[12, 8], strokeWidth=3, color="#888888")
+    .encode(x=alt.X("Study Hours:Q"), y=alt.Y("Probability:Q"))
+)
+
+# Threshold label
+threshold_label = (
+    alt.Chart(pd.DataFrame({"x": [9.5], "y": [0.54], "text": ["Decision Threshold (p=0.5)"]}))
+    .mark_text(fontSize=16, color="#666666", align="right")
+    .encode(x="x:Q", y="y:Q", text="text:N")
+)
+
+# Combine all layers
+chart = (
+    alt.layer(ci_band, curve, threshold, threshold_label, points)
+    .properties(
+        width=1600,
+        height=900,
+        title=alt.Title("logistic-regression · altair · pyplots.ai", fontSize=28, anchor="middle"),
+    )
+    .configure_axis(labelFontSize=18, titleFontSize=22, gridOpacity=0.3)
+    .configure_view(strokeWidth=0)
+)
+
+# Save outputs
+chart.save("plot.png", scale_factor=3.0)
+chart.save("plot.html")

plots/logistic-regression/metadata/altair.yaml

@@ -0,0 +1,216 @@
+library: altair
+specification_id: logistic-regression
+created: '2026-01-09T21:55:53Z'
+updated: '2026-01-09T22:01:12Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 20866597347
+issue: 3550
+python_version: 3.13.11
+library_version: 6.0.0
+preview_url: https://storage.googleapis.com/pyplots-images/plots/logistic-regression/altair/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/logistic-regression/altair/plot_thumb.png
+preview_html: https://storage.googleapis.com/pyplots-images/plots/logistic-regression/altair/plot.html
+quality_score: 91
+review:
+  strengths:
+  - Excellent implementation of the sigmoid curve with manual gradient descent fitting
+  - Well-designed confidence interval band using mark_area
+  - Appropriate jittering of data points for visibility
+  - Clean Altair layer composition combining multiple visual elements
+  - 'Good color choice (Python blue #306998 and yellow #FFD43B)'
+  - Proper title format following spec requirements
+  - Tooltips included for interactivity
+  weaknesses:
+  - Axis label could include units (e.g., Study Hours (hrs))
+  - Some data points at boundary regions show unexpected class membership (pass at
+    low hours, fail at high hours) which may confuse viewers
+  - Grid opacity could be slightly more subtle (0.2 instead of 0.3)
+  image_description: 'The plot displays a logistic regression visualization with the
+    characteristic S-shaped sigmoid curve. The x-axis shows "Study Hours" ranging
+    from 0 to 10.8, and the y-axis shows "Probability / Outcome" ranging from -0.10
+    to 1.10. Data points are colored by class: blue circles for "Fail" (clustered
+    near the bottom around y=0) and yellow circles for "Pass" (clustered near the
+    top around y=1). The blue sigmoid curve shows the fitted logistic regression probability,
+    surrounded by a light blue semi-transparent confidence interval band. A gray dashed
+    horizontal line at p=0.5 indicates the decision threshold, with a "Decision Threshold
+    (p=0.5)" label. The legend in the upper right shows "Exam Result" with Fail (blue)
+    and Pass (yellow). The title reads "logistic-regression · altair · pyplots.ai".'
+  criteria_checklist:
+    visual_quality:
+      score: 36
+      max: 40
+      items:
+      - id: VQ-01
+        name: Text Legibility
+        score: 10
+        max: 10
+        passed: true
+        comment: Title, axis labels, and tick labels are all clearly readable at full
+          size with appropriate font sizes
+      - id: VQ-02
+        name: No Overlap
+        score: 8
+        max: 8
+        passed: true
+        comment: No overlapping text elements, data points have appropriate jitter
+      - id: VQ-03
+        name: Element Visibility
+        score: 7
+        max: 8
+        passed: true
+        comment: Markers well-sized (size=200) with good opacity (0.6), though some
+          overlap in dense regions
+      - id: VQ-04
+        name: Color Accessibility
+        score: 5
+        max: 5
+        passed: true
+        comment: Blue and yellow are colorblind-safe and provide excellent contrast
+      - id: VQ-05
+        name: Layout Balance
+        score: 4
+        max: 5
+        passed: true
+        comment: Good use of canvas space, legend well positioned but slight extra
+          space on right
+      - id: VQ-06
+        name: Axis Labels
+        score: 1
+        max: 2
+        passed: true
+        comment: Descriptive labels but no units
+      - id: VQ-07
+        name: Grid & Legend
+        score: 1
+        max: 2
+        passed: true
+        comment: Grid subtle (gridOpacity=0.3), legend well placed but slightly large
+    spec_compliance:
+      score: 24
+      max: 25
+      items:
+      - id: SC-01
+        name: Plot Type
+        score: 8
+        max: 8
+        passed: true
+        comment: Correct logistic regression visualization with sigmoid curve
+      - id: SC-02
+        name: Data Mapping
+        score: 5
+        max: 5
+        passed: true
+        comment: X correctly shows predictor, Y shows probability/outcome
+      - id: SC-03
+        name: Required Features
+        score: 5
+        max: 5
+        passed: true
+        comment: 'All spec features present: sigmoid curve, confidence interval, jittered
+          points, decision threshold line, class coloring'
+      - id: SC-04
+        name: Data Range
+        score: 3
+        max: 3
+        passed: true
+        comment: All data visible with appropriate scale
+      - id: SC-05
+        name: Legend Accuracy
+        score: 2
+        max: 2
+        passed: true
+        comment: Legend correctly shows Exam Result with Fail/Pass
+      - id: SC-06
+        name: Title Format
+        score: 1
+        max: 2
+        passed: true
+        comment: Uses correct format but middot character may render differently across
+          systems
+    data_quality:
+      score: 18
+      max: 20
+      items:
+      - id: DQ-01
+        name: Feature Coverage
+        score: 7
+        max: 8
+        passed: true
+        comment: 'Shows sigmoid curve, both classes, confidence interval, threshold;
+          minor: could show edge cases more'
+      - id: DQ-02
+        name: Realistic Context
+        score: 7
+        max: 7
+        passed: true
+        comment: Exam pass/fail vs study hours is an excellent, neutral, realistic
+          scenario
+      - id: DQ-03
+        name: Appropriate Scale
+        score: 4
+        max: 5
+        passed: true
+        comment: 'Study hours 0-10 is reasonable; 150 samples good; minor: some pass
+          outcomes at low hours'
+    code_quality:
+      score: 10
+      max: 10
+      items:
+      - id: CQ-01
+        name: KISS Structure
+        score: 3
+        max: 3
+        passed: true
+        comment: 'Clean linear flow: imports, data, model, plot, save'
+      - id: CQ-02
+        name: Reproducibility
+        score: 3
+        max: 3
+        passed: true
+        comment: Uses np.random.seed(42)
+      - id: CQ-03
+        name: Clean Imports
+        score: 2
+        max: 2
+        passed: true
+        comment: Only necessary imports (altair, numpy, pandas)
+      - id: CQ-04
+        name: No Deprecated API
+        score: 1
+        max: 1
+        passed: true
+        comment: Uses current Altair API
+      - id: CQ-05
+        name: Output Correct
+        score: 1
+        max: 1
+        passed: true
+        comment: Saves as plot.png and plot.html
+    library_features:
+      score: 3
+      max: 5
+      items:
+      - id: LF-01
+        name: Distinctive Features
+        score: 3
+        max: 5
+        passed: true
+        comment: Uses Altair layer composition, tooltips, and declarative encoding
+          well, but could use more interactive features
+  verdict: APPROVED
+impl_tags:
+  dependencies: []
+  techniques:
+  - layer-composition
+  - annotations
+  - hover-tooltips
+  - html-export
+  patterns:
+  - data-generation
+  - iteration-over-groups
+  dataprep:
+  - regression
+  styling:
+  - alpha-blending
+  - grid-styling
+  - edge-highlighting