Skip to content

Quick Start Guide

Get up and running with BatteryProc in minutes. This guide covers the most common workflow: processing raw battery data into publication-ready plots and metrics.

Prerequisites

Make sure you have completed the Installation steps first.

1. Process a Single File

The simplest command takes a data file and an output directory. BatteryProc supports .xlsx (Neware), .csv, .txt, and .mpt (BioLogic) formats.

batteryproc data/cell_01.xlsx -o results/

What happens:

  1. BatteryProc reads cell_01.xlsx and detects its format.
  2. It creates a subfolder results/cell_01_Results/.
  3. It calculates per-cycle metrics (capacity, efficiency, retention) and generates standard plots.

If the file contains a placeholder active material mass (e.g., 1 g), BatteryProc will pause and ask you to enter the correct mass. You can skip this prompt by providing the mass upfront:

batteryproc data/cell_01.xlsx --mass-g 0.523 -o results/

2. Batch Processing

To process an entire folder of data files, point to the directory. Add -r to search subdirectories recursively.

# All supported files in one directory
batteryproc data/project_A/ -o results/project_A/

# Include subdirectories
batteryproc data/project_A/ -r -o results/project_A/

Each input file gets its own subfolder within the output directory.

3. Enable Advanced Analysis

Add flags to request additional plots and data:

batteryproc data/cell_01.xlsx --energy --derivative --svg -o results/
Flag What it adds
--energy Specific energy (Wh/kg) vs. cycle plots.
--derivative Differential capacity (dQ/dV) analysis — useful for identifying phase transitions.
--derivative 1 10 50 dQ/dV for specific cycles instead of just the last cycle.
--svg High-quality vector graphics alongside standard PNGs.
--csv Export the underlying data of every plot as CSV files.

4. Understanding the Output

After running the command, navigate to your output folder. For an input file cell_01.xlsx, you will find a folder named cell_01_Results/ containing:

File What it shows What to look for
*_capacity_vs_cycle.png Charge and discharge capacity per cycle The slope of the discharge curve indicates capacity fade.
*_ce_vs_cycle.png Coulombic efficiency per cycle Should approach 99–100% after formation. Dips indicate side reactions.
*_retention_vs_cycle.png Capacity retention (Cycle 1 = 100%) How quickly the cell is degrading.
*_capacity_vs_voltage.png Voltage profiles for selected cycles Shifts in curves signal internal resistance growth or loss of active material.

If you used --energy, you will also see *_energy_vs_cycle.png. If you used --derivative, you will see *_dqdv_profiles.png (peaks correspond to material phase changes).

See the Plot Gallery for visual examples of every plot type.

5. Export Data as CSV

To get the numeric data behind every plot as CSV files:

# CSVs alongside plots
batteryproc data/cell_01.xlsx --csv -o results/

# CSVs only (skip plot rendering — faster)
batteryproc data/cell_01.xlsx --csv-only -o results/

See the CSV Data Export Guide for column definitions and naming conventions.

6. Next Steps