battery-qv-plot - SKILL.md Agent Skill

name: battery-qv-plot description: Plot charge Q-V curves (voltage vs charge capacity) for battery cycling data with cycle-mapped colorbar. Supports pkl, csv, parquet, xlsx formats. Use when visualizing battery Q-V curves, voltage-capacity plots, charge capacity evolution, or cycle aging visualization.

Battery Charge Q-V Curve Visualization

Overview

绘制电池循环数据的充电 Q-V 曲线（电压 vs 充电容量），使用 colorbar 映射不同循环编号，直观展示容量随循环的演变。

Features

支持多种输入格式：pkl、csv、parquet、xlsx
仅绘制充电曲线
Blues colormap + colorbar 映射循环编号
3-sigma 异常循环自动过滤
出版级图片质量（dpi=300）

Plot Style

figsize=(3, 2)，dpi=300
Blues colormap，colorbar 无刻度
简洁的坐标轴标签
容量增量模式（每个循环相对于自身起点）

Workflow

1. 加载数据（pkl / csv / parquet / xlsx）
2. 提取每个循环的电压和充电容量数据
3. 3-sigma 过滤异常循环（基于最大充电容量）
4. 计算容量增量（Q - Q[0]）
5. 绘制 Q-V 曲线 + colorbar
6. 保存图片

Data Format Support

PKL（推荐，来自 battery-data-preprocess skill）

{
    'cell_id': str,
    'cycle_data': [
        {
            'cycle_number': int,
            'voltage_in_V': array,
            'current_in_A': array,
            'charge_capacity_in_Ah': array,
            ...
        },
        ...
    ]
}

CSV / Parquet / XLSX

支持两种数据路径：

路径 1（标准）：数据包含 cycle + charge capacity 列 → 直接 groupby 读取。

路径 2（Fallback）：数据只有 voltage + current + time → 自动检测循环（电流符号变化 / SOC 谷值）+ 电流积分计算容量（∫I dt）。同时自动分离 RPT 数据。

自动检测列名模式：

Role	Known Names
voltage	`Ecell/V`, `Voltage(V)`, `Voltage (V)`, `voltage (V)`, `voltage`, `V(V)`
charge_cap	`Q charge/mA.h` (÷1000), `Charge_Capacity (Ah)`, `charge_capacity`, `Qc`
cycle	`cycle number`, `Cycle_Index`, `cycle_index`, `cycle`
current	`current (A)`, `Current(A)`, `Current (A)`, `<I>/mA` (÷1000), `Current (mA)` (÷1000), `I`
timestamp	`time_stamp`, `Time`, `time`, `Test_Time (s)`, `time/s` 等
soc	`soc`, `SOC`, `State_of_Charge`
rpt	`rpt`, `RPT`, `test_type`

Manual Column Specification

当列名自动检测失败时，可手动指定列名和单位换算系数（col_name:scale）：

python scripts/plot_qv_curves.py \
  --input data.csv \
  --voltage_col "U_mV:0.001" \
  --charge_cap_col "Cap_mAh:0.001" \
  --cycle_col "Cycle"

# 对于只有 voltage + current 的原始数据
python scripts/plot_qv_curves.py \
  --input raw_data.parquet \
  --current_col "I_mA:0.001"

Usage

python scripts/plot_qv_curves.py \
  --input cell.pkl \
  --output qv_curve.png

# 默认自动裁剪到 min_voltage ~ max_voltage - 0.1
# 指定电压片段
python scripts/plot_qv_curves.py \
  --input cell.pkl \
  --vrange 3.0,3.8

# 画完整电压范围
python scripts/plot_qv_curves.py \
  --input cell.pkl \
  --vrange full

See reference.md for full CLI parameters. See examples.md for usage examples.