data-analysis

数据分析技能

支持的输入数据类型

1. 表格形式的数据：csv、xlsx
2. 文本中包含的数据：docx、pdf、md
3. 图片中包含的数据：png、jpg

步骤一：数据读入与探查

为了防止 Token 溢出和执行环境卡死，智能体 严禁 直接打印全量数据或将其加载到 Prompt 上下文中，只允许将必要的数据概要加载进上下文。

1. 数据读入与保存

对不同类型的数据应使用不同的读取方法：

• csv: 直接使用pandas库读取
• xlsx: 使用pandas库或 \xlsx 工具读取
• docx: 使用 \docx 工具读取，并将其中待分析的目标数据提取出来保存为csv文件
• pdf: 使用 \pdf 工具读取，并将其中待分析的目标数据提取出来保存为csv文件
• md: 直接读取，并将其中待分析的目标数据提取出来保存为csv文件
• png、jpg: 使用视觉工具读取，并将其中待分析的目标数据提取出来保存为csv文件

2. 数据探查

在编写正式分析代码前，必须先执行一段轻量级的探查代码。将代码保存至工作空间。

原则：

只看样貌，不看全貌： 仅获取元数据和少量样本。

元数据优先： 必须获取列名（Columns）和数据类型（Dtypes）。

样本限制： 严格限制读取行数（推荐n=5）。

探查全部文件： 若有多份待分析的文件，需要对所有文件逐一探查，并检查文件间可能存在的关联，将具体关联方式保存为csv文档或md文件，供后续分析进行参考。

标准探查代码模式 (Python示例):

import pandas as pd

# 设定文件路径
file_path = 'target_data.csv'

try:
    # 1. 仅读取前5行，避免加载大文件占用内存
    # 注意：对于非CSV文件 (如 Parquet, Excel)，使用相应的 read_ function 并配合 head()
    if file_path.endswith('.csv'):
        df_preview = pd.read_csv(file_path, nrows=5)
    elif file_path.endswith('.parquet'):
        df_preview = pd.read_parquet(file_path).head(5)
    elif file_path.endswith(('.xls', '.xlsx')):
        df_preview = pd.read_excel(file_path, nrows=5)
    
    # 2. 输出关键元数据供智能体思考
    print("=== 数据预览 (前5行) ===")
    print(df_preview.to_markdown(index=False))
    
    print("\n=== 列信息与类型 ===")
    print(df_preview.info())
    
except Exception as e:
    print(f"摄入错误: {e}")

3. 编码与格式自适应

编码回退：如果读取失败，尝试 `encoding='gbk'` 或 `encoding='latin1'`。
分隔符：如果数据挤在一列，尝试 sep=';' 或 sep='\t'。

步骤二：数据质量检查

在进行任何分析前，必须先“体检”。这能避免“垃圾进，垃圾出”。检查结果需放在最后的报告中。

以下是详细的检查清单：

1. 完整性

检查数据是否存在缺失，这会直接影响统计的偏差。

缺失值：

检查字段中 NULL 、 NaN 或空字符串的比例。

• 注意“伪缺失值”，例如用 -1 、 0 、 9999 或 "Unknown" 来代替缺失值的情况。

记录缺失：

• 数据量是否符合预期？（例如：昨天的日志应该有 100万条，实际只有 20万条）。
• 时间序列是否连续？（例如：是否缺失了某几天的交易数据）。

截断:

文本字段是否因为字符长度限制被截断（例如 JSON 字符串不完整）。

2. 唯一性

检查数据是否存在重复，这会导致指标被夸大。

完全重复: 检查是否存在完全相同的行。

主键重复: ID 字段是否唯一？（例如：同一个 UserID 不应该出现在用户表的两行中）。

业务实体重复: 同一个业务对象是否因为大小写不同、空格不同而被记录了多次（例如 "Apple"和 "apple" ）。

3. 准确性与有效性

检查数据是否符合定义的格式和现实世界的物理规则。

数据类型:

• 数值字段里是否混入了字符串？
• 日期字段是否真的是日期格式？

取值范围:

• 数值是否在合理范围内？（例如：年龄不应为负数或超过 150；折扣率不应大于 100% ）。
• 概率值是否在 0 到 1 之间？

4. 一致性

检查数据在不同维度或来源上是否统一。

