spec: add scatter-lag specification (#5264)

## New Specification: `scatter-lag`

Related to #5251

---

### specification.md

# scatter-lag: Lag Plot for Time Series Autocorrelation Diagnosis

## Description

A lag plot is a scatter plot of a time series against a lagged version
of itself, plotting y(t) on the x-axis versus y(t+k) on the y-axis for a
given lag order k. If the data is purely random, points scatter
uniformly with no visible structure; if autocorrelation is present,
distinctive patterns emerge — linear clusters for autoregressive
processes, elliptical shapes for seasonal data. This provides a quick
visual diagnostic for time series dependence, complementing numerical
tools like ACF/PACF.

## Applications

- Checking for autocorrelation before applying regression models that
assume independent residuals
- Diagnosing stationarity and serial dependence in financial return
series
- Identifying seasonal or cyclical patterns in sensor and environmental
monitoring data
- Validating residual independence after fitting ARIMA or other time
series models

## Data

- `value` (float) — time series observations in chronological order
- `lag` (int) — lag order k, default 1 (plot y(t) vs y(t+k))
- Size: 100–5000 observations
- Example: daily stock returns, hourly temperature readings, or
synthetic AR(1) process data

## Notes

- Default lag = 1, but the implementation should support configurable
lag values (e.g., 1, 7, 12)
- Include a diagonal reference line (y = x) to help assess whether the
series is uncorrelated
- Optionally color points by their time index to reveal temporal
structure within the scatter
- Strong linear pattern along the diagonal indicates high positive
autocorrelation at the given lag; perpendicular spread indicates
negative autocorrelation
- Consider adding a correlation coefficient annotation (r value) to
quantify the visual pattern

---

**Next:** Add `approved` label to the issue to merge this PR.

---
:robot: *[spec-create
workflow](https://github.com/MarkusNeusinger/pyplots/actions/runs/24290847773)*

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

Author: github-actions[bot]

plots/scatter-lag/specification.md

@@ -0,0 +1,27 @@
+# scatter-lag: Lag Plot for Time Series Autocorrelation Diagnosis
+
+## Description
+
+A lag plot is a scatter plot of a time series against a lagged version of itself, plotting y(t) on the x-axis versus y(t+k) on the y-axis for a given lag order k. If the data is purely random, points scatter uniformly with no visible structure; if autocorrelation is present, distinctive patterns emerge — linear clusters for autoregressive processes, elliptical shapes for seasonal data. This provides a quick visual diagnostic for time series dependence, complementing numerical tools like ACF/PACF.
+
+## Applications
+
+- Checking for autocorrelation before applying regression models that assume independent residuals
+- Diagnosing stationarity and serial dependence in financial return series
+- Identifying seasonal or cyclical patterns in sensor and environmental monitoring data
+- Validating residual independence after fitting ARIMA or other time series models
+
+## Data
+
+- `value` (float) — time series observations in chronological order
+- `lag` (int) — lag order k, default 1 (plot y(t) vs y(t+k))
+- Size: 100–5000 observations
+- Example: daily stock returns, hourly temperature readings, or synthetic AR(1) process data
+
+## Notes
+
+- Default lag = 1, but the implementation should support configurable lag values (e.g., 1, 7, 12)
+- Include a diagonal reference line (y = x) to help assess whether the series is uncorrelated
+- Optionally color points by their time index to reveal temporal structure within the scatter
+- Strong linear pattern along the diagonal indicates high positive autocorrelation at the given lag; perpendicular spread indicates negative autocorrelation
+- Consider adding a correlation coefficient annotation (r value) to quantify the visual pattern

plots/scatter-lag/specification.yaml

@@ -0,0 +1,29 @@
+# Specification-level metadata for scatter-lag
+# Auto-synced to PostgreSQL on push to main
+
+spec_id: scatter-lag
+title: Lag Plot for Time Series Autocorrelation Diagnosis
+
+# Specification tracking
+created: "2026-04-11T20:23:52Z"
+updated: null
+issue: 5251
+suggested: MarkusNeusinger
+
+# Classification tags (applies to all library implementations)
+# See docs/reference/tagging-system.md for detailed guidelines
+tags:
+  plot_type:
+    - scatter
+  data_type:
+    - timeseries
+    - numeric
+    - continuous
+  domain:
+    - statistics
+    - finance
+    - general
+  features:
+    - correlation
+    - temporal
+    - 2d