name: data-profiler description: > 数据探查与数据字典生成。触发条件: (1) 用户提供新的 CSV/Excel 数据文件, (2) 说"探查数据"/"数据画像"/"data profile"/"生成数据字典", (3) 在分析之前需要全面了解数据结构。 核心能力: 自动生成数据字典、检测变量层级关系、评估缺失模式、 定义分析人群，为后续所有分析消除"盲猜列名"和"NaN崩溃"的风险。 allowed-tools: Read, Write, Edit, Glob, Grep, Bash

Data Profiler - 数据探查与字典生成

核心理念

分析之前，先认识数据。

P-A 论文中遇到的4次被动人工干预中有3次源于"不了解数据"：

• 列名猜错 (follow_up_days vs time_hf_readm)
• 变量层级不清 (tcm_syndrome 43种 vs syndrome_group 4组)
• 缺失值未预检 → NaN 导致模型崩溃

本 Skill 在任何分析之前运行，一次性解决所有这些问题。

触发条件

1. 用户提供新的数据文件（CSV/Excel/SPSS/Stata）
2. 用户说"探查数据"/"数据画像"/"data profile"/"数据字典"
3. paper-pipeline 编排器在 Step 1 自动调用
4. 用户说"看看这个数据长什么样"/"有什么变量"

输入

• 必需: 数据文件路径
• 可选: 研究问题描述（帮助标注关键变量）
• 可选: 已有的变量说明文档

输出

• data_dictionary.md — 完整数据字典
• data_profile_report.md — 数据质量报告
• analysis_populations.md — 分析人群定义与流程

探查流程

Phase 1: 基础结构扫描

目标: 30秒内了解数据的基本面貌。

import pandas as pd
import numpy as np

def basic_scan(file_path):
    """基础结构扫描"""
    # 1. 读取数据
    if file_path.endswith('.csv'):
        df = pd.read_csv(file_path)
    elif file_path.endswith(('.xlsx', '.xls')):
        df = pd.read_excel(file_path)
    elif file_path.endswith('.sav'):
        df = pd.read_spss(file_path)
    elif file_path.endswith('.dta'):
        df = pd.read_stata(file_path)

    # 2. 基本信息
    info = {
        'rows': len(df),
        'columns': len(df.columns),
        'memory_mb': df.memory_usage(deep=True).sum() / 1024**2,
        'duplicated_rows': df.duplicated().sum(),
    }

    # 3. 变量分类
    numeric_cols = df.select_dtypes(include=[np.number]).columns.tolist()
    categorical_cols = df.select_dtypes(include=['object', 'category']).columns.tolist()
    datetime_cols = df.select_dtypes(include=['datetime64']).columns.tolist()
    boolean_cols = df.select_dtypes(include=['bool']).columns.tolist()

    # 4. 自动检测伪分类变量（数值型但唯一值<=10）
    pseudo_categorical = []
    for col in numeric_cols:
        if df[col].nunique() <= 10:
            pseudo_categorical.append(col)

    return df, info, {
        'numeric': numeric_cols,
        'categorical': categorical_cols,
        'datetime': datetime_cols,
        'boolean': boolean_cols,
        'pseudo_categorical': pseudo_categorical,
    }

输出格式:

## 数据概览

| 指标 | 值 |
|------|-----|
| 行数 | 1,395 |
| 列数 | 94 |
| 内存占用 | 12.3 MB |
| 重复行 | 0 |
| 数值变量 | 60 |
| 分类变量 | 34 |
| 伪分类变量 | 15 (数值型但≤10个唯一值) |

Phase 2: 数据字典生成

目标: 为每个变量生成完整的描述信息。

对每个变量提取：

变量名推断规则:

