User Guide#

Input formats#

bdf.read auto-detects cycler exports. You can also force a plugin:

import bdf
df = bdf.read("raw_vendor.csv", plugin="neware-csv")

Supported plugins:

Plugin id	File types	Notes
`basytec-txt`	`.txt`, `.dat`	Basytec result files.
`biologic-mpt`	`.mpt`	BioLogic MPT exports.
`digatron-csv`	`.csv`	Digatron CSV exports (including unit-row layouts).
`landt-csv`	`.csv`	Landt CSV with snake_case headers.
`landt-txt`	`.txt`	Landt text exports.
`matlab-mat`	`.mat`	Requires a sidecar mapping file.
`neware-csv`	`.csv`	Neware/BTS CSV exports.
`neware-nda`	`.nda`, `.ndax`	Neware NDA export (included by default).
`neware-nda-fast`	`.nda`, `.ndax`	Fast NDA backend (requires `fastnda`).
`novonix-csv`	`.csv`	Novonix UHPC CSV with `[Data]` section.

Workflows#

import bdf

df = bdf.read("raw_vendor.csv")
df_clean, rep = bdf.clean(df, time_fix="segment", outlier="none")
bdf.plot(df_clean, xdata="Test Time / s", ydata=["Voltage / V"])

Plotly interactive plots are included in the base install; Bokeh/HoloViews backends require batterydf[hvplot].

Recommended usage#

Use bdf.read for most workflows. The lower-level functions are for advanced cases:

bdf.parse: read vendor data without normalization.
bdf.normalize: normalize an in-memory DataFrame.
bdf.validate: validate a DataFrame or BDF artifact without re-reading.

For parse-only workflows:

df_raw = bdf.parse("raw_vendor.csv")

For collections:

summary = bdf.ingest("data/raw", out_dir="data/bdf", format="parquet")

CLI equivalent:

bdf ingest data/raw --out-dir data/bdf --format parquet

For repositories with multiple collections:

summary = bdf.ingest("data/repos", layout="nested", discover_collections=True)

Metadata#

BDF emits JSON-LD metadata for datasets and distributions.

from bdf.metadata import Dataset, Creator, DataDownload

meta = Dataset(
    title="Example dataset",
    creators=[Creator(name="Example Creator")],
    description="Short description of the dataset.",
)

dist = DataDownload(
    url="https://example.org/data.csv",
    name="Raw CSV export",
    encoding_format="text/csv",
)

meta.save_jsonld("out/metadata.jsonld", distributions=[dist])

Registry#

Aggregate JSON-LD metadata into a local registry for search and SPARQL queries.

import bdf

bdf.build_registry(["/path/to/metadata-root"], registry_dir="~/.bdf/registry")
hits = bdf.search("nmc 3.7V 5Ah", registry_dir="~/.bdf/registry")