单位统一: 距离是米还是千米？金额是元还是分？
枚举值统一: 同样的含义是否有多种表达？（例如： "Beijing" , "BJ" , "北京" 应该标准化为同一种）。
跨表一致性: 两个表中相同含义的字段，数据是否对得上？（例如：订单表中的总金额是否等于详情表中各商品金额之和）。

5. 关联性

若多份文件间存在关联关系，检查关系是否断裂。
外键约束: 事实表中的 ID 是否都能在维度表中找到？（例如：订单表里的 product_id ，在商品表中是否存在？如果不存在，就是“孤儿数据”）。

代码示例：

import pandas as pd
# --- 1. 完整性检查 (Completeness) ---
for col in COLS_CHECK_MISSING:
    # 检查 NULL/NaN
    missing_count = df[col].isnull().sum()
    # 检查空字符串 (如果是字符串列)
    empty_str_count = (df[col] == '').sum() if df[col].dtype == 'object' else 0
    total_missing = missing_count + empty_str_count
    if total_missing > 0:
        print(f"  -> 警告: 列 '{col}' 存在 {total_missing} 条缺失数据")
    else:
        print(f"  -> 通过: 列 '{col}' 无缺失")
# --- 2. 唯一性检查 (Uniqueness) ---
if df[COL_PRIMARY_KEY].duplicated().any():
    duplicate_count = df[COL_PRIMARY_KEY].duplicated().sum()
    print(f"  -> 警告: 主键 '{COL_PRIMARY_KEY}' 发现 {duplicate_count} 条重复记录")
    # 可选：查看重复样本
    # print(df[df[COL_PRIMARY_KEY].duplicated(keep=False)])
else:
    print(f"  -> 通过: 主键唯一")
# --- 3. 准确性检查 (Accuracy) ---
# 过滤出不符合规则的行
invalid_rows = df[df[COL_NUMERIC] < MIN_VALUE_THRESHOLD]
if not invalid_rows.empty:
    print(f"  -> 警告: 发现 {len(invalid_rows)} 条数据小于最小值 {MIN_VALUE_THRESHOLD}")
else:
    print(f"  -> 通过: 数值范围正常")
# --- 4. 一致性检查 (Consistency) ---
# 找出不在标准列表中的值
# fillna(False) 是为了处理空值情况，避免报错
invalid_mask = ~df[COL_CATEGORY].isin(VALID_CATEGORIES) & df[COL_CATEGORY].notnull()
invalid_cats = df.loc[invalid_mask, COL_CATEGORY].unique()
if len(invalid_cats) > 0:
    print(f"  -> 警告: 列 '{COL_CATEGORY}' 包含非标准值: {invalid_cats}")
else:
    print(f"  -> 通过: 枚举值一致")
# --- 5. 关联性检查 (Integrity) ---
# 注意：此步需要有一个参考表 (ref_df)
try:
    # 找出在当前表中存在，但在参考表(ref_df)中找不到的 ID
    # 同样排除了当前表外键为空的情况
    orphan_mask = ~df[COL_FOREIGN_KEY].isin(ref_df[COL_REF_KEY]) & df[COL_FOREIGN_KEY].notnull()
    orphan_count = orphan_mask.sum()
    if orphan_count > 0:
        print(f"  -> 警告: 发现 {orphan_count} 条“孤儿数据” (在维表中找不到对应记录)")
    else:
        print(f"  -> 通过: 外键关联完整")
except NameError:
    print("  -> 跳过: 未定义 ref_df (维表)，无法进行关联检查")

步骤三：确定工作流程

根据任务需求确定具体的工作流程，优先使用用户指定的分析方法，不要使用与任务无关的分析方法。工作流程一般包含数据处理、分析和可视化呈现。

核心分析方法

1. 统计分析

• 描述性统计： 均值、中位数、标准差、四分位数、百分位数
• 推断性统计： 假设检验、置信区间、P值
• 相关性分析： 皮尔逊 (Pearson)、斯皮尔曼 (Spearman)、肯德尔 (Kendall)、点二列 (Point-biserial) 相关系数​
• 分布分析： 正态性、偏度、峰度、Q-Q图
• 高级统计检验： 方差分析 (ANOVA)、t检验、卡方检验、非参数检验

2. 模式发现

• 趋势分析与时间序列分解
• 季节性模式检测与预测
• 聚类与细分：K-means、层次聚类、DBSCAN
• 关联规则挖掘与购物篮分析
• 特征工程与特征选择
• 降维技术：PCA (主成分分析)、t-SNE、UMAP

