72 lines
3.5 KiB
Markdown
72 lines
3.5 KiB
Markdown
# charts 数据模式（现行版）
|
||
|
||
> 旧版文档已存档为 `docs/旧的charts-data-mode-plan.md`。
|
||
|
||
## 目标
|
||
- 后端返回结构化图表数据，前端用 ECharts 渲染；不再生成/传输图片。
|
||
- 统一清洗，避免 NaN/Inf/不可序列化对象导致接口崩溃。
|
||
- 响应结构以 `analysis.<lang>.charts` 为准；`images` 为空仅用于兼容旧前端。
|
||
|
||
## 序列化规范（to_echarts_safe 已实现）
|
||
- NaN/Inf/pd.NA → null；numpy 标量转原生类型；Decimal 转 float。
|
||
- Timestamp/datetime → ISO8601 字符串。
|
||
- ndarray/DataFrame/Series → list 或 records；递归清洗并防循环引用。
|
||
|
||
## 响应骨架（实际线上形态）
|
||
```json
|
||
{
|
||
"success": true,
|
||
"meta": { ... },
|
||
"analysis": {
|
||
"zh": {
|
||
"data_description": "...",
|
||
"preprocessing_steps": [...],
|
||
"api_analysis": { ... },
|
||
"steps": [
|
||
{ "key": "ts_img", "title": "Time Series Analysis", "chart": "ts", "summary": "..." },
|
||
...
|
||
],
|
||
"charts": {
|
||
"ts": { ... },
|
||
"acf_pacf": { ... },
|
||
...
|
||
}
|
||
}
|
||
},
|
||
"images": {},
|
||
"log": [...]
|
||
}
|
||
```
|
||
- 顶层不再单独返回 `charts`；前端应读取 `analysis.<lang>.charts`。如需顶层别名，可在路由层追加映射。
|
||
- `steps[].chart` 指向 `charts` 中的 key，驱动前端展示顺序。
|
||
|
||
## 图表数据格式（按现实现状）
|
||
- **时间序列 ts**：`type: line`，`dataset = [[col...], [...]]`，含 timestamp 字符串。
|
||
- **ACF/PACF acf_pacf**：`series: [{name: col, acf:[{lag,value}], pacf:[{lag,value}]}]`，每个列打包在同一项。
|
||
- **平稳性 stationarity**：`records: [{column, ADF:{...}, KPSS:{...}}]`。
|
||
- **正态性 normality**：`records: [{column, histogram:[{range_start,range_end,count},...], Shapiro-Wilk:{...}, Jarque-Bera:{...}}]`。
|
||
- **季节分解 seasonal**：`type: line`，`dataset` 包含 observed/trend/seasonal/resid，缺失为 null。
|
||
- **频谱 spectral（已做摘要以控体积）**：
|
||
- `spectrogram`: `f`, `t`, `Sxx_log10_mean`, `Sxx_shape`；不返回完整矩阵。
|
||
- `periodogram`: `f` 与 `Pxx_den` 仅前 20 个点。
|
||
- **相关性 heatmap**：`type: heatmap`，`data` 为 `[i,j,value]` 扁平列表，含 xLabels/yLabels。
|
||
- **PCA 碎石 pca_scree**：`type: bar`，`dataset` 组件/解释度/累积值。
|
||
- **PCA 散点 pca_scatter**：`type: scatter`，`records` 含 PC1/PC2/timestamp。
|
||
- **特征重要性 feature_importance**：`type: bar`，`records` 含 feature/importance。
|
||
- **聚类 cluster**：`type: scatter`，`records` 含 cluster 与 timestamp。
|
||
- **因子分析 factor**：`type: scatter`，`records` 含 Factor1/Factor2 与 timestamp。
|
||
- **协整 cointegration**：`type: table`，`meta` 直接承载 trace_stat/crit_vals/eigen_vals。
|
||
- **VAR 预测 var_forecast**：`type: line`，`dataset` 含 step 与各 forecast 列。
|
||
|
||
## 兼容与注意
|
||
- `images` 为空对象；任何遗留的 `image_path` 已剔除。
|
||
- 当前频谱输出为“摘要版”，若要还原全量矩阵需调整 `perform_spectral_analysis`。
|
||
- ACF/PACF 结构与旧文档不同，前端需按现状解码；若要拆分 series，可在后端调整 `_build_chart_payload`。
|
||
- 正态性直方图已由后端分箱，无需前端再分箱。
|
||
|
||
## 已知可选改进
|
||
1) 路由层增加顶层 `charts` 别名，便于前端迁移。
|
||
2) ACF/PACF 改为每列拆两条 series（acf/pacf），与旧示例一致。
|
||
3) 为 spectral 增加 `mode=full|summary` 开关，前端可选取全量或摘要。
|
||
4) 对大体积 dataset 增加可选抽样/截断策略。
|