Skip to content

Guide: Command-Line Interface Usage

Master the BatteryProc CLI to automate your data analysis workflow.

BatteryProc is designed to be used primarily from the command line, enabling you to process single files or entire datasets with a single command. This guide covers the essential commands, common workflows, and advanced features for power users.

1. Basic Syntax

The general syntax for running BatteryProc is:

batteryproc <inputs> -o <output_directory> [options]
  • inputs: One or more paths to data files (e.g., .xlsx, .csv) or directories.
  • -o / --outdir: The destination directory for all results. If not specified, results are saved in a Results folder next to the input file.

Tip: BatteryProc will automatically create the output directory if it doesn't exist.

2. Common Workflows

2.1. Process a Single File

Analyze one file and save results to a specific folder.

batteryproc data/cell_01.xlsx -o analysis/cell_01_results

2.2. Process a Directory (Batch Mode)

Process all supported files in a folder. This is non-recursive by default (it won't look in subfolders).

batteryproc data/batch_run_january/ -o results/january_batch
Each input file will get its own subfolder within results/january_batch.

2.3. Recursive Processing

Use the -r (or --recursive) flag to find and process files in all subdirectories. This is ideal for organizing data by project.

batteryproc data/project_alpha/ -r -o results/project_alpha_summary

3. Controlling Outputs

3.1. Plot Customization

BatteryProc generates standard capacity and efficiency plots by default. You can enable additional plots with flags:

  • --energy: Adds specific energy (Wh/kg) vs. cycle plots.
  • --derivative [CYCLES]: Adds differential capacity (dQ/dV) plots.
    • --derivative: Plots dQ/dV for the last cycle.
    • --derivative 1 10 50: Plots dQ/dV for cycles 1, 10, and 50.
  • --svg: Saves vector graphics (.svg) in addition to standard PNGs. Useful for high-quality publication figures.
  • --dpi <N>: Sets the resolution for PNGs (default is 300 DPI).

3.2. CSV Data Export

Export the underlying data of every plot as CSV files for use in spreadsheets or custom scripts.

  • --csv: Generate CSV files alongside plots.
  • --csv-only: Generate CSV files only, skipping plot rendering (faster).
# CSVs + plots
batteryproc data.xlsx --csv

# CSVs only (no plots)
batteryproc data.xlsx --csv-only

# Combine with energy and derivative flags
batteryproc data.xlsx --csv --energy --derivative 1 10

Note: --csv and --csv-only are mutually exclusive.

See the CSV Output Guide for column definitions and naming conventions.

3.3. Output Structure

For an input file my_cell.xlsx, BatteryProc creates a folder my_cell_Results/ containing: - my_cell_capacity_vs_cycle.png - my_cell_ce_vs_cycle.png - my_cell_capacity_vs_voltage.png - ...and any other requested plots.

4. Advanced Features

4.1. Mass and Normalization

Specific capacity (mAh/g) depends on the active material mass. BatteryProc tries to find this in the file, but often it's missing or set to a dummy value (1.0 g).

  • Interactive Prompt: If the tool detects a potential dummy mass (1g), it will pause and ask you to enter the correct mass in grams.
  • Automated Override: To skip the prompt (e.g., for scripts), provide the mass upfront: 
    batteryproc cell_01.xlsx --mass-g 0.523 --cell-weight-g 4.5
    • --mass-g: Active material mass (for mAh/g).
    • --cell-weight-g: Total cell weight (for Wh/kg).

4.2. Averaging Multiple Cells

You can create an average performance plot from multiple replicate cells. BatteryProc groups cells by filename and test protocol (step plan).

  • --average: Average capacity and Coulombic efficiency.
  • --average-energy: Average specific energy.
  • --average-ignore-plan: Force averaging even if test protocols differ (use with caution).

Example: 

batteryproc cell_A1.xlsx cell_A2.xlsx cell_A3.xlsx --average -o results/group_A
This produces an *_Average_avg_capacity_vs_cycle.png in the results/group_A root folder, showing the mean and standard deviation.

4.3. Force Processing

By default, files with very little data (e.g., only Cycle 1) are skipped to keep output clean. Use --force-process to override this check.

batteryproc incomplete_test.xlsx --force-process

5. Automation & Scripting

5.1. Quiet Mode and Progress Bars

  • --no-progress: Disables the progress bar. Essential for logging to files or CI/CD pipelines.
  • --quiet: Suppresses warnings, printing only critical errors.
batteryproc large_dataset/ --no-progress --quiet > log.txt 2>&1

5.2. Exit Codes

BatteryProc uses standard exit codes for shell scripting: - 0: Success (all files processed). - 1: Unexpected error. - 2: Parse error (invalid format). - 3: Data quality failure (bad cell). - 13: Permission denied.

Note: In batch mode, the exit code is 0 as long as at least one file succeeded. Check logs for individual failures.

See Also