Guide: CSV Output¶

Export the data behind every BatteryProc plot to CSV files for further analysis.

BatteryProc can export all plotted data as comma-separated value (CSV) files. This is useful for importing data into spreadsheets, statistics packages, or custom scripts.

1. Quick Start¶

Generate CSVs alongside plots¶

batteryproc data.xlsx --csv

Generate CSVs only (skip plots, faster)¶

batteryproc data.xlsx --csv-only

Combine with other flags¶

batteryproc data.xlsx --csv --energy --derivative 1 10 50
batteryproc data/ -r --csv-only

Note: --csv and --csv-only are mutually exclusive — you cannot use both at once.

2. CSV File Naming¶

All CSV files follow the same naming convention as plots:

{file_stem}_{plot_type_suffix}.csv

For example, if the input file is BatteryA.xlsx:

Plot Type	CSV Filename
Capacity vs Cycle	`BatteryA_cap_v_cyc.csv`
Coulombic Efficiency vs Cycle	`BatteryA_ce_v_cyc.csv`
Capacity Retention vs Cycle	`BatteryA_retention_v_cyc.csv`
Energy vs Cycle	`BatteryA_ene_v_cyc.csv`
First Cycle Overview	`BatteryA_first_cyc.csv`
Voltage vs Time	`BatteryA_volt_v_time.csv`
dQ/dV	`BatteryA_dqdv.csv`
Capacity vs Voltage	`BatteryA_cap_v_volt.csv`

3. Column Definitions¶

Simple Cycle Metrics¶

Capacity vs Cycle (_cap_v_cyc.csv)

Column	Description
`Cycle Index`	Cycle number
`Charge_mAh/g`	Specific charge capacity (mAh/g)
`Discharge_mAh/g`	Specific discharge capacity (mAh/g)

Coulombic Efficiency (_ce_v_cyc.csv)

Column	Description
`Cycle Index`	Cycle number
`CE_percent`	Coulombic efficiency (%)

Capacity Retention (_retention_v_cyc.csv)

Column	Description
`Cycle Index`	Cycle number
`CapacityRetention_percent`	Capacity retention relative to first cycle (%)

Energy vs Cycle (_ene_v_cyc.csv) — requires --energy flag

Column	Description
`Cycle Index`	Cycle number
`Charge_mWh/g`	Specific charge energy (mWh/g)
`Discharge_mWh/g`	Specific discharge energy (mWh/g)

Time-Series Data¶

First Cycle Overview (_first_cyc.csv)

Column	Description
`Time_min`	Time in minutes
`Voltage(V)`	Cell voltage (V)
`Current(mA)`	Applied current (mA)

Voltage vs Time (_volt_v_time.csv)

Column	Description
`Time_hr`	Time in hours
`Voltage_V`	Cell voltage (V)

Complex Data¶

dQ/dV (_dqdv.csv) — requires --derivative flag

Column	Description
`Cycle`	Cycle number
`Mode`	`charge` or `discharge`
`Voltage_V`	Voltage (V)
`dQdV_mAh_per_V_per_g`	Differential capacity (mAh/V/g)

Capacity vs Voltage (_cap_v_volt.csv)

Column	Description
`Cycle`	Cycle number
`Mode`	`charge` or `discharge`
`Voltage_V`	Voltage (V)
`Charge_Capacity_mAh_per_g`	Charge capacity (mAh/g, charge rows)
`Discharge_Capacity_mAh_per_g`	Discharge capacity (mAh/g, discharge rows)

4. Averaged Data CSVs¶

When using --average or --average-energy, averaged CSV files are always produced (regardless of --csv flag). They use the naming pattern:

Plot Type	CSV Filename
Average Capacity	`{group}_avg_cap_v_cyc.csv`
Average Energy	`{group}_avg_ene_v_cyc.csv`
Average Retention	`{group}_avg_ret_v_cyc.csv`
Average CE	`{group}_avg_ce_v_cyc.csv`

5. Use Cases¶

Spreadsheet analysis: Open CSVs in Excel, Google Sheets, or LibreOffice Calc
Custom plotting: Import into Python (pandas), MATLAB, R, or Origin
Batch data extraction: Use --csv-only for fast data export without rendering plots
Archival: Store raw data alongside publication figures