Get Started#

Battery Data Format (BDF) is a canonical schema for cycler time-series data. The bdf package reads vendor exports, normalizes them into BDF, validates and repairs datasets, and produces metadata for sharing.

What BDF standardizes#

BDF fixes the column labels and units so datasets from different cyclers can be compared without custom glue code.

Required columns:

  • Test Time / s

  • Voltage / V

  • Current / A

Common recommended columns:

  • Unix Time / s

  • Cycle Count / 1

  • Step Count / 1

  • Ambient Temperature / degC

Install#

pip install batterydf

PyPI distribution name is batterydf; Python import and CLI remain bdf.

Extras (combine as needed, for example pip install "batterydf[nda,plot]"):

Extra

Adds

nda

Neware .nda/.ndax support (fastnda backend, requires numpy>=2.2).

mpr

BioLogic .mpr support (via yadg).

excel

Excel support via the fast calamine engine.

mat

MATLAB .mat support.

arbin

Arbin .res support.

yaml

YAML plugin definitions.

plot

Static (matplotlib) interactive (plotly) plotting.

hvplot

Interactive exploration with Bokeh/HoloViews.

all

Every extra above.

Dev-only tooling (tests, linting, docs) are in [dependency-groups], clone the repo and use uv sync – see CONTRIBUTING.md for more info.

Quickstart notebook#

Open the rendered notebook:

First steps#

import bdf

# read() returns (frame, metadata); the frame is a polars frame
df, meta = bdf.read("raw_vendor.csv")  # auto-detect and normalize
df = df.to_pandas()  # the validate/plot helpers operate on pandas
report = bdf.validate(df, report=True, raise_on_error=False)
bdf.plot(df, xdata="Test Time / s", ydata=["Voltage / V"], save="plot.png")