gomd 2.1.0__py3-none-any.whl

gomd/stats.py

@@ -0,0 +1,1086 @@
+"""
+gomd.stats — Time-Series Econometrics, Non-Parametric Trend Detection,
+Regime-Shift Analysis, Extreme Value Theory (GEV/Gumbel), and Panel Estimators
+===============================================================================
+Implements self-contained statistical & econometric algorithms:
+  1. Mann-Kendall Monotonic Trend Test & Theil-Sen Robust Slope Estimator
+  2. Pettitt (1979) Non-Parametric Regime-Shift / Change-Point Detection
+  3. Gumbel / Extreme Value Return Level Estimator (10, 25, 50, 100-yr periods)
+  4. Engle-Granger Two-Step Cointegration & Error Correction Mechanism (ECM)
+  5. Within-Transformation Fixed-Effects (FE) Panel Regression Estimator
+"""
+
+from __future__ import annotations
+
+import math
+import statistics
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+
+def _normal_cdf(z: float) -> float:
+    return 0.5 * (1.0 + math.erf(z / math.sqrt(2.0)))
+
+
+def mann_kendall_sen(
+    y: Sequence[float],
+    t: Optional[Sequence[float]] = None,
+) -> Dict[str, Any]:
+    """
+    Perform the non-parametric Mann-Kendall monotonic trend test (Mann, 1945;
+    Kendall, 1975) with tie-group variance correction and compute the Theil-Sen
+    robust slope estimator (Sen, 1968).
+
+    Parameters
+    ----------
+    y : Sequence[float]
+        Time-series observations.
+    t : Sequence[float], optional
+        Time coordinates (e.g., years). Defaults to `0, 1, ..., n-1`.
+    """
+    vals = [float(v) for v in y if v is not None and not math.isnan(float(v))]
+    n = len(vals)
+    if n < 3:
+        return {"error": "At least 3 observations are required for Mann-Kendall test.", "n": n}
+
+    times = [float(x) for x in t] if (t is not None and len(t) == n) else [float(i) for i in range(n)]
+
+    s_stat = 0
+    slopes: List[float] = []
+    for i in range(n - 1):
+        for j in range(i + 1, n):
+            diff = vals[j] - vals[i]
+            if diff > 0:
+                s_stat += 1
+            elif diff < 0:
+                s_stat -= 1
+            dt = times[j] - times[i]
+            if dt != 0:
+                slopes.append(diff / dt)
+
+    # Tie correction for Var(S)
+    counts: Dict[float, int] = {}
+    for v in vals:
+        counts[v] = counts.get(v, 0) + 1
+    tie_term = sum(m * (m - 1) * (2 * m + 5) for m in counts.values() if m > 1)
+    var_s = (n * (n - 1) * (2 * n + 5) - tie_term) / 18.0
+    std_s = math.sqrt(max(var_s, 1e-9))
+
+    if s_stat > 0:
+        z_mk = (s_stat - 1.0) / std_s
+    elif s_stat < 0:
+        z_mk = (s_stat + 1.0) / std_s
+    else:
+        z_mk = 0.0
+
+    p_val = 2.0 * (1.0 - _normal_cdf(abs(z_mk)))
+    tau = s_stat / (0.5 * n * (n - 1))
+    sen_slope = statistics.median(slopes) if slopes else 0.0
+    sen_intercept = statistics.median(vals) - sen_slope * statistics.median(times)
+
+    if p_val < 0.05:
+        direction = "increasing_significant" if z_mk > 0 else "decreasing_significant"
+    else:
+        direction = "no_significant_trend"
+
+    return {
+        "n": n,
+        "mann_kendall_s": s_stat,
+        "kendall_tau": round(tau, 4),
+        "z_stat": round(z_mk, 4),
+        "p_value": round(p_val, 6),
+        "theil_sen_slope": round(sen_slope, 6),
+        "sen_slope_per_unit": round(sen_slope, 6),
+        "theil_sen_intercept": round(sen_intercept, 4),
+        "trend_classification": direction,
+        "trend": direction,
+    }
+
+
+def pettitt_changepoint(
+    y: Sequence[float],
+    labels: Optional[Sequence[Any]] = None,
+) -> Dict[str, Any]:
+    """
+    Detect a single structural regime shift (change-point) in a time series using
+    the non-parametric Pettitt (1979, Applied Statistics) rank-based test.
+    """
+    vals = [float(v) for v in y if v is not None and not math.isnan(float(v))]
+    n = len(vals)
+    if n < 4:
+        return {"error": "At least 4 observations are required for Pettitt test.", "n": n}
+
+    idx_labels = list(labels) if (labels is not None and len(labels) == n) else list(range(n))
+
+    u_t: List[int] = []
+    u_curr = 0
+    for t_idx in range(n - 1):
+        # Incremental update of Mann-Whitney U_t,n
+        delta = 0
+        v_t = vals[t_idx]
+        for j in range(n):
+            if vals[j] > v_t:
+                delta += 1
+            elif vals[j] < v_t:
+                delta -= 1
+        u_curr += delta
+        u_t.append(abs(u_curr))
+
+    k_max = max(u_t)
+    tau_idx = u_t.index(k_max)
+    # Pettitt (1979) approximate two-sided significance probability
+    p_approx = min(2.0 * math.exp((-6.0 * (k_max ** 2)) / ((n ** 3) + (n ** 2))), 1.0)
+
+    pre_mean = sum(vals[: tau_idx + 1]) / (tau_idx + 1)
+    post_mean = sum(vals[tau_idx + 1 :]) / max(n - tau_idx - 1, 1)
+
+    return {
+        "n": n,
+        "changepoint_index": tau_idx,
+        "changepoint_label": idx_labels[tau_idx],
+        "pettitt_k_stat": k_max,
+        "p_value_approx": round(p_approx, 6),
+        "significant_at_5pct": p_approx < 0.05,
+        "pre_regime_mean": round(pre_mean, 4),
+        "post_regime_mean": round(post_mean, 4),
+        "mean_before": round(pre_mean, 4),
+        "mean_after": round(post_mean, 4),
+        "regime_shift_delta": round(post_mean - pre_mean, 4),
+    }
+
+
+def extreme_return_levels(
+    annual_maxima: Sequence[float],
+    return_periods: Sequence[int] = (10, 25, 50, 100),
+) -> Dict[str, Any]:
+    """
+    Fit an Extreme Value Type I (Gumbel) distribution via L-moments / Euler-Mascheroni
+    method of moments to annual maxima and compute extreme return levels z_T for
+    specified return periods T (in years).
+    """
+    vals = [float(v) for v in annual_maxima if v is not None and not math.isnan(float(v))]
+    n = len(vals)
+    if n < 5:
+        return {"error": "At least 5 annual maxima are required for Gumbel fitting.", "n": n}
+
+    mean_val = sum(vals) / n
+    var_val = sum((v - mean_val) ** 2 for v in vals) / (n - 1)
+    std_val = math.sqrt(max(var_val, 1e-9))
+
+    # Euler-Mascheroni constant gamma_E = 0.5772156649
+    gamma_e = 0.5772156649015329
+    beta_scale = (std_val * math.sqrt(6.0)) / math.pi
+    mu_loc = mean_val - gamma_e * beta_scale
+
+    levels: Dict[str, float] = {}
+    for rp in return_periods:
+        T = max(float(rp), 1.001)
+        y_t = -math.log(-math.log(1.0 - 1.0 / T))
+        z_t = mu_loc + beta_scale * y_t
+        levels[f"return_level_{int(rp)}yr"] = round(z_t, 4)
+
+    return {
+        "n_years": n,
+        "sample_mean": round(mean_val, 4),
+        "sample_std": round(std_val, 4),
+        "gumbel_location_mu": round(mu_loc, 4),
+        "gumbel_scale_beta": round(beta_scale, 4),
+        "return_levels": levels,
+    }
+
+
+def cointegration_eg_test(
+    x: Sequence[float],
+    y: Sequence[float],
+) -> Dict[str, Any]:
+    """
+    Execute the Engle & Granger (1987) two-step cointegration analysis and estimate
+    the Error Correction Mechanism (ECM) speed-of-adjustment coefficient:
+      Step 1 (Long-run equilibrium): y_t = alpha + beta * x_t + u_t
+      Step 2 (Residual ADF test):    Delta u_t = phi * u_{t-1} + eps_t
+      Step 3 (ECM):                  Delta y_t = c + gamma * u_{t-1} + delta * Delta x_t
+    """
+    n = min(len(x), len(y))
+    if n < 8:
+        return {"error": "At least 8 paired observations are required for Engle-Granger test.", "n": n}
+
+    xv = [float(x[i]) for i in range(n)]
+    yv = [float(y[i]) for i in range(n)]
+
+    mx = sum(xv) / n
+    my = sum(yv) / n
+    sxx = sum((xv[i] - mx) ** 2 for i in range(n))
+    sxy = sum((xv[i] - mx) * (yv[i] - my) for i in range(n))
+    beta = sxy / max(sxx, 1e-12)
+    alpha = my - beta * mx
+
+    # Cointegrating residuals u_t
+    u = [yv[i] - (alpha + beta * xv[i]) for i in range(n)]
+    du = [u[t] - u[t - 1] for t in range(1, n)]
+    u_lag = [u[t - 1] for t in range(1, n)]
+
+    denom_u = sum(val ** 2 for val in u_lag)
+    phi = sum(u_lag[i] * du[i] for i in range(n - 1)) / max(denom_u, 1e-12)
+    resid_adf = [du[i] - phi * u_lag[i] for i in range(n - 1)]
+    sigma2_adf = sum(r ** 2 for r in resid_adf) / max(n - 2, 1)
+    se_phi = math.sqrt(sigma2_adf / max(denom_u, 1e-12))
+    adf_t_stat = phi / max(se_phi, 1e-12)
+
+    # MacKinnon (1991) 5% critical value for 2-variable Engle-Granger cointegration ~ -3.34
+    cointegrated_5pct = adf_t_stat < -3.34
+
+    return {
+        "n": n,
+        "long_run_intercept_alpha": round(alpha, 4),
+        "long_run_slope_beta": round(beta, 6),
+        "adf_residual_rho": round(phi, 4),
+        "engle_granger_adf_t_stat": round(adf_t_stat, 4),
+        "critical_value_5pct": -3.34,
+        "cointegrated_at_5pct": cointegrated_5pct,
+    }
+
+
+def panel_fixed_effects(
+    records: Sequence[Dict[str, Any]],
+    entity_col: str,
+    y_col: str,
+    x_col: str,
+) -> Dict[str, Any]:
+    """
+    Estimate a Within-Transformation One-Way Fixed Effects (FE) panel regression:
+        (y_{it} - y_bar_i) = beta_FE * (x_{it} - x_bar_i) + (eps_{it} - eps_bar_i)
+
+    Controls for all time-invariant unobserved heterogeneity alpha_i across countries
+    or sea basins without requiring external econometrics libraries.
+    """
+    groups: Dict[str, List[Tuple[float, float]]] = {}
+    for row in records:
+        if entity_col in row and y_col in row and x_col in row:
+            try:
+                ent = str(row[entity_col])
+                yv = float(row[y_col])
+                xv = float(row[x_col])
+                if not (math.isnan(yv) or math.isnan(xv)):
+                    groups.setdefault(ent, []).append((xv, yv))
+            except (TypeError, ValueError):
+                continue
+
+    x_tilde: List[float] = []
+    y_tilde: List[float] = []
+    n_entities = 0
+    for ent, pairs in groups.items():
+        if len(pairs) < 2:
+            continue
+        n_entities += 1
+        mx = sum(p[0] for p in pairs) / len(pairs)
+        my = sum(p[1] for p in pairs) / len(pairs)
+        for xv, yv in pairs:
+            x_tilde.append(xv - mx)
+            y_tilde.append(yv - my)
+
+    n_obs = len(x_tilde)
+    if n_obs < 4 or n_entities < 1:
+        return {"error": "Insufficient panel observations after within-transformation.", "n_obs": n_obs}
+
+    sxx = sum(x ** 2 for x in x_tilde)
+    sxy = sum(x_tilde[i] * y_tilde[i] for i in range(n_obs))
+    syy = sum(y ** 2 for y in y_tilde)
+    beta_fe = sxy / max(sxx, 1e-12)
+
+    rss = sum((y_tilde[i] - beta_fe * x_tilde[i]) ** 2 for i in range(n_obs))
+    dof = max(n_obs - n_entities - 1, 1)
+    sigma2 = rss / dof
+    se_beta = math.sqrt(sigma2 / max(sxx, 1e-12))
+    t_stat = beta_fe / max(se_beta, 1e-12)
+    p_val = 2.0 * (1.0 - _normal_cdf(abs(t_stat)))
+    r2_within = max(1.0 - rss / max(syy, 1e-12), 0.0)
+
+    return {
+        "n_obs": n_obs,
+        "n_entities": n_entities,
+        "degrees_of_freedom": dof,
+        "beta_fe": round(beta_fe, 6),
+        "std_error": round(se_beta, 6),
+        "t_stat": round(t_stat, 4),
+        "p_value": round(p_val, 6),
+        "r_squared_within": round(r2_within, 4),
+    }
+
+
+def synthetic_did_ate(
+    treated_pre: Sequence[float],
+    treated_post: Sequence[float],
+    control_matrix_pre: Sequence[Sequence[float]],
+    control_matrix_post: Sequence[Sequence[float]],
+    ridge_zeta: float = 0.05,
+) -> Dict[str, Any]:
+    """
+    Estimate the Causal Average Treatment Effect on the Treated (ATE / ATT) of a Marine
+    or Climate Policy Intervention using Synthetic Difference-in-Differences (SDID).
+
+    Combines Abadie Synthetic Control unit weights (omega_i) and time weights (lambda_t)
+    with two-way fixed effects to achieve doubly-robust causal inference even when
+    parallel trends are imperfect.
+
+    Post-2020 Econometric Reference:
+      - Arkhangelsky, D., Athey, S., Hirshberg, D. A., Imbens, G. W., & Wager, S. (2021).
+        Synthetic Difference-in-Differences. American Economic Review, 111(12), 4088-4118.
+    """
+    t_pre = [float(v) for v in treated_pre]
+    t_post = [float(v) for v in treated_post]
+    c_pre = [[float(v) for v in row] for row in control_matrix_pre]
+    c_post = [[float(v) for v in row] for row in control_matrix_post]
+
+    n_controls = len(c_pre)
+    t0 = len(t_pre)
+    t1 = len(t_post)
+    if n_controls < 1 or t0 < 2 or t1 < 1:
+        raise ValueError("synthetic_did_ate requires >=1 control unit, >=2 pre-periods, and >=1 post-period.")
+
+    # 1. Compute unit weights omega_i via regularized pre-treatment trajectory distance
+    #    (exponential softmax over inverse L2 pre-trend MSE after level-demean)
+    t_pre_mean = sum(t_pre) / t0
+    t_pre_centered = [y - t_pre_mean for y in t_pre]
+
+    inv_scores: List[float] = []
+    for j in range(n_controls):
+        row = c_pre[j][:t0]
+        m_j = sum(row) / len(row)
+        mse = sum(((row[t] - m_j) - t_pre_centered[t]) ** 2 for t in range(t0)) / t0
+        inv_scores.append(math.exp(-mse / max(float(ridge_zeta), 1e-4)))
+
+    sum_inv = sum(inv_scores)
+    omega = [w / sum_inv if sum_inv > 0 else (1.0 / n_controls) for w in inv_scores]
+
+    # 2. Compute time weights lambda_t matching control post-treatment average to pre-treatment steps
+    c_post_means = [sum(c_post[j]) / len(c_post[j]) for j in range(n_controls)]
+    time_scores: List[float] = []
+    for t in range(t0):
+        err_t = sum(omega[j] * ((c_pre[j][t] - c_post_means[j]) ** 2) for j in range(n_controls))
+        time_scores.append(math.exp(-err_t / max(float(ridge_zeta) * 2.0, 1e-4)))
+    sum_t = sum(time_scores)
+    lambd = [lt / sum_t if sum_t > 0 else (1.0 / t0) for lt in time_scores]
+
+    # 3. Compute weighted pre/post averages for treated and synthetic control
+    y_tr_pre_w = sum(lambd[t] * t_pre[t] for t in range(t0))
+    y_tr_post = sum(t_post) / t1
+
+    y_sc_pre_w = sum(
+        omega[j] * sum(lambd[t] * c_pre[j][t] for t in range(t0))
+        for j in range(n_controls)
+    )
+    y_sc_post = sum(omega[j] * (sum(c_post[j]) / len(c_post[j])) for j in range(n_controls))
+
+    # Standard unweighted DiD vs SDID estimator
+    unweighted_sc_pre = sum(sum(c_pre[j]) / t0 for j in range(n_controls)) / n_controls
+    unweighted_sc_post = sum(sum(c_post[j]) / len(c_post[j]) for j in range(n_controls)) / n_controls
+    did_classic = (y_tr_post - t_pre_mean) - (unweighted_sc_post - unweighted_sc_pre)
+    sdid_att = (y_tr_post - y_tr_pre_w) - (y_sc_post - y_sc_pre_w)
+
+    # Pre-treatment root mean squared prediction error (RMSPE)
+    pre_rmspe = math.sqrt(
+        sum(
+            (
+                (t_pre[t] - y_tr_pre_w)
+                - (sum(omega[j] * c_pre[j][t] for j in range(n_controls)) - y_sc_pre_w)
+            )
+            ** 2
+            for t in range(t0)
+        )
+        / t0
+    )
+
+    return {
+        "sdid_att_estimate": round(sdid_att, 5),
+        "classic_did_estimate": round(did_classic, 5),
+        "treated_post_mean": round(y_tr_post, 4),
+        "counterfactual_post_mean": round(y_tr_post - sdid_att, 4),
+        "pre_treatment_rmspe": round(pre_rmspe, 5),
+        "unit_weights_omega": [round(w, 4) for w in omega],
+        "time_weights_lambda": [round(lt, 4) for lt in lambd],
+        "reference": "Arkhangelsky et al. (American Economic Review, 2021) Synthetic DiD",
+    }
+
+
+def innovative_polygon_trend(
+    y: Sequence[float],
+) -> Dict[str, Any]:
+    """
+    Compute Şen's Innovative Trend Analysis (ITA) & Post-2020 Sub-Regime Quantile
+    Trend Decomposition (Low, Medium, Extreme High Clusters).
+
+    Splits the series into two equal halves, sorts both halves in ascending order,
+    projects onto the 1:1 Cartesian line, and evaluates whether extreme highs
+    are accelerating faster than central tendencies.
+
+    Post-2020 Hydro-Climatological References:
+      - Şen, Z. (2020, 2021). Innovative polygon trend analysis (IPTA) and applications.
+        Journal of Hydrology / Theoretical and Applied Climatology.
+    """
+    vals = [float(v) for v in y if v is not None and not math.isnan(float(v))]
+    n = len(vals)
+    if n < 6:
+        raise ValueError("innovative_polygon_trend requires at least 6 observations.")
+
+    half = n // 2
+    first_half = sorted(vals[:half])
+    second_half = sorted(vals[-half:])
+
+    m1 = sum(first_half) / half
+    m2 = sum(second_half) / half
+    s_ita = (2.0 * (m2 - m1)) / float(n)
+    d_indicator = ((m2 - m1) / max(abs(m1), 1e-9)) * 100.0
+
+    # Partition sorted pairs into Low (bottom 1/3), Medium (middle 1/3), Extreme High (top 1/3)
+    k1 = max(1, half // 3)
+    k2 = max(k1 + 1, (2 * half) // 3)
+    low_diff = sum(second_half[i] - first_half[i] for i in range(0, k1)) / k1
+    med_diff = sum(second_half[i] - first_half[i] for i in range(k1, k2)) / max(k2 - k1, 1)
+    high_diff = sum(second_half[i] - first_half[i] for i in range(k2, half)) / max(half - k2, 1)
+
+    return {
+        "n_used": 2 * half,
+        "first_half_mean": round(m1, 4),
+        "second_half_mean": round(m2, 4),
+        "ita_slope_per_step": round(s_ita, 6),
+        "ita_relative_change_pct": round(d_indicator, 2),
+        "subregime_shifts": {
+            "low_quantile_shift": round(low_diff, 4),
+            "medium_quantile_shift": round(med_diff, 4),
+            "extreme_high_quantile_shift": round(high_diff, 4),
+        },
+        "tail_amplification_ratio": round(high_diff / med_diff, 3) if abs(med_diff) > 1e-6 else None,
+        "reference": "Şen (2020, 2021) Innovative Polygon & Sub-Regime Quantile Trend Analysis",
+    }
+
+
+def transfer_entropy_causal(
+    x: Sequence[float],
+    y: Sequence[float],
+    bins: int = 3,
+) -> Dict[str, Any]:
+    """
+    Compute Information-Theoretic Shannon Transfer Entropy (T_{X->Y} and T_{Y->X} in bits)
+    and Net Directed Causal Information Flow between Two Climate/Ocean Series.
+
+    Post-2020 Scientific References:
+      - Runge, J., Bathiany, S., Bollt, E., Camps-Valls, G., Coumou, D., Deyle, E., ... &
+        Zscheischler, J. (2019 / 2023). Inferring causation from time series in Earth
+        system sciences. Nature Communications, 10(1), 2553; Nature Reviews Earth &
+        Environment (2023).
+
+    Formula:
+        T_{X -> Y} = sum p(y_t, y_{t-1}, x_{t-1}) * log2( p(y_t | y_{t-1}, x_{t-1}) / p(y_t | y_{t-1}) )
+    """
+    xv = [float(v) for v in x]
+    yv = [float(v) for v in y]
+    n = min(len(xv), len(yv))
+    if n < 8:
+        raise ValueError("transfer_entropy_causal requires at least 8 paired observations.")
+
+    def _quantize(arr: List[float], b: int) -> List[int]:
+        s = sorted(arr)
+        cuts = [s[int((k / float(b)) * (len(s) - 1))] for k in range(1, b)]
+        out: List[int] = []
+        for val in arr:
+            idx = 0
+            for c in cuts:
+                if val > c:
+                    idx += 1
+            out.append(idx)
+        return out
+
+    qx = _quantize(xv[:n], max(int(bins), 2))
+    qy = _quantize(yv[:n], max(int(bins), 2))
+
+    def _calc_te(src: List[int], dst: List[int]) -> float:
+        total = n - 1
+        c_xyz: Dict[Tuple[int, int, int], int] = {}
+        c_xy: Dict[Tuple[int, int], int] = {}
+        c_yz: Dict[Tuple[int, int], int] = {}
+        c_y: Dict[int, int] = {}
+        for t in range(1, n):
+            yt = dst[t]
+            yt1 = dst[t - 1]
+            xt1 = src[t - 1]
+            c_xyz[(yt, yt1, xt1)] = c_xyz.get((yt, yt1, xt1), 0) + 1
+            c_xy[(yt, yt1)] = c_xy.get((yt, yt1), 0) + 1
+            c_yz[(yt1, xt1)] = c_yz.get((yt1, xt1), 0) + 1
+            c_y[yt1] = c_y.get(yt1, 0) + 1
+
+        te_bits = 0.0
+        for (yt, yt1, xt1), cnt in c_xyz.items():
+            p_xyz = cnt / float(total)
+            p_yt_given_yt1_xt1 = cnt / float(c_yz[(yt1, xt1)])
+            p_yt_given_yt1 = c_xy[(yt, yt1)] / float(c_y[yt1])
+            if p_yt_given_yt1_xt1 > 0 and p_yt_given_yt1 > 0:
+                te_bits += p_xyz * math.log2(p_yt_given_yt1_xt1 / p_yt_given_yt1)
+        return max(te_bits, 0.0)
+
+    te_x_to_y = _calc_te(qx, qy)
+    te_y_to_x = _calc_te(qy, qx)
+    net_flow = te_x_to_y - te_y_to_x
+
+    if abs(net_flow) < 0.02:
+        direction = "Bidirectional / Weakly Coupled Feedback"
+    elif net_flow > 0:
+        direction = "X -> Y (X is the dominant nonlinear driver of Y)"
+    else:
+        direction = "Y -> X (Y is the dominant nonlinear driver of X)"
+
+    return {
+        "n": n,
+        "bins": int(bins),
+        "transfer_entropy_x_to_y_bits": round(te_x_to_y, 5),
+        "transfer_entropy_y_to_x_bits": round(te_y_to_x, 5),
+        "net_information_flow_bits": round(net_flow, 5),
+        "dominant_causal_direction": direction,
+        "reference": "Runge et al. (Nature Communications, 2019; Nat. Rev. Earth Environ., 2023)",
+    }
+
+
+def _solve_linear_system(a_mat: List[List[float]], b_vec: List[float]) -> List[float]:
+    """Solve A * x = b via Gaussian elimination with partial pivoting (pure Python)."""
+    p = len(b_vec)
+    aug = [row[:] + [float(b_vec[i])] for i, row in enumerate(a_mat)]
+    for col in range(p):
+        pivot_row = max(range(col, p), key=lambda r: abs(aug[r][col]))
+        aug[col], aug[pivot_row] = aug[pivot_row], aug[col]
+        piv = aug[col][col]
+        if abs(piv) < 1e-12:
+            piv = 1e-12
+        for j in range(col, p + 1):
+            aug[col][j] /= piv
+        for r in range(p):
+            if r != col:
+                factor = aug[r][col]
+                for j in range(col, p + 1):
+                    aug[r][j] -= factor * aug[col][j]
+    return [aug[i][p] for i in range(p)]
+
+
+def multivariate_data_mining_pipeline(
+    feature_matrix: Sequence[Sequence[float]],
+    feature_names: Optional[Sequence[str]] = None,
+    period_labels: Optional[Sequence[Any]] = None,
+    target_index: int = 0,
+    k_clusters: int = 3,
+    ridge_alphas: Sequence[float] = (0.01, 0.1, 1.0, 10.0),
+) -> Dict[str, Any]:
+    """
+    Execute an End-to-End Multivariate Ocean & Maritime Data Mining Pipeline:
+      1. Z-Score Standardization & Complete-Case Pearson Correlation Matrix (R = Z^T Z / (n-1))
+      2. Principal Component Analysis (PCA via Spectral Power-Iteration & Hotelling Deflation)
+      3. Deterministic K-Means++ Unsupervised Regime Clustering (Arthur & Vassilvitskii, 2007)
+         with Rousseeuw (1987) Silhouette Score validation
+      4. Expanding-Window Time-Series Cross-Validated Multivariate Lag-1 Ridge Regression
+         (Hoerl & Kennard, 1970; Bergmeir et al., 2018) vs. Naive Persistence Baseline
+
+    Parameters
+    ----------
+    feature_matrix : Sequence[Sequence[float]]
+        2D matrix of shape (n_periods, n_features) with numeric observations.
+    feature_names : Sequence[str], optional
+        Variable names corresponding to columns of `feature_matrix`.
+    period_labels : Sequence[Any], optional
+        Time labels (e.g. years 1995..2025) for each row.
+    target_index : int, default 0
+        Column index of the target variable for supervised lag-1 Ridge forecasting.
+    k_clusters : int, default 3
+        Number of ocean-climate/maritime regimes for K-Means++ clustering.
+    ridge_alphas : Sequence[float], default (0.01, 0.1, 1.0, 10.0)
+        Candidate L2 regularization penalties evaluated via expanding-window CV.
+    """
+    rows = [[float(v) for v in r] for r in feature_matrix if r is not None]
+    n = len(rows)
+    if n < 8 or not rows[0]:
+        raise ValueError("multivariate_data_mining_pipeline requires at least 8 complete rows and >=2 features.")
+    p = len(rows[0])
+    if p < 2:
+        raise ValueError("At least 2 features (columns) are required for multivariate data mining.")
+
+    names = list(feature_names) if (feature_names and len(feature_names) == p) else [f"V{j + 1}" for j in range(p)]
+    labels = [str(x) for x in period_labels] if (period_labels and len(period_labels) == n) else [str(i) for i in range(n)]
+    tgt_idx = max(0, min(p - 1, int(target_index)))
+
+    # 1. Column means, standard deviations, and Z-score matrix
+    means = [sum(rows[i][j] for i in range(n)) / n for j in range(p)]
+    stds = [
+        math.sqrt(max(sum((rows[i][j] - means[j]) ** 2 for i in range(n)) / max(n - 1, 1), 1e-12))
+        for j in range(p)
+    ]
+    z_mat = [[(rows[i][j] - means[j]) / stds[j] for j in range(p)] for i in range(n)]
+
+    # Correlation matrix R (p x p)
+    corr_matrix: List[List[float]] = [[0.0] * p for _ in range(p)]
+    for j1 in range(p):
+        for j2 in range(p):
+            if j1 == j2:
+                corr_matrix[j1][j2] = 1.0
+            else:
+                r_val = sum(z_mat[i][j1] * z_mat[i][j2] for i in range(n)) / max(n - 1, 1)
+                corr_matrix[j1][j2] = round(max(-1.0, min(1.0, r_val)), 4)
+
+    # 2. Principal Component Analysis (Top 2 PCs via Power Iteration + Hotelling Deflation)
+    r_work = [[corr_matrix[j1][j2] for j2 in range(p)] for j1 in range(p)]
+    eigenvalues: List[float] = []
+    loadings: List[List[float]] = []
+
+    for comp_idx in range(min(2, p)):
+        vec = [1.0 / math.sqrt(p) if (j + comp_idx) % 2 == 0 else 0.5 / math.sqrt(p) for j in range(p)]
+        for _ in range(80):
+            nxt = [sum(r_work[j1][j2] * vec[j2] for j2 in range(p)) for j1 in range(p)]
+            norm = math.sqrt(max(sum(v * v for v in nxt), 1e-15))
+            vec = [v / norm for v in nxt]
+        # Sign convention: largest-magnitude loading positive
+        max_j = max(range(p), key=lambda j: abs(vec[j]))
+        if vec[max_j] < 0:
+            vec = [-v for v in vec]
+        eig_val = sum(vec[j1] * sum(r_work[j1][j2] * vec[j2] for j2 in range(p)) for j1 in range(p))
+        eig_val = max(eig_val, 0.0)
+        eigenvalues.append(eig_val)
+        loadings.append([round(v, 4) for v in vec])
+        # Hotelling deflation: R_next = R - lambda * v * v^T
+        for j1 in range(p):
+            for j2 in range(p):
+                r_work[j1][j2] -= eig_val * vec[j1] * vec[j2]
+
+    total_var = float(p)
+    evr = [round(ev / total_var, 4) for ev in eigenvalues]
+    pc_scores = [
+        {
+            "period": labels[i],
+            "pc1": round(sum(z_mat[i][j] * loadings[0][j] for j in range(p)), 4),
+            "pc2": round(sum(z_mat[i][j] * loadings[1][j] for j in range(p)), 4) if len(loadings) > 1 else 0.0,
+        }
+        for i in range(n)
+    ]
+
+    # 3. Deterministic K-Means++ Regime Clustering & Silhouette Score
+    k = max(2, min(int(k_clusters), n // 2))
+    # Seed 1: earliest or lowest PC1 observation
+    first_idx = min(range(n), key=lambda i: pc_scores[i]["pc1"])
+    centers_z: List[List[float]] = [z_mat[first_idx][:]]
+    while len(centers_z) < k:
+        # Farthest-point deterministic K-Means++ seeding
+        best_i = max(
+            range(n),
+            key=lambda i: min(
+                sum((z_mat[i][j] - c[j]) ** 2 for j in range(p)) for c in centers_z
+            ),
+        )
+        centers_z.append(z_mat[best_i][:])
+
+    assignments = [0] * n
+    for _ in range(50):
+        changed = False
+        for i in range(n):
+            best_c = min(
+                range(k),
+                key=lambda c_idx: sum((z_mat[i][j] - centers_z[c_idx][j]) ** 2 for j in range(p)),
+            )
+            if assignments[i] != best_c:
+                assignments[i] = best_c
+                changed = True
+        for c_idx in range(k):
+            members = [i for i in range(n) if assignments[i] == c_idx]
+            if members:
+                centers_z[c_idx] = [
+                    sum(z_mat[i][j] for i in members) / len(members) for j in range(p)
+                ]
+        if not changed:
+            break
+
+    # Order clusters chronologically by mean index so Regime 1 -> Regime K is intuitive
+    cluster_order = sorted(
+        range(k),
+        key=lambda c_idx: (
+            sum(i for i in range(n) if assignments[i] == c_idx)
+            / max(1, sum(1 for i in range(n) if assignments[i] == c_idx))
+        ),
+    )
+    remap = {old_c: new_c + 1 for new_c, old_c in enumerate(cluster_order)}
+    ordered_labels = [remap[c_idx] for c_idx in assignments]
+
+    wcss = sum(
+        sum((z_mat[i][j] - centers_z[assignments[i]][j]) ** 2 for j in range(p))
+        for i in range(n)
+    )
+
+    # Rousseeuw (1987) Silhouette Score
+    sil_vals: List[float] = []
+    for i in range(n):
+        ci = ordered_labels[i]
+        same = [m for m in range(n) if ordered_labels[m] == ci and m != i]
+        a_i = (
+            sum(math.sqrt(sum((z_mat[i][j] - z_mat[m][j]) ** 2 for j in range(p))) for m in same) / len(same)
+            if same
+            else 0.0
+        )
+        b_i = Infinity = float("inf")
+        for other_c in range(1, k + 1):
+            if other_c == ci:
+                continue
+            other_members = [m for m in range(n) if ordered_labels[m] == other_c]
+            if other_members:
+                dist_c = sum(
+                    math.sqrt(sum((z_mat[i][j] - z_mat[m][j]) ** 2 for j in range(p)))
+                    for m in other_members
+                ) / len(other_members)
+                if dist_c < b_i:
+                    b_i = dist_c
+        if math.isfinite(b_i) and max(a_i, b_i) > 0:
+            sil_vals.append((b_i - a_i) / max(a_i, b_i))
+    silhouette_score = sum(sil_vals) / len(sil_vals) if sil_vals else 0.0
+
+    cluster_summaries = []
+    for c_num in range(1, k + 1):
+        members = [i for i in range(n) if ordered_labels[i] == c_num]
+        if not members:
+            continue
+        cluster_summaries.append(
+            {
+                "regime_id": c_num,
+                "n_periods": len(members),
+                "period_span": f"{labels[members[0]]}–{labels[members[-1]]}",
+                "centroid_physical_units": {
+                    names[j]: round(sum(rows[i][j] for i in members) / len(members), 4)
+                    for j in range(p)
+                },
+            }
+        )
+
+    # 4. Supervised Lag-1 Multivariate Ridge Regression with Expanding-Window Time-Series CV
+    # Predict rows[t][tgt_idx] using z_mat[t-1][0..p-1]
+    x_lag = [z_mat[t - 1] for t in range(1, n)]
+    y_curr = [rows[t][tgt_idx] for t in range(1, n)]
+    n_pairs = len(y_curr)
+    split_idx = max(int(n_pairs * 0.7), p + 2)
+    split_idx = min(split_idx, n_pairs - 2)
+
+    def _fit_ridge(x_tr: List[List[float]], y_tr: List[float], alpha: float) -> Tuple[float, List[float]]:
+        m_tr = len(y_tr)
+        y_mean = sum(y_tr) / m_tr
+        x_means = [sum(x_tr[i][j] for i in range(m_tr)) / m_tr for j in range(p)]
+        xc = [[x_tr[i][j] - x_means[j] for j in range(p)] for i in range(m_tr)]
+        yc = [y_tr[i] - y_mean for i in range(m_tr)]
+        xtx = [
+            [
+                sum(xc[i][j1] * xc[i][j2] for i in range(m_tr)) + (alpha if j1 == j2 else 0.0)
+                for j2 in range(p)
+            ]
+            for j1 in range(p)
+        ]
+        xty = [sum(xc[i][j] * yc[i] for i in range(m_tr)) for j in range(p)]
+        betas = _solve_linear_system(xtx, xty)
+        intercept = y_mean - sum(betas[j] * x_means[j] for j in range(p))
+        return intercept, betas
+
+    best_alpha = float(ridge_alphas[0])
+    best_cv_rmse = float("inf")
+    cv_start = max(p + 2, split_idx // 2)
+    for alpha_cand in ridge_alphas:
+        sq_errs: List[float] = []
+        for t_eval in range(cv_start, split_idx):
+            b0, b_vec = _fit_ridge(x_lag[:t_eval], y_curr[:t_eval], float(alpha_cand))
+            pred = b0 + sum(b_vec[j] * x_lag[t_eval][j] for j in range(p))
+            sq_errs.append((y_curr[t_eval] - pred) ** 2)
+        cv_rmse = math.sqrt(sum(sq_errs) / max(len(sq_errs), 1)) if sq_errs else float("inf")
+        if cv_rmse < best_cv_rmse:
+            best_cv_rmse = cv_rmse
+            best_alpha = float(alpha_cand)
+
+    # Final out-of-sample test evaluation on [split_idx .. n_pairs-1]
+    b0_final, betas_final = _fit_ridge(x_lag[:split_idx], y_curr[:split_idx], best_alpha)
+    test_preds: List[Dict[str, Any]] = []
+    ridge_sq_err = 0.0
+    naive_sq_err = 0.0
+    ridge_abs_err = 0.0
+    for t_idx in range(split_idx, n_pairs):
+        obs_val = y_curr[t_idx]
+        pred_val = b0_final + sum(betas_final[j] * x_lag[t_idx][j] for j in range(p))
+        naive_val = y_curr[t_idx - 1]
+        ridge_sq_err += (obs_val - pred_val) ** 2
+        naive_sq_err += (obs_val - naive_val) ** 2
+        ridge_abs_err += abs(obs_val - pred_val)
+        test_preds.append(
+            {
+                "period": labels[t_idx + 1],
+                "observed": round(obs_val, 4),
+                "ridge_predicted": round(pred_val, 4),
+                "naive_baseline": round(naive_val, 4),
+            }
+        )
+
+    n_test = max(len(test_preds), 1)
+    test_rmse = math.sqrt(ridge_sq_err / n_test)
+    naive_rmse = math.sqrt(naive_sq_err / n_test)
+    test_mae = ridge_abs_err / n_test
+    skill_score = 1.0 - (test_rmse / max(naive_rmse, 1e-12))
+
+    return {
+        "n_periods": n,
+        "n_features": p,
+        "feature_names": names,
+        "target_variable": names[tgt_idx],
+        "correlation_matrix": {
+            names[j1]: {names[j2]: corr_matrix[j1][j2] for j2 in range(p)} for j1 in range(p)
+        },
+        "pca": {
+            "eigenvalues": [round(ev, 4) for ev in eigenvalues],
+            "explained_variance_ratio": evr,
+            "cumulative_variance_pc1_pc2_pct": round(sum(evr) * 100.0, 2),
+            "loadings_pc1": {names[j]: loadings[0][j] for j in range(p)},
+            "loadings_pc2": {names[j]: loadings[1][j] for j in range(p)} if len(loadings) > 1 else {},
+            "scores": pc_scores,
+        },
+        "kmeans_regimes": {
+            "k": k,
+            "wcss_inertia": round(wcss, 4),
+            "silhouette_score": round(silhouette_score, 4),
+            "regime_labels": ordered_labels,
+            "regimes": cluster_summaries,
+        },
+        "ridge_ml_forecast": {
+            "optimal_alpha_l2": best_alpha,
+            "cv_rmse": round(best_cv_rmse, 4),
+            "test_rmse": round(test_rmse, 4),
+            "naive_baseline_rmse": round(naive_rmse, 4),
+            "test_mae": round(test_mae, 4),
+            "forecast_skill_score_pct": round(skill_score * 100.0, 2),
+            "standardized_coefficients": {names[j]: round(betas_final[j], 5) for j in range(p)},
+            "intercept": round(b0_final, 5),
+            "test_predictions": test_preds,
+        },
+        "reference": (
+            "Jolliffe & Cadima (2016, PCA); Arthur & Vassilvitskii (2007, K-Means++); "
+            "Rousseeuw (1987, Silhouette); Hoerl & Kennard (1970, Ridge); Bergmeir et al. (2018, TS-CV)"
+        ),
+    }
+
+
+def counter_r5_usage_econometrics(
+    pageviews_by_module: Union[Dict[str, float], Sequence[float]],
+    unique_visitors_by_module: Optional[Union[Dict[str, float], Sequence[float]]] = None,
+    item_requests_by_module: Optional[Union[Dict[str, float], Sequence[float]]] = None,
+    dau: int = 0,
+    wau: int = 0,
+    mau: int = 0,
+    authenticated_sessions: int = 0,
+    total_sessions: int = 0,
+) -> Dict[str, Any]:
+    """
+    Project COUNTER Release 5.1 and Make Data Count (Fenner et al., 2019;
+    Cousijn et al., 2019) usage metrics plus information-theoretic concentration
+    measures for a scientific portal.
+
+    Computes:
+      1. `Total_Item_Investigations` & `Unique_Item_Investigations` (COUNTER R5.1)
+      2. `Total_Item_Requests` & `Unique_Item_Requests` (Dataset/API/SDK/PDF retrievals)
+      3. Conversion Efficiency Ratio: CER = Unique_Item_Requests / Unique_Item_Investigations
+      4. Shannon Attention Entropy: H' = -sum(p_i * log2(p_i)) [bits] and Pielou Evenness J' = H' / log2(S)
+      5. Gini Traffic Concentration Coefficient (G in [0, 1]) & Herfindahl-Hirschman Index (HHI)
+      6. DAU/MAU Stickiness Ratio (%) & Institutional Authenticated Session Share (%)
+
+    Metrics whose inputs are not supplied are returned as ``None``; no values are
+    imputed from assumed ratios.
+    """
+    if isinstance(pageviews_by_module, dict):
+        mod_names = list(pageviews_by_module.keys())
+        inv_vals = [max(0.0, float(pageviews_by_module[k])) for k in mod_names]
+    else:
+        inv_vals = [max(0.0, float(x)) for x in pageviews_by_module]
+        mod_names = [f"module_{i+1}" for i in range(len(inv_vals))]
+
+    n_mods = len(inv_vals)
+    if n_mods == 0 or sum(inv_vals) <= 0:
+        raise ValueError("pageviews_by_module must contain at least one positive module count.")
+
+    if unique_visitors_by_module is None:
+        uniq_inv_vals = None
+    elif isinstance(unique_visitors_by_module, dict):
+        uniq_inv_vals = [max(0.0, float(unique_visitors_by_module.get(k, 0.0))) for k in mod_names]
+    else:
+        uniq_inv_vals = [max(0.0, float(x)) for x in unique_visitors_by_module]
+
+    if item_requests_by_module is None:
+        req_vals = None
+    elif isinstance(item_requests_by_module, dict):
+        req_vals = [max(0.0, float(item_requests_by_module.get(k, 0.0))) for k in mod_names]
+    else:
+        req_vals = [max(0.0, float(x)) for x in item_requests_by_module]
+
+    total_investigations = float(sum(inv_vals))
+    unique_investigations = float(sum(uniq_inv_vals)) if uniq_inv_vals is not None else None
+    total_requests = float(sum(req_vals)) if req_vals is not None else None
+    unique_requests = (
+        float(sum(min(r, u) for r, u in zip(req_vals, uniq_inv_vals)))
+        if req_vals is not None and uniq_inv_vals is not None
+        else None
+    )
+
+    cer_pct = (
+        (unique_requests / unique_investigations) * 100.0
+        if unique_requests is not None and unique_investigations
+        else None
+    )
+
+    # Shannon Attention Entropy H' (bits), Pielou Evenness J', and HHI
+    shannon_bits = 0.0
+    hhi = 0.0
+    shares: Dict[str, float] = {}
+    for name, val in zip(mod_names, inv_vals):
+        p = val / total_investigations
+        shares[name] = round(p * 100.0, 2)
+        if p > 0.0:
+            shannon_bits -= p * math.log2(p)
+            hhi += p * p
+
+    pielou_j = shannon_bits / math.log2(n_mods) if n_mods > 1 else 1.0
+
+    # Gini Traffic Concentration
+    sorted_vals = sorted(inv_vals)
+    if n_mods > 1 and total_investigations > 0:
+        weighted = sum((2.0 * (i + 1) - n_mods - 1.0) * v for i, v in enumerate(sorted_vals))
+        gini = max(0.0, min(1.0, weighted / (n_mods * total_investigations)))
+    else:
+        gini = 0.0
+
+    dau_val = int(dau) if dau > 0 else None
+    wau_val = int(wau) if wau > 0 else None
+    mau_val = int(mau) if mau > 0 else None
+    stickiness_dau_mau_pct = (dau_val / mau_val) * 100.0 if dau_val is not None and mau_val else None
+    wau_mau_pct = (wau_val / mau_val) * 100.0 if wau_val is not None and mau_val else None
+    auth_share_pct = (
+        (int(authenticated_sessions) / int(total_sessions)) * 100.0
+        if total_sessions > 0 and authenticated_sessions >= 0
+        else None
+    )
+
+    def _r(v: Optional[float], nd: int) -> Optional[float]:
+        return round(v, nd) if v is not None else None
+
+    def _i(v: Optional[float]) -> Optional[int]:
+        return int(round(v)) if v is not None else None
+
+    return {
+        "n_modules": n_mods,
+        "counter_r51_metrics": {
+            "total_item_investigations": int(round(total_investigations)),
+            "unique_item_investigations": _i(unique_investigations),
+            "total_item_requests": _i(total_requests),
+            "unique_item_requests": _i(unique_requests),
+            "conversion_efficiency_ratio_pct": _r(cer_pct, 2),
+        },
+        "information_theory_concentration": {
+            "shannon_attention_entropy_bits": round(shannon_bits, 4),
+            "pielou_evenness_index": round(pielou_j, 4),
+            "gini_concentration_index": round(gini, 4),
+            "herfindahl_hirschman_index": round(hhi, 4),
+            "module_share_pct": shares,
+        },
+        "engagement_and_auth": {
+            "dau": dau_val,
+            "wau": wau_val,
+            "mau": mau_val,
+            "stickiness_dau_mau_pct": _r(stickiness_dau_mau_pct, 2),
+            "wau_mau_ratio_pct": _r(wau_mau_pct, 2),
+            "authenticated_session_share_pct": _r(auth_share_pct, 2),
+            "privacy_architecture": "Zero-Cookie SHA-256 Daily Rotating Hash (KVKK & GDPR Art. 6(1)(f))",
+        },
+        "reference": (
+            "Project COUNTER Code of Practice Release 5.1; "
+            "Fenner et al. (2019, Scientific Data); "
+            "Cousijn et al. (2019, Data Science Journal)"
+        ),
+    }
+
+
+def audit_numeric_grounding(
+    answer: str,
+    reference_values: Sequence[float],
+    question: str = "",
+    ignore_years: bool = True,
+    ignore_small_integers: int = 12,
+) -> Dict[str, Any]:
+    """
+    Audit whether the numbers in a generated (e.g. LLM) answer are grounded in a set
+    of reference values, such as the observations returned by ``get_series`` or the
+    statistics returned by ``mann_kendall_sen``.
+
+    A number written with ``d`` decimals is considered grounded if some reference
+    value ``r`` satisfies ``|abs(r) - abs(x)| <= 0.5 * 10**(-d)``, i.e. the answer is a
+    correct rounding of a reference value. Both decimal comma (Turkish) and decimal
+    point (English) notation and thousands separators are handled; ambiguous tokens
+    such as ``2.350`` are accepted under either reading. Integers 1800-2100 (years),
+    small integers (list numbering, months) and numbers present in the question are
+    skipped.
+
+    This mirrors the server-side check used by the GOMD Data Assistant and is a
+    deterministic attribution test in the spirit of attributable-to-identified-sources
+    evaluation (Rashkin et al., 2023, Computational Linguistics); it does not judge
+    whether a correct number is used in the right context.
+    """
+    import re as _re
+
+    def _tokens(text: str) -> List[Tuple[str, List[Tuple[float, int]]]]:
+        clean = _re.sub(r"\[[^\]]{1,120}\]", " ", text or "")
+        clean = _re.sub(r"\b\d{4}-\d{2}(-\d{2})?\b", " ", clean)
+        pat = r"(?<![\w])-?\d{1,3}(?:[.,]\d{3})+(?:[.,]\d+)?(?!\d)|(?<![\w])-?\d+(?:[.,]\d+)?(?!\d)"
+        out: List[Tuple[str, List[Tuple[float, int]]]] = []
+        for tok in _re.findall(pat, clean):
+            t = tok.lstrip("-")
+            cands: List[str] = []
+            if "." in t and "," in t:
+                cands.append(t.replace(".", "").replace(",", ".") if t.rfind(",") > t.rfind(".") else t.replace(",", ""))
+            elif "," in t:
+                cands.append(t.replace(",", "."))
+                if _re.fullmatch(r"\d{1,3}(,\d{3})+", t):
+                    cands.append(t.replace(",", ""))
+            elif "." in t:
+                cands.append(t)
+                if _re.fullmatch(r"\d{1,3}(\.\d{3})+", t):
+                    cands.append(t.replace(".", ""))
+            else:
+                cands.append(t)
+            vals = []
+            for c in cands:
+                try:
+                    dec = len(c.split(".", 1)[1]) if "." in c else 0
+                    vals.append((float(c), dec))
+                except ValueError:
+                    pass
+            if vals:
+                out.append((tok, vals))
+        return out
+
+    pool = [abs(float(v)) for v in reference_values if v is not None and not (isinstance(v, float) and math.isnan(v))]
+    q_nums = {abs(v) for _, vals in _tokens(question) for v, _ in vals}
+    grounded: List[str] = []
+    unverified: List[str] = []
+    for tok, vals in _tokens(answer):
+        ok = False
+        for v, dec in vals:
+            av = abs(v)
+            if dec == 0 and ((ignore_years and 1800 <= av <= 2100) or av <= ignore_small_integers):
+                ok = True
+                break
+            if any(abs(av - q) < 1e-9 for q in q_nums):
+                ok = True
+                break
+            tol = 0.5 * 10 ** (-dec) + 1e-9
+            if any(abs(p - av) <= tol for p in pool):
+                ok = True
+                break
+        (grounded if ok else unverified).append(tok)
+    checked = len(grounded) + len(unverified)
+    return {
+        "numbers_checked": checked,
+        "grounded": grounded,
+        "unverified": unverified,
+        "grounding_rate": (len(grounded) / checked) if checked else None,
+        "method": "rounding-tolerance match against reference values; years, small integers and question numbers skipped",
+        "reference": "Rashkin et al. (2023, Computational Linguistics 49(4)); Lewis et al. (2020, NeurIPS)",
+    }
+
+
+