# dataflow

**Repository Path**: ysq233/dataflow

## Basic Information

- **Project Name**: dataflow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-02
- **Last Updated**: 2026-05-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# data-flow-skill

面向数据分析任务的一站式 **Agent Skill**：覆盖“数据类型检测 → 数据理解 → 预处理 → 统计分析 → 可视化图表生成 → 正式报告生成 → 幻灯片生成”的端到端链路。

本仓库的定位更接近“可复用的数据分析工作流组件 + 模板库 + 质量约束（checkpoints）”，适合用作：

- 课程作业/论文实验的可复现分析管线（带结构化中间产物）
- 按数据类型自动切换分析策略的 Agent Skill
- 报告与幻灯片（LaTeX/HTML）的模板与写作约束参考

> 重要：本仓库强调“子任务拆分”和“产物可追溯”。详见 SKILL.md 与 evaluation/。

## 特性

- **数据类型检测与策略分派**：自动识别 `tabular_generic / questionnaire / time_series / literary`
- **结构化产物契约**：将检测、画像、预处理日志、统计摘要、发现等写入固定目录，便于复现与审计
- **可视化模板库**：Matplotlib 论文级静态图模板（多种柱状/折线/散点/雷达/分布/热力等）
- **流程图生成**：内置 Mermaid CLI，支持本地渲染优先，失败可回退远程渲染
- **主题示意图生成**：提供图片生成 CLI（需配置 `DASHSCOPE_API_KEY`）
- **自评价机制**：提供 checkpoints 与评分规则，约束输出质量与交付一致性

## 快速开始

### 1) 环境要求

- Python 3.10+（建议在 conda 环境 `vis_env` 中运行）
- 可选：Node.js（用于 `npx @mermaid-js/mermaid-cli` 本地渲染 Mermaid）
- 可选：LaTeX（`pdflatex`/`bibtex`，用于报告/幻灯片 PDF 编译）

建议在 conda 环境 `vis_env` 中运行（示例）：

```bash
conda create -n vis_env python=3.11
conda activate vis_env
```

安装常用依赖（运行 Matplotlib 模板脚本通常需要）：

```bash
pip install matplotlib numpy pandas
```

部分脚本（如折断轴散点图模板）可能会用到 `scipy`。

### 2) 在 Python 中调用：数据类型检测与策略选择

以示例数据 `cases/` 为例（下面示例使用 CSV 文件）：

```python
from analysis.scripts.analyzer_dataset_detection import detect_dataset
from analysis.scripts.analyzer_strategy_registry import select_strategy

data_path = "cases/case2-表格数据（奥运奖牌）/summer.csv"

detection = detect_dataset(data_path, task_description="对奖牌数据做探索性分析")
strategy = select_strategy(detection)

print(detection)
print(strategy)
```

### 3) Mermaid 流程图：生成并导出 PNG

```bash
python mermaid/cli.py export \
	--title "数据分析流程" \
	--step "导入数据" \
	--step "数据清洗" \
	--step "统计分析" \
	--step "输出报告" \
	--mmd-output mermaid/examples/data_flow.mmd \
	--image-output mermaid/examples/data_flow.png
```

更多用法见 `mermaid/README.md`。

### 4) 主题示意图：按 prompt 生成图片（可选）

需要设置环境变量 `DASHSCOPE_API_KEY`（或在仓库根目录放置 `.env` 文件）。示例：

```bash
python image_gen/image_generator.py generate \
	--prompt "简约插画风格，数据图表与齿轮象征分析流程，背景留白，无文字" \
	--output output/figures/theme_illustration.png
```

约束与写法建议见 `image_gen/prompt_constraints.md`。

### 5) Matplotlib 图表模板：复制并替换数据区

Matplotlib 模板位于 `visualization/matplotlib/scripts/`。推荐流程：

1. 先阅读 `visualization/matplotlib/SKILL.md` 选择合适的样式脚本
2. 复制脚本到你的工作目录或 `output/` 下
3. 只替换脚本顶部的数据区（不要在模板脚本里写复杂数据清洗逻辑）
4. 运行脚本生成图

```bash
python visualization/matplotlib/scripts/box_plot.py
```

## 仓库结构

```text
analysis/                 # 数据检测、策略分派、数据理解、预处理、统计分析、发现生成
visualization/            # Matplotlib 静态图样式模板、ECharts 交互图表
mermaid/                  # Mermaid 流程图生成模块（含 CLI）
image_gen/                # 主题示意图生成（含 CLI，需 API Key）
report/                   # 报告生成说明与 LaTeX 模板
report_template/          # 报告 LaTeX 模板（可直接编写章节内容）
slides/                   # 幻灯片生成说明（HTML/LaTeX PDF）
slides_template/          # 幻灯片 LaTeX 模板
evaluation/               # checkpoints 与评分规则
cases/                    # 示例数据集（表格/问卷/时序/文学语料）
assets/                   # 示例产物（图表/报告/幻灯片等）
docs/                     # 过程性文档（计划/spec 等）
agents/                   # Skill 的 agent 配置（如 openai.yaml）
```

## 工作流与输出契约

整体工作流、强制规则、模块边界与输入/输出约定统一在 `SKILL.md` 中定义。

默认推荐输出目录：

```text
output/
	figures/               # 图表文件
	tables/                # 表格文件
	report/                # report.md / report.tex / report.pdf
	slides/                # slides.html / slides.tex / slides.pdf
	artifacts/             # dataset_detection.json 等结构化产物
```

关键硬约束（节选）：

- 所有预处理动作必须记录，不得静默修改数据
- 数据处理/分析/可视化必须按“子任务脚本”拆分执行，禁止一个脚本跑完整链路
- 报告/幻灯片生成阶段禁止写一次性代码，必须在既有模板上直接写内容

完整 checkpoints 见 `evaluation/checkpoints.md`。

## 文档入口

- `SKILL.md`：总工作流、强制规则、输入输出契约
- `analysis/README.md`：分析模块边界、执行顺序、产物规范
- `mermaid/README.md`：Mermaid CLI 与渲染策略
- `visualization/matplotlib/SKILL.md`：图表模板选择与数据替换规则
- `report/reporter_report-generation.md`：报告生成顺序与写作约束
- `slides/slides_slide-generation.md`：幻灯片生成顺序与内容选择规则

## 贡献指南（Contributing）

欢迎以 Issue / PR 的方式贡献：

1. 新增/修改分析逻辑时，请遵守 `evaluation/checkpoints.md` 的硬约束（尤其是“子任务拆分”和“产物可追溯”）
2. 新增图表模板时，请补充对应的说明文档（参考 `visualization/matplotlib/SKILL.md`）
3. 若新增策略，请同步更新 `analysis/scripts/analyzer_strategy_registry.py` 与 `analysis/strategies/`

## 团队分工与贡献

| 成员 | 贡献占比 | 主要分工 |
|------|---------|---------|
| yuan shengqi | 20% | SKILL.md工作流编排，evaluation模块，echarts模块 |
| Yuluxue | 20% | analysis 模块（数据分析、策略、预处理、统计分析、发现生成），演示PPT制作 |
| 小纸团 | 20% | Pdf报告生成模块，演示PPT制作 |
| Hejinfeng | 20% | 幻灯片模块（slides/tex 模板、slides scripts），项目报告 |
| HAHAJN | 20% | 可视化（mermaid 流程图、visualization 图表），REDAME |