BDF Quickstart#

Welcome to the Battery Data Format (BDF)! This notebook shows a quick minimal workflow using the BDF package:

  1. Read a dataset from a defined source

  2. Visualize the dataset with line plots

  3. Save the dataset as a BDF file

# Import the package
import bdf

# Read the raw source data and display the header
# read() returns (frame, metadata); convert to pandas for the plot/save helpers below
df, meta = bdf.read("https://zenodo.org/records/17289383/files/SINTEF__NaCR32140-MP10-04__2025-08-25__GITT_0p05C_25degC__BioLogic.mpt")
df = df.to_pandas()
df.head()
Test Time / s Voltage / V Current / A Cycle Count / 1 Step ID Step Time / s Net Capacity / Ah Charging Energy / Wh Discharging Energy / Wh Net Energy / Wh Power / W Internal Resistance / ohm
0 0.000000 1.714230 0.0 0 0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
1 10.000000 1.714152 0.0 0 0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
2 20.000001 1.714152 0.0 0 0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
3 30.000001 1.714230 0.0 0 0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
4 40.000002 1.714191 0.0 0 0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 
# Visualize the data using the default features or a customized view
bdf.plot(df)

<Figure size 640x480 with 1 Axes>

# Visualize the data using a customized view
bdf.plot(
    df,
    xdata="Test Time / s", xunit="h",
    ydata="Voltage / V", 
    yydata="Current / A",
)

<Figure size 640x480 with 2 Axes>

# Save the data as a BDF CSV (column headers unchanged by default)
bdf.save(df, "./out/quickstart/InstitutionCode__CellName__YYYYMMDD_XXX.bdf.csv")
# Optional: write machine-readable (skos:notation) headers instead
# bdf.save(df, "./out/quickstart/InstitutionCode__CellName__YYYYMMDD_XXX.bdf.csv", labels="machine")

Next Steps#

Additional features are comprehensively presented in dedicated example notebooks. We recommend exploring them in the following order:

Notebook

Description

read.ipynb

Load vendor/registry sources and produce a normalized BDF DataFrame.

validate.ipynb

Run BDF schema checks and reports (incl. non-monotonic time warnings).

ontology_spec_and_units.ipynb

Inspect the column ontology, load other versions or a custom TTL, and convert units via the spec.

visualization.ipynb

Plot BDF data with clean styling and on-the-fly unit conversions.

repair.ipynb

Fix timestamps, clean columns, and apply other data repair utilities.

ingest.ipynb

Ingest data from a directory or filepath into BDF.

metadata.ipynb

Generate schema.org + CSVW JSON-LD metadata for datasets and distributions.