================================================================================
  A14 算法库 — 开发者功能触发说明
  版本 1.0  |  2026-07-08
================================================================================

本文档面向二次开发的程序员，说明每个算法模块的函数签名、参数含义、
返回值结构，以及如何从前端/API/Agent 触发这些功能。


════════════════════════════════════════════════════════
  一、触发架构总览
════════════════════════════════════════════════════════

  用户前端 / API请求
       ↓
  Agent 解析意图 → 生成 workflow JSON
       ↓
  pipeline/engine.py 调度执行
       ↓
  algorithms/*.py (本库)  ← 你现在看的
       ↓
  返回结果 + 图表 → Agent 生成报告


════════════════════════════════════════════════════════
  二、各模块函数签名与参数详解
════════════════════════════════════════════════════════


2.1 preprocess.py — 数据清洗
────────────────────────────────────────

clean_pipeline(df, cols, time_col, freq, outlier_method, outlier_threshold, missing_method)
  → (DataFrame, dict)

  df: DataFrame              — 原始数据
  cols: List[str] | None     — 处理哪些列，None=所有数值列
  time_col: str | None       — 时间列名，None=用现有索引
  freq: str                  — 重采样频率 "1s" "100ms" 等
  outlier_method: "3sigma" | "iqr"
  outlier_threshold: float   — 3σ=3.0, IQR=1.5 为常用值
  missing_method: "interpolate" | "ffill" | "bfill" | "drop" | "mean"

  👤 触发：用户说 "清洗数据" → Agent 调此函数
  📤 返回：stats["outliers_detected"] 告诉前端 "检测到 N 个异常值"

align_timestamps(df, time_col, freq, method)
  → DataFrame

detect_outliers_3sigma(df, cols, threshold)
  → DataFrame（异常值处变 NaN）

detect_outliers_iqr(df, cols, factor)
  → DataFrame（异常值处变 NaN）

handle_missing(df, cols, method)
  → DataFrame


2.2 segment.py — 动态截取（★ 核心）
────────────────────────────────────────

identify_steady_transient(series, method, window, filter_lambda, threshold, rate_threshold)
  → np.ndarray[bool]

  series: np.ndarray         — 单变量时序
  method: "rhinehart"|"rate" — Rhinehart算法(推荐) | 变化率法(快速)
  window: int                — 窗口大小 30~100，越大越平滑
  filter_lambda: float       — Rhinehart滤波系数 0.01~0.05，越小越平滑
  threshold: float           — 瞬态判定阈值 0.3~1.0，越大越严格
  rate_threshold: float      — 变化率阈值(仅rate模式)

  返回：True=瞬态点，False=稳态点

  👤 触发：用户说 "找出动态段" → Agent 调此函数

extract_dynamic_data(df, var_cols, method, window, filter_lambda, threshold, min_segment_length, expand_margin)
  → dict {
      "segments": [(start, end), ...],   ← 截取段索引
      "labels": np.ndarray[bool],       ← 全序列标注
      "dataframes": [DataFrame, ...],   ← 各段独立 DataFrame
      "combined_df": DataFrame,         ← 拼接后的数据
    }

  min_segment_length: int    — 最小段长度，太短丢弃
  expand_margin: int         — 瞬态段前后扩展 margin

  👤 触发：用户说 "提取1号塔高信噪比的动态数据" → Agent 调此函数

extract_transient_segments(labels, min_gap, min_length)
  → List[Tuple[int, int]]


2.3 quality.py — 质量评分
────────────────────────────────────────

score_segment(df, var_cols, weights)
  → dict {
      "total_score": float,         ← 0~100 综合分
      "snr_score": float,
      "dynamic_score": float,
      "stationarity_score": float,
      "length_score": float,
      "snr_values": {col: float},
      "segment_length": int,
    }

  weights: {"snr":0.3, "dynamic":0.3, "stationarity":0.2, "length":0.2}

  👤 触发：用户说 "对截取的数据段评分排序" → Agent 调此函数

rank_segments(segments, var_cols, weights)
  → List[dict]  按 total_score 降序排列

  输入 segments 是 DataFrame 列表（来自 extract_dynamic_data 的 dataframes）

compute_snr(series) → float  信噪比(dB)
compute_dynamic_richness(series) → float  动态丰富度
compute_stationarity(series) → float  平稳性


2.4 delay.py — 时滞分析
────────────────────────────────────────

compute_time_delay(x, y, max_lag, dt)
  → dict {
      "lag_samples": int,       ← x超前y的采样点数（正=超前，负=滞后）
      "lag_seconds": float,
      "correlation": float,     ← 最大互相关系数 [-1,1]
      "lags": [int],
      "correlations": [float],
    }

  max_lag: int     — 最大搜索窗口（采样点），建议 100~500
  dt: float        — 采样间隔（秒）

  👤 触发：用户说 "分析变量间时滞" → Agent 调此函数

time_delay_matrix(df, var_cols, max_lag, dt)
  → DataFrame   行列均为变量名，值=lag_samples
  (diagonal=0，矩阵不对称)

  👤 触发：用户说 "计算时滞矩阵" → Agent 调此函数

compensate_delay(df, delay_matrix, reference_col)
  → DataFrame   所有变量对齐到 reference_col

  👤 触发：用户说 "补偿时滞" → Agent 调此函数


2.5 collinear.py — 共线性分析
────────────────────────────────────────

compute_vif(df, cols)
  → DataFrame  两列：variable, VIF
  VIF > 10 → 严重共线性，建议剔除

find_redundant_variables(df, cols, vif_threshold)
  → dict {
      "redundant": [col],          ← 建议剔除
      "keep": [col],               ← 保留
      "vif_table": [{dict}, ...],
      "removal_reason": {col: str},
    }

pca_reduce(df, cols, n_components, variance_threshold)
  → dict {
      "transformed": np.ndarray,        ← 降维后数据
      "components": [[float]],          ← 载荷矩阵
      "explained_variance_ratio": [...],
      "cumulative_variance": float,
      "n_components_kept": int,
      "feature_names": ["PC1",...],
    }

  n_components=None → 由 variance_threshold(0.95) 自动决定

collinearity_pipeline(df, cols, vif_threshold, pca_variance_threshold, auto_remove)
  → dict {vif_analysis, pca_result, processed_df}

  👤 触发：用户说 "处理共线性" → Agent 调用此 pipeline


2.6 identify.py — 系统辨识（ARX）
────────────────────────────────────────

class ARXModel(na, nb, nk)
  na: int  自回归阶次（y的历史项数）
  nb: int  外生输入阶次（u的历史项数）
  nk: int  输入延迟（采样周期数）

  model.fit(y, u)
    → dict {
        "na","nb","nk","n_params","n_samples",
        "theta": [float],          ← 模型参数 [a1...ana, b1...bnb]
        "FIT_percent": float,      ← ★ 核心指标，越高越好
        "FPE": float,              ← 最终预测误差
        "MSE": float,
        "RMSE": float,
        "AIC": float,              ← 赤池信息准则，越小越好
        "residual_variance": float,
      }

  model.predict(y, u) → np.ndarray  一步前向预测

auto_select_order(y, u, na_range, nb_range, nk, criterion)
  → dict {best_na, best_nb, best_nk, best_score, criterion, best_info, all_results}

  na_range/nb_range: (min, max)  搜索范围
  criterion: "AIC" | "FPE" | "FIT"

  👤 触发：用户说 "训练模型" → Agent 调 ARXModel.fit()
  👤 触发：用户说 "自动选最佳模型阶次" → Agent 调 auto_select_order()


2.7 visualize.py — 可视化
────────────────────────────────────────
所有函数返回 base64 字符串，前端直接 <img src="data:image/png;base64,{{img}}">

plot_cleaning_comparison(original, cleaned, var_name) → str
  清洗前后上下对比图

plot_dynamic_segments(df, var_name, labels, segments) → str
  波形 + 红/绿底色标注瞬态/稳态

plot_correlation_heatmap(df, cols) → str
  变量相关性热力图（带数值标注）

plot_delay_heatmap(delay_matrix) → str
  时滞矩阵热力图（带数值标注）

plot_convergence_curve(iterations, scores, metric_name) → str
  闭环寻优收敛曲线（自动标注最优值）

plot_prediction_vs_actual(y_true, y_pred, fit_pct) → str
  ARX 辨识 预测vs实际 对比图


════════════════════════════════════════════════════════
  三、Agent 集成指南
════════════════════════════════════════════════════════

算法库已通过 app/algorithms/__init__.py 统一导出。
Agent (agent/tools.py) 中，每种操作封装为一个 LangChain Tool：

  from app.algorithms import clean_pipeline, extract_dynamic_data, rank_segments
  from app.algorithms import time_delay_matrix, collinearity_pipeline
  from app.algorithms import ARXModel
  from app.algorithms import plot_cleaning_comparison, plot_convergence_curve

每个 Tool 的输入是 JSON 参数，输出是 JSON 结果。
图表函数返回 base64，放入 JSON 响应的 images 字段。

示例 Tool 定义：
  {
    "name": "clean_data",
    "description": "清洗工业时序数据：异常值检测+缺失值处理",
    "parameters": {
      "outlier_method": {"type": "string", "enum": ["3sigma", "iqr"]},
      "outlier_threshold": {"type": "number", "default": 3.0},
      "missing_method": {"type": "string", "default": "interpolate"},
    }
  }


════════════════════════════════════════════════════════
  四、各功能触发条件汇总
════════════════════════════════════════════════════════

  用户说的                       → 调用的函数
  ─────────────────────────────  ──────────────────
  "上传/查看/删除数据"            → API routes.py（非算法库）
  "生成仿真测试数据"              → generate_data.py
  "清洗数据" / "去异常值"         → clean_pipeline()
  "找出动态数据段" / "高信噪比"   → extract_dynamic_data()
  "给数据段打分排序"              → rank_segments()
  "分析时滞" / "计算滞后关系"     → time_delay_matrix() / compute_time_delay()
  "补偿时滞" / "对齐时间"         → compensate_delay()
  "检测共线性"                   → compute_vif() / find_redundant_variables()
  "PCA降维"                      → pca_reduce()
  "处理共线性"（一键）            → collinearity_pipeline()
  "训练ARX模型" / "系统辨识"     → ARXModel.fit()
  "自动选最佳模型阶次"            → auto_select_order()
  "生成清洗对比图"               → plot_cleaning_comparison()
  "生成波形高亮图"               → plot_dynamic_segments()
  "生成相关性热力图"              → plot_correlation_heatmap()
  "生成时滞热力图"               → plot_delay_heatmap()
  "生成收敛曲线"                 → plot_convergence_curve()
  "生成辨识对比图"               → plot_prediction_vs_actual()
