battery-qv-plot

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.