Metadata-Version: 2.4
Name: ghealth-tools
Version: 0.4.20
Summary: PPG数据分析命令行工具库
Author: health_tools
License: MIT
Project-URL: Homepage, https://github.com/XiaoPb/health_tools
Keywords: ppg,health,data-analysis,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: rich>=13.0.0
Requires-Dist: chardet>=5.0.0
Requires-Dist: tqdm>=4.65.0
Provides-Extra: ui
Requires-Dist: streamlit>=1.30.0; extra == "ui"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black==24.10.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# GHealth Tools

PPG（光电容积脉搏波）数据分析命令行工具库，支持数据转换、可视化、分类等功能。

## 安装

```bash
pip install ghealth-tools
```

或从源码安装：

```bash
git clone https://github.com/yourusername/health_tools.git
cd health_tools
pip install -e .
```

## 快速开始

```bash
# 查看帮助
ghealth_tool --help

# 查看版本
ghealth_tool --version
```

## 命令

### parse - 日志解析

将原始日志文件解析为CSV格式。

```bash
# 使用解析规则文件
ghealth_tool parse -i raw.log -o output.csv -r parse/gh3220.yaml

# 使用芯片规则
ghealth_tool parse -i raw.log -o output.csv --chip gh3220

# 批量处理目录
ghealth_tool parse -i logs/ -o output/ -r parse/default.yaml -v
```

### plot - 数据可视化

绘制PPG数据的时域/频域图。

```bash
# 绘制时域和频域图
ghealth_tool plot -i data.csv -o plots/ --type both --sample-rate 100

# 仅绘制时域图
ghealth_tool plot -i data.csv -o plots/ --type time --channels red,ir

# 指定窗口和重叠率
ghealth_tool plot -i data.csv -o plots/ --window 10 --overlap 0.75
```

### classify - 数据分类

根据规则对数据进行分类保存。

```bash
# 使用分类规则
ghealth_tool classify -i data/ -o classified/ -r classify/default.yaml

# 生成分类报告
ghealth_tool classify -i data/ -o classified/ -r classify/default.yaml --report

# 移动文件而非复制
ghealth_tool classify -i data/ -o classified/ -r classify/default.yaml --move
```

### convert - 格式转换

CSV格式转换（紧凑型↔展开型，芯片特定格式）。

```bash
# 使用转换规则
ghealth_tool cv -i input.csv -o output.csv -r convert/my_rule.yaml

# 合并多个文件
ghealth_tool cv -i data/ -o merged.csv -r convert/rule.yaml --merge

# 按大小分割
ghealth_tool cv -i large.csv -o split/ -r convert/rule.yaml --split 10000

# 生成规则模板
ghealth_tool convert --init-rule -c gh3220 -o my_convert_rule.yaml
```

### factory - 产测计算

计算 SNR/CTR/Noise，支持芯片规则自动提取增益和灯电流。

```bash
# 单文件计算
ghealth_tool fac -i data.csv -c gh3036_evk

# 目录批量计算
ghealth_tool fac -i data_dir/ -c gh3036_evk -v

# 指定增益和电流
ghealth_tool fac -i data.csv -c gh3036 --gain 10 --current 25.0

# 覆盖默认时长配置
ghealth_tool fac -i data.csv -c gh3036_evk --snr-cfg "5,5,60" --ctr-cfg "1,0,2"
```

### info - 信息查看

查看数据文件或规则文件信息。

```bash
# 查看CSV文件信息
ghealth_tool info data.csv --stats --preview 20

# 查看规则文件
ghealth_tool info rules/chip/gh3220.yaml --schema
```

### validate - 规则验证

验证YAML规则文件格式和内容。

```bash
# 验证规则文件
ghealth_tool validate rules/chip/gh3220.yaml

# 严格模式验证
ghealth_tool validate rules/parse/gh3220.yaml --strict
```

## 规则文件