3. 商业智能

• KPI 分析与仪表板设计
• 客户细分与画像
• 购物篮分析与推荐系统
• 流失预测与客户生命周期价值 (CLV)
• A/B 测试与实验设计
• ROI (投资回报率) 分析与业务影响评估
• 摘要与可落地的行动建议

4. 探索性技术

• 单变量分析：分布、统计量、可视化
• 双变量分析：相关性、对比、关系
• 多变量分析：回归、聚类、分类
• 时间序列分析：趋势、季节性、预测
• 类别数据分析：频数、列联表、关联性
• 空间分析与地理模式
• 文本分析与自然语言处理 (NLP)

核心可视化方法

目标是通过深思熟虑的视觉设计，让数据变得易于理解、富有洞察力。每一个可视化都应该清晰明了，并帮助使用者做出更好的决策。

针对数值型数据

• 分布： 直方图、箱线图、小提琴图、密度图
• 比较： 条形图、折线图、散点图
• 关系： 散点图、相关性矩阵、热力图
• 构成： 堆叠条形图、饼图、树状图
• 趋势： 折线图、面积图、移动平均图

针对分类型数据

• 频率： 条形图、饼图、环形图（甜甜圈图）
• 比较： 分组条形图、堆叠条形图
• 关系： 热力图、马赛克图、平行集合图
• 构成： 树状图、旭日图

针对时间序列数据

• 趋势： 折线图、面积图、平滑曲线
• 季节性： 季节性分解、热力图
• 比较： 多重折线图、分面图（Faceted plots）
• 分布： 基于时间的箱线图、小提琴图

高级技巧

• 交互式仪表盘: 创建多面板仪表板、添加筛选器和控件

• 动画可视化: 展示随时间的变化、阐释复杂过程

报告撰写

根据用户的要求确定所需的报告类型，若无明确要求只需给出一份md格式的数据分析报告。

报告类型

• 执行摘要： 分析过程文档，为使用者提供任务执行的全部过程
• 商业数据分析报告： 数据驱动的商业洞察，对数据分析的结果进行总结和剖析
• 仪表盘文档： 交互式图表说明

报告格式

markdown、pdf、docx

报告风格和内容

• 准确性: 细致、严谨、语言清晰，确保所有统计数据和事实均正确无误
• 逻辑性: 从数据到洞见的逻辑发展
• 专业性: 理解关键发现和统计意义，识别数据中的模式和趋势
• 基于数据: 围绕数据发现构建有深度的叙述
• 可执行的见解: 明确的建议和后续步骤
• 视觉集成： 如果是pdf或docx类型的报告，需要插入合适的图表，并确保视觉与文本的一致性，设计合适的布局
• 可读性： 不要使用类似“行业黑话”的难懂的词汇，避免不必要的细节，措辞简单易懂且书面化。

步骤四：规范代码生成与执行

プログラミング言語

• Python: Pandas, NumPy, Scikit-learn, Matplotlib, Seaborn, Plotly, TensorFlow, PyTorch
• R: Tidyverse, ggplot2, dplyr, caret, shiny, data.table​
• SQL: PostgreSQL, MySQL, SQLite, BigQuery, Redshift, Snowflake
• JavaScript: D3.js, Plotly.js, Chart.js, TensorFlow.js, Node.js

一般的な技術スタック（Python）