COMMON_PATTERNS = {
    # 时间相关
    r'(?i)(time|duration|days|months|years|follow.?up|fu)': '时间/随访',
    r'(?i)(date|dt|dob)': '日期',
    # 结局变量
    r'(?i)(event|outcome|death|readm|recur|survival)': '结局事件',
    r'(?i)(status|censor)': '删失状态',
    # 人口学
    r'(?i)(age|sex|gender|bmi|height|weight)': '人口学',
    # 实验室
    r'(?i)(bnp|nt.?pro|creat|sodium|potassium|hemoglobin|hb|albumin)': '实验室指标',
    # 用药
    r'(?i)(med|drug|rx|acei|arb|bb|mra|diuretic|raas)': '用药',
    # 分类/分组
    r'(?i)(group|cluster|class|type|category|syndrome|stage)': '分组变量',
    # 评分
    r'(?i)(score|scale|index|grade)': '评分/量表',
    # 影像
    r'(?i)(ef|lvef|lv|rv|la|ra|ivs|lvpw)': '心脏超声',
}

Phase 3: 变量层级关系检测

目标: 自动发现"父子"变量关系，避免 P-A 中 tcm_syndrome vs syndrome_group 的混淆。

def detect_hierarchy(df):
    """检测分类变量间的层级关系"""
    cat_cols = df.select_dtypes(include=['object', 'category']).columns
    # 加上伪分类变量
    for col in df.select_dtypes(include=[np.number]).columns:
        if df[col].nunique() <= 20:
            cat_cols = cat_cols.append(pd.Index([col]))

    hierarchies = []
    for i, col_a in enumerate(cat_cols):
        for col_b in cat_cols[i+1:]:
            # 检查 A 是否是 B 的细分
            # 即：每个 A 值只映射到一个 B 值
            mapping = df.groupby(col_a)[col_b].nunique()
            if mapping.max() == 1 and df[col_a].nunique() > df[col_b].nunique():
                hierarchies.append({
                    'child': col_a,
                    'parent': col_b,
                    'child_levels': df[col_a].nunique(),
                    'parent_levels': df[col_b].nunique(),
                })
            # 反向检查
            mapping_rev = df.groupby(col_b)[col_a].nunique()
            if mapping_rev.max() == 1 and df[col_b].nunique() > df[col_a].nunique():
                hierarchies.append({
                    'child': col_b,
                    'parent': col_a,
                    'child_levels': df[col_b].nunique(),
                    'parent_levels': df[col_a].nunique(),
                })

    return hierarchies

输出格式:

## 变量层级关系

| 细分变量 (子) | 聚合变量 (父) | 子级别数 | 父级别数 | 关系 |
|--------------|--------------|---------|---------|------|
| tcm_syndrome | syndrome_group | 43 | 4 | 43种证型 → 4大证型组 |
| diagnosis_detail | diagnosis_main | 28 | 5 | 28种诊断 → 5大类 |

**建议**: 在生存分析/回归模型中使用 `syndrome_group` (4组)，而非 `tcm_syndrome` (43种)。

Phase 4: 缺失模式分析

目标: 全面了解缺失情况，预防 NaN 崩溃。

def missing_analysis(df):
    """缺失模式分析"""
    # 1. 变量级缺失
    missing_by_var = df.isnull().sum().sort_values(ascending=False)
    missing_pct = (missing_by_var / len(df) * 100).round(1)

    # 2. 行级缺失
    row_missing = df.isnull().sum(axis=1)
    complete_cases = (row_missing == 0).sum()

    # 3. 缺失模式（哪些变量一起缺失）
    missing_cols = missing_by_var[missing_by_var > 0].index.tolist()
    if len(missing_cols) >= 2:
        # 检查共缺失率
        co_missing = {}
        for i, col_a in enumerate(missing_cols[:10]):
            for col_b in missing_cols[i+1:10]:
                both_missing = (df[col_a].isnull() & df[col_b].isnull()).sum()
                if both_missing > 0:
                    co_missing[f"{col_a} & {col_b}"] = both_missing

    # 4. 缺失率分层建议
    strategies = {}
    for col in missing_cols:
        pct = missing_pct[col]
        if pct < 5:
            strategies[col] = "列表删除 (listwise) — 影响小"
        elif pct < 20:
            strategies[col] = "多重填补 (MICE) 或中位数填补"
        else:
            strategies[col] = "需检查 MCAR/MAR，考虑删除该变量"

    return {
        'by_variable': missing_pct[missing_pct > 0],
        'complete_cases': complete_cases,
        'complete_rate': complete_cases / len(df) * 100,
        'strategies': strategies,
    }

