[v1 API] 13 — Bivariate aggregations: correlation with field2

[tomanizer]

Part of #403. Depends on #413.

What

Add Pearson correlation as a bivariate aggregation. This requires a minor extension to the measure spec to support a second field.

Model change

Add optional field2 to MeasureSpec:

class MeasureSpec(BaseModel):
    field: str
    field2: str | None = None   # only valid for bivariate aggregations
    aggregation: AggregationFunction = "sum"
    alias: str | None = None
    sort_by: str | None = None
    params: dict[str, Any] | None = None

New aggregation function

correlation

Pearson correlation coefficient between two numeric fields.

{
  "field":        "stock_return",
  "field2":       "index_return",
  "aggregation":  "correlation",
  "alias":        "beta_proxy"
}

SQL: CORR("stock_return", "index_return") — DuckDB built-in.

Returns a double in [-1.0, 1.0]. Returns null when there is insufficient data (fewer than 2 rows in the group).

Default alias when none specified: {field}__corr__{field2}.

Validation

• correlation without field2 → 422 VALIDATION_ERROR with message "correlation requires field2"
• field2 present with any aggregation other than correlation → 422 VALIDATION_ERROR with message "field2 is only valid for correlation"
• Both field and field2 must exist in the dataset schema and be numeric → 422 FIELD_NOT_FOUND or 422 AGGREGATION_NOT_SUPPORTED as appropriate
• field and field2 must not be the same field

Acceptance criteria

• correlation with two numeric fields returns correct CORR value
• correlation without field2 returns 422
• field2 with non-correlation aggregation returns 422
• field or field2 not in schema returns 422 FIELD_NOT_FOUND
• Non-numeric field returns 422 AGGREGATION_NOT_SUPPORTED
• Returns null (not error) when group has < 2 rows
• Tests cover: valid correlation, missing field2, wrong type, single-row groups