# Numeric Distribution Check

字段分布校验工具。读取结构化数据文件（CSV、TSV、Excel等），按模式检查数值字段统计特征或分类字段频率分布是否合理。...

- Repository: https://github.com/cas-bigdatalab/piflow (541 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-10-23
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add cas-bigdatalab/piflow --skill numeric_distribution_check -g -a claude-code -y`
Codex: `npx skills add cas-bigdatalab/piflow --skill numeric_distribution_check -g -a codex -y`
Cursor: `npx skills add cas-bigdatalab/piflow --skill numeric_distribution_check -g -a cursor -y`
Gemini CLI: `npx skills add cas-bigdatalab/piflow --skill numeric_distribution_check -g -a gemini-cli -y`

## Description

字段分布校验工具。读取结构化数据文件（CSV、TSV、Excel等），按模式检查数值字段统计特征或分类字段频率分布是否合理。 数值模式用于检查均值、标准差、中位数、分位数等统计量；分类模式用于检查类别数上限和单类占比是否异常。 当用户提到分布校验、统计特征验证、类别频率检查、类别倾斜检测等需求时使用此skill。 即使用户没有明确说出"分布校验"，只要任务涉及验证字段整体分布是否偏移或失衡，就应该使用此skill。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# numeric_distribution_check 字段分布校验Skill

## 功能概述

本skill用于在**表级别**检查字段的整体分布是否合理，包含两种模式：

### 数值模式（numeric）
- 计算数值字段的统计特征
- 支持均值、标准差、中位数、最小值、最大值、25%分位数、75%分位数
- 任一统计量超出约束范围时，整表标记为不通过

### 分类模式（categorical）
- 统计分类字段的类别数和类别占比
- 检查类别数是否超过 `max_categories`
- 检查单类占比是否超过 `max_single_ratio`
- 类别数超限时整表标记；单类占比超限时仅标记该类别对应的行

## 触发条件

当用户请求以下任务时，应使用此skill：
- 分布校验
- 统计特征验证
- 均值/标准差检查
- 数值分布偏移检测
- 类别频率检查
- 分类分布检查
- 类别倾斜检测
- 数据平衡性分析

## 处理逻辑

1. 读取输入数据表
2. 根据 `mode` 选择校验路径：
   - `numeric`：提取 `value_field` 的有效数值，计算统计量并与 `stat_constraints` 比较
   - `categorical`：统计 `category_field` 的类别频次和占比，检查 `max_categories` 与 `max_single_ratio`
3. 若任一约束超限，则在 `mark_field_name` 列标记 `qc_mark`
4. 输出统计摘要和校验结果

## 支持的文件格式

- CSV (.csv)
- TSV (.tsv)
- Excel (.xls, .xlsx)
- SPSS (.sav)

## 使用方法

### 步骤1：获取用户输入输出路径及参数

向用户确认：
1. 输入文件路径（需要校验的文件）
2. 输出文件路径（校验结果文件）
3. 校验模式（numeric 或 categorical）
4. 数值字段名与统计约束，或分类字段名与类别阈值
5. 质控标识

### 步骤2：执行字段分布校验脚本

在 `scripts/` 目录下找到 `numeric_distribution_check.py`，使用Python执行：

数值模式：

```bash
python scripts/numeric_distribution_check.py \
    --input_path data.csv \
    --output_path checked.csv \
    --mode numeric \
    --value_field "score" \
    --stat_constraints "mean,40,60 std,0,20" \
    --qc_mark QC0029
```

分类模式：

```bash
python scripts/numeric_distribution_check.py \
    --input_path data.csv \
    --output_path checked.csv \
    --mode categorical \
    --category_field "category" \
    --max_categories 20 \
    --max_single_ratio 0.5 \
    --qc_mark QC0029
```

### 步骤3：返回结果

脚本执行完成后，告知用户：
- 实际统计值或类别分布概况
- 哪些约束超出范围
- 是否整表标记，或仅标记单类倾斜行

## 参数说明

The rest: https://github.com/cas-bigdatalab/piflow/blob/HEAD/workspace/skills/numeric_distribution_check/SKILL.md