docs/12_usage_guide.md

ChartPipeline 使用指南

本指南将帮助您快速上手 ChartPipeline 框架，了解如何安装、配置和使用该工具生成高质量的数据可视化。

目录

• 安装
• 基本使用
• 进阶使用
• 常见问题
• 故障排除

安装

系统要求

• Python 3.8 或更高版本
• 建议使用 Linux 或 macOS，Windows 也支持

安装步骤

1. 克隆代码库：

   git clone https://github.com/yourusername/ChartPipeline.git
   cd ChartPipeline
   

2. 安装依赖：

   pip install -r requirements.txt
   

3. 验证安装：

   python -m pipeline --help
   

基本使用

ChartPipeline 可以通过以下方式使用：

1. 完整管道处理

使用 pipeline.py 脚本执行整个数据可视化生成流程：

python pipeline.py --input data.json --output chart.svg

这将依次执行所有模块，将 data.json 转换为 chart.svg。

2. 单模块处理

您也可以单独调用特定模块：

# 图表类型推荐
python -m modules.chart_type_recommender.chart_type_recommender --input data.json --output data_with_chart_type.json

# 数据洞察生成
python -m modules.datafact_generator.datafact_generator --input data_with_chart_type.json --output data_with_insights.json

# 其他模块类似...

3. 编程方式使用

在您自己的 Python 代码中使用：

from pipeline import run_pipeline

success = run_pipeline(
    input_path='data.json',
    output_path='output.svg',
    temp_dir='tmp'
)

if success:
    print("可视化生成成功！")

数据准备

ChartPipeline 需要特定格式的 JSON 输入文件。以下是创建有效输入的指南：

输入文件结构

输入 JSON 应包含两个主要部分：metadata 和 data：

{
  "metadata": {
    "title": "图表标题",
    "description": "图表描述",
    "main_insight": "主要洞察"
  },
  "data": {
    "columns": [
      {
        "name": "列名",
        "importance": "primary",
        "description": "列描述",
        "unit": "单位",
        "data_type": "数据类型",
        "role": "在图表中的角色"
      },
      // 更多列定义...
    ],
    "data": [
      {
        "列名1": 值1,
        "列名2": 值2,
        // ...
      },
      // 更多数据行...
    ]
  }
}

参考 输入数据格式 获取详细规范。

示例数据

框架附带了几个示例数据文件，您可以作为参考：

# 使用示例数据生成图表
python pipeline.py --input examples/time_series/national_emergencies.json --output emergencies_chart.svg

进阶使用

自定义模块执行

您可以选择仅执行部分模块：

python pipeline.py --input data.json --output chart.svg --modules chart_type_recommender,datafact_generator,title_generator,chart_engine

临时文件存储

管理临时文件的位置：

python pipeline.py --input data.json --output chart.svg --temp-dir ./my_temp_folder

配置文件

通过配置文件自定义框架行为：

1. 创建配置文件 config.yaml：

   chart_type_recommender:
     max_recommendations: 3
     
   datafact_generator:
     max_facts: 5
     
   color_recommender:
     color_blind_friendly: true
     
   # 其他模块配置...
   

2. 应用配置：

   python pipeline.py --input data.json --output chart.svg --config config.yaml
   

输出格式

ChartPipeline 默认输出 SVG 格式，但也支持转换为其他格式：

# 导出为 PNG
python pipeline.py --input data.json --output chart.png --format png

# 导出为 PDF
python pipeline.py --input data.json --output chart.pdf --format pdf

自定义和扩展

添加新图表类型

1. 在 modules/chart_engine/templates/ 目录下创建新模板文件
2. 在 modules/chart_engine/chart_engine.py 中注册新图表类型
3. 在 modules/chart_type_recommender/chart_type_recommender.py 中添加新图表类型的推荐逻辑

故障排除

常见错误

1. 输入数据格式错误

   • 检查 JSON 文件格式是否符合要求
   • 验证所有必需字段是否存在

2. 模块导入错误

   • 确认已安装所有依赖项
   • 检查 Python 环境路径是否正确

3. SVG 渲染问题

   • 确保系统安装了必要的图形库
   • 检查生成的 SVG 文件语法是否正确

日志和调试

启用详细日志以帮助诊断问题：

python pipeline.py --input data.json --output chart.svg --log-level debug

日志文件默认保存在 logs/ 目录中。

性能优化

提高处理大型数据集的速度：

1. 使用 PyPy 代替 CPython 运行框架
2. 启用多进程模式：--parallel true
3. 对输入数据进行预处理和优化
4. 考虑使用内存映射文件处理中间结果

社区和支持

• GitHub Issues: 报告 bug 和功能请求
• 文档: 完整的文档在 docs/ 目录下
• 示例: 查看 examples/ 目录获取示例用法