"""绘图。

`plot` 是一个通用入口，按 `kind` 分派；三个专用图有真实的额外逻辑
（显著性星标、残差诊断、收敛曲线），所以单独保留。
"""

from __future__ import annotations

from typing import Any

__all__ = ["plot", "plot_convergence", "plot_correlation_matrix", "plot_residuals"]


def plot(
    x: Any = None,
    y: Any = None,
    kind: str = "line",
    ax: Any = None,
    labels: Any = None,
    title: str | None = None,
    xlabel: str | None = None,
    ylabel: str | None = None,
    **kwargs: Any,
) -> Any:
    """通用绘图入口。

    Parameters
    ----------
    kind:
        `"line"` / `"scatter"` / `"hist"` / `"box"` / `"bar"` / `"heatmap"` / `"pie"`。
    ax:
        传入已有 axes 就在上面画（多子图场景）；`None` 时新建 figure。

    Returns
    -------
    符合"创建—绘制—保存"三段的 `(fig, ax)`，交给 :func:`save_figure`。

    Examples
    --------
    >>> fig, ax = plot([1, 2, 3], [1, 4, 9], kind="line")   # doctest: +SKIP
    """
    # TODO(L1)
    raise NotImplementedError


def plot_correlation_matrix(data: Any, method: str = "pearson", annot: bool = True, significance: bool = True) -> Any:
    """相关矩阵热图。

    `significance=True` 时在不显著的格子（`p > 0.05`）上打叉。
    这比只画颜色有意义得多——**不显著的相关性画出来是误导**。
    """
    # TODO(L1)
    raise NotImplementedError


def plot_residuals(y_true: Any, y_pred: Any, n_features: int | None = None) -> Any:
    """残差诊断四联图：残差-拟合值、Q-Q 图、直方图、残差-序。

    拟合完模型**第一件事就是看这个**：
    * 残差-拟合值有漏斗形 → 异方差，考虑加权最小二乘或对数变换；
    * Q-Q 图偏离直线 → 正态性假设不成立，区间估计要改用 bootstrap；
    * 残差有周期性 → 漏了时间/结构项。

    这三个诊断结论是论文"模型检验"一节的素材，比只报一个 R² 有说服力。
    """
    # TODO(L1)
    raise NotImplementedError


def plot_convergence(history: Any, ax: Any = None, labels: Any = None, log: bool = False, reference: float | None = None) -> Any:
    """收敛曲线。

    `history` 可以是迭代轨迹数组、也接受 `Result.extras["history"]`
    （`simulated_annealing` 与 `monte_carlo` 都会填这个字段）。
    `reference` 传入解析解时会把真值画成虚线，
    用于"MC 积分误差随 n 收敛"这类图——这是证明 `n` 选得合理的标准做法。
    """
    # TODO(L1)
    raise NotImplementedError