输出格式:

## 缺失模式分析

### 概览
| 指标 | 值 |
|------|-----|
| 完全病例数 | 766 / 895 (85.6%) |
| 有缺失的变量数 | 12 / 94 |
| 最高缺失率 | creatinine_dc (8.3%) |

### 缺失变量详情
| 变量 | 缺失数 | 缺失率 | 建议处理 |
|------|--------|--------|---------|
| creatinine_dc | 74 | 8.3% | 中位数填补 |
| sodium_dc | 45 | 5.0% | 中位数填补 |
| bnp_dc | 32 | 3.6% | 列表删除 |

### 对分析的影响
- **完全病例分析**: N=766 (损失14.4%)
- **中位数填补后**: N=895 (损失0%)
- **建议**: 完全病例为主分析，填补为敏感性分析

Phase 5: 分析人群定义

目标: 明确每个可能的分析子集及其精确 N。

def define_populations(df, criteria):
    """定义分析人群

    criteria 示例:
    {
        'total': {},  # 全部
        'has_ef': {'ef': 'notna'},
        'has_followup': {'time_hf_readm': 'notna'},
        'complete_case': {'creatinine_dc': 'notna', 'sodium_dc': 'notna', ...},
    }
    """
    populations = {}
    for name, filters in criteria.items():
        subset = df.copy()
        for col, condition in filters.items():
            if condition == 'notna':
                subset = subset[subset[col].notna()]
            elif condition == 'notzero':
                subset = subset[subset[col] != 0]
            elif isinstance(condition, tuple):
                subset = subset[subset[col].between(*condition)]
        populations[name] = {
            'n': len(subset),
            'filters': filters,
        }
    return populations

输出格式:

## 分析人群定义

| 人群 | 条件 | N | 用途 |
|------|------|---|------|
| 全部入院 | 无 | 1,395 | 人口学描述 |
| 四大证型 | syndrome_group ∈ {QDBS,YQD,YDFR,HKYD} | 993 | Table 1, 组间比较 |
| 有随访数据 | time_hf_readm > 0 | 895 | KM生存分析 |
| 完全病例 | 所有协变量非缺失 | 766 | Cox回归主分析 |
| HFpEF亚组 | ef ≥ 50 | 522 | 敏感性分析 |

**CRITICAL**: 在稿件中报告结果时，务必注明每个分析使用的人群和对应的 N。

数据字典输出格式

# Data Dictionary

**Dataset**: analysis_ready.csv
**Generated**: 2026-02-26
**Rows**: 1,395 | **Columns**: 94

---

## ID / 索引变量
| 变量名 | 含义 | 类型 | 唯一值 | 备注 |
|--------|------|------|--------|------|
| patient_id | 患者ID | int | 1395 | 主键 |

## 人口学变量
| 变量名 | 含义 | 类型 | 缺失率 | 统计摘要 |
|--------|------|------|--------|---------|
| age | 年龄 | float | 0% | 71.2 ± 12.3 (23-99) |
| sex | 性别 | binary(0/1) | 0% | 男 58.4% |

## 分组变量
| 变量名 | 含义 | 类型 | 级别数 | 层级关系 |
|--------|------|------|--------|---------|
| tcm_syndrome | 中医证型(细) | object | 43 | → syndrome_group |
| syndrome_group | 中医证型组(粗) | object | 4 | QDBS/YQD/YDFR/HKYD |

## 结局变量
| 变量名 | 含义 | 类型 | 缺失率 | 统计摘要 |
|--------|------|------|--------|---------|
| readmission_hf | 心衰再入院 | binary(0/1) | 0% | 事件率 15.2% |
| time_hf_readm | 随访时间(天) | float | 35.8% | 365 ± 180 |

...（按语义分组列出所有变量）

与其他 Skill 的协作

更新日志

• v1.0 (2026-02-26): 初始版本
  • 5阶段探查流程：基础扫描 → 数据字典 → 层级检测 → 缺失分析 → 人群定义
  • 从 P-A 论文经验中提炼的变量名推断规则和层级关系检测算法