### 芯片规则 (rules/chip/*.yaml)

定义CSV文件的格式和产测计算参数：

```yaml
version: "1.0"
chip: gh3220

csv:
  info_row: 1
  header_row: 2
  data_start_row: 3
  delimiter: ","
  encoding: "utf-8"

columns:
  - TimeStamp
  - FRAME_ID
  - CH{0-15}

factory_columns:         # 产测计算列
  - CH{0-15}

factory_config:          # 各指标独立时长配置
  sample_rate: 100
  snr:
    skip_head_seconds: 10
    skip_tail_seconds: 10
    min_duration_seconds: 90
  ctr:
    skip_head_seconds: 1
    skip_tail_seconds: 0
    min_duration_seconds: 2
  noise:
    skip_head_seconds: 2
    skip_tail_seconds: 0
    min_duration_seconds: 4

chip_info:
  adc_full_scale: 8388608
  adc_offset: 8388608
  adc_vref: 1.8
  tia_ratio: 2
```

### 解析规则 (rules/parse/*.yaml)

定义如何解析日志文件：

```yaml
version: "1.0"
description: "GH3220日志解析规则"

regex: '^\[(.+?)\]\s+GH3220:\s*(\d+),(\d+),(\d+),(\d+)$'

columns:
  - timestamp
  - red
  - ir
  - green
  - aux
```

### 分类规则 (rules/classify/*.yaml)

定义数据分类规则：

```yaml
version: "1.0"

filename:
  regex: '(\d{8})_(\w+)_(\w+)\.csv'
  fields:
    - date
    - subject
    - motion

data_columns:
  - name: motion
    source: filename
    match:
      supine: ["supine", "lie"]
      sit: ["sit", "sitting"]

structure:
  supine: ""
  sit: ""

rules:
  - target: "{motion}"
    use_filename: true
```

### 转换规则 (rules/convert/*.yaml)

定义CSV格式转换，支持列映射、前值填充、频率扩展：

```yaml
version: "1.0"
target_chip: gh3220

csv:
  info_row: 0            # 信息所在行（0=无）
  header_row: 1          # 列名所在行
  data_start_row: 2      # 数据开始行
  delimiter: ","

column_mapping:
  time: TimeStamp
  acc[0]: ACCX           # [] 为字面量列名
  rawdata{0-15}: CH{0-15}  # {} 展开为 rawdata0->CH0, rawdata1->CH1, ...

forward_fill:
  - polar_HR             # 0值用前一个非0值填充

expand_repeat:
  polar_HR: 25           # 每个值重复25次匹配采样率
```

## 列名展开语法

使用 `{start-end}` 进行范围展开，`[]` 保留为字面量：

```yaml
columns:
  - CH{0-15}             # 展开为 CH0, CH1, ..., CH15
  - ALGO{0-1}_CH{0-2}   # 多段展开: ALGO0_CH0, ALGO0_CH1, ..., ALGO1_CH2

column_mapping:
  rawdata[{0-1}]: Rawdata{0-1}  # rawdata[0]->Rawdata0, rawdata[1]->Rawdata1
  acc[0]: ACCX                   # acc[0] 是字面量列名
```

## 内置芯片规则

| 芯片 | 文件 | 描述 |
|------|------|------|
| GH3220 | `rules/chip/gh3220.yaml` | Goodix PPG传感器 |
| GH3036 | `rules/chip/gh3036.yaml` | Goodix健康传感器 |
| GH3036_EVK | `rules/chip/gh3036_evk.yaml` | GH3036 评估板 |

## 开发

### 环境设置

```bash
# 克隆仓库
git clone https://github.com/yourusername/health_tools.git
cd health_tools

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
.\venv\Scripts\activate  # Windows

# 安装开发依赖
pip install -e ".[dev]"
```

### 运行测试

```bash
pytest
```

### 代码格式化

```bash
black src/
ruff check src/
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！