• コア処理: `pandas`, `numpy
• 統計とマイニング: `scipy`, `sklearn`（必要に応じて）
• 可視化: `matplotlib`, `seaborn`（静的）；`plotly`（インタラクティブ）
• ユーティリティライブラリ: `tabulate`（出力の整形）、`\xlsx`ツール、`\pdf`ツール、`\docx`ツール

コード生成の手順

第1段階：要件分析

• 前の手順で決定した分析フローに基づき、分析目標と出力要件を明確にします
• 適切なプログラミング言語を選択します（明確な指定がない場合は、デフォルトでPythonを使用します）
• ライブラリとフレームワークを選択します
• パフォーマンスと拡張性の要件を考慮します

第2段階：構造設計

• モジュール化されたコード構造を設計し、複雑なタスクを小さく単一目的の関数に分割します
• 複雑なタスクを管理しやすい機能に分割します
• 再利用性と保守性を計画します
• メモリ管理に注意します：大規模なデータセットを効率的に処理します

第3段階：実装

• 簡潔で効率的なコードを記述します
• 適切なエラー処理を加えます
• 明確で簡潔なコメントを追加します
• コードを実行して結果を取得します

エラー処理

• データ読み込みエラー：ファイルの欠落、形式の問題、エンコードの問題に対処します。
• メモリの問題：チャンク処理（chunking）またはデータサンプリングを実施します。
• パフォーマンスの問題：アルゴリズムを最適化し、キャッシュと並列処理を使用します。
• 依存関係の問題：ライブラリのバージョンを確認し、フォールバックの選択肢を用意します。

ステップ5：結果の検証と出力

結果をユーザーに提示する前に、以下のセルフチェックリストを実行する必要があります：

完全性チェック：

• すべての結果ファイル（.png/.html/.xlsx/.pdfなど）が正常に生成され、ワークスペースに存在することを確認しましたか？
• 重要な計算結果（KPI、統計量など）が空でなく、妥当な値であることを確認しましたか？
• 出力ファイル（CSVなど）にデータが含まれ、ヘッダーが正しいことを確認しましたか？
• ユーザーが必要とするすべての結果ファイルが完全に生成されていることを確認しましたか？

形式の一貫性：

• グラフにタイトル、軸ラベル、凡例がありますか？
• レポートのフォントは統一され、見出しの階層は明確ですか？
• レポート内の画像は適切な位置にあり、明確なラベルと説明が付いていますか？

品質ゲートを通過したことを確認してから、納品できます。

例

例 1：基本的な販売データの傾向分析（構造化データ）

ユーザーの指示： 「sales_2023.csvを分析してください。下半期の販売傾向を見たいです。また、データには返金された注文があるようなので、忘れずに処理してください。」

エージェントの実行フロー：

1. ステップ1（データの調査）： pd.read_csv('sales_2023.csv', nrows=5)を実行します。 確認事項： 列にはdate、amount、status、product_idが含まれています。dateは文字列形式のため、変換が必要です。

2. ステップ2（品質チェック）： 完全性： amountに欠損値がないか確認します。 一貫性： statusフィールドを確認し、"Refund"と"Completed"が含まれていることを確認します。 対応： status == 'Refund'の行を除外し、完了済みの注文のみを残します。

3. ステップ3と4（分析と実行）： 処理： dateをdatetimeオブジェクトに変換し、amountを月単位で集計します。 コード： Pandasを使用してresample('M').sum()を実行します。 可視化： 折れ線グラフsales_trend.pngを生成し、ピークの月を示します。

4. ステップ5（納品）： 簡易レポートと折れ線グラフを出力します：「2023年下半期の売上は11月にピークを迎えました（大型セールの影響）。45件の返金記録を除外した後の総売上はX元です。」

例 2：ファイルをまたいだ関連分析（マルチモーダル／複雑なシナリオ）

ユーザーの指示： 「製品カテゴリの定義ファイルcategories.xlsxと、最近のユーザーフィードバックログfeedback.pdfがあります。どの製品カテゴリで否定的なフィードバックが最も多いか分析してください。」

エージェントの実行フロー：

1. ステップ1（データの読み込み）： categories.xlsxの場合：Pandasを使用して先頭5行を読み込み、product_idとcategory_nameが含まれていることを確認します。 feedback.pdfの場合：\pdfツールを呼び出してテキストを抽出し、LLMを通じてCSV形式（product_id、sentiment、contentを含む）に構造化して解析し、temp_feedback_parsed.csvとして保存します。

2. ステップ2（関連性のチェック）： 調査： temp_feedback_parsed.csvのサンプルを読み込みます。 関連性： フィードバック表のproduct_idがすべてcategories.xlsxに存在するか確認します。 警告： カテゴリ表に存在しないproduct_idが3件見つかったため、「不明なカテゴリ」としてマークします。

3. ステップ3と4（分析と実行）： ロジック： 2つの表をproduct_idに基づいてマージします。 フィルタリング： sentiment == 'Negative'のレコードを抽出します。 集計： category_nameごとにvalue_counts()を実行します。 可視化： Seabornを使用して横棒グラフnegative_feedback_by_category.pngを作成します。

4. ステップ5（納品）： Markdownレポートを生成し、可視化画像を出力します。「電子製品」カテゴリの否定的なフィードバックが最も多く、その多くは「バッテリー駆動時間」の問題に関するものです（テキストクラスタリングに基づく発見）。