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[hvplot]"):

Extra

Adds

hvplot

Interactive exploration with Bokeh/HoloViews.

polars

Polars support plus the fast NDA backend (requires numpy>=2.2).

numpy2

Forces numpy 2.x (recommended for fastnda).

dev

Test and lint tooling for contributors.

docs

Sphinx docs toolchain.

fastnda

Fast NDA backend (requires numpy>=2.2).

Plotly interactive plots and Neware NDA support are included in the base install.

Quickstart notebook#

Open the rendered notebook:

First steps#

import bdf

df = bdf.read("raw_vendor.csv")  # auto-detect and normalize
report = bdf.validate(df, report=True, raise_on_error=False)
bdf.plot(df, xdata="Test Time / s", ydata=["Voltage / V"], save="plot.png")