3.5 KiB
3.5 KiB
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；递归清洗并防循环引用。
响应骨架（实际线上形态）
{
"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。 - 正态性直方图已由后端分箱，无需前端再分箱。
已知可选改进
- 路由层增加顶层
charts别名，便于前端迁移。 - ACF/PACF 改为每列拆两条 series（acf/pacf），与旧示例一致。
- 为 spectral 增加
mode=full|summary开关，前端可选取全量或摘要。 - 对大体积 dataset 增加可选抽样/截断策略。