{
  "cells": [
    {
      "cell_type": "markdown",
      "id": "0",
      "metadata": {},
      "source": [
        "# BDF Quickstart\n",
        "\n",
        "Welcome to the Battery Data Format (BDF)! This notebook shows a quick minimal workflow using the **BDF** package:\n",
        "\n",
        "1. **Read** a dataset from a defined source\n",
        "2. **Visualize** the dataset with line plots\n",
        "3. **Save** the dataset as a BDF file"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "1",
      "metadata": {},
      "outputs": [],
      "source": [
        "# Import the package\n",
        "import bdf"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "2",
      "metadata": {},
      "outputs": [],
      "source": [
        "# Read the raw source data and display the header\n",
        "# read() returns (frame, metadata); convert to pandas for the plot/save helpers below\n",
        "df, meta = bdf.read(\"https://zenodo.org/records/17289383/files/SINTEF__NaCR32140-MP10-04__2025-08-25__GITT_0p05C_25degC__BioLogic.mpt\")\n",
        "df = df.to_pandas()\n",
        "df.head()"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "3",
      "metadata": {},
      "outputs": [],
      "source": [
        "# Visualize the data using the default features or a customized view\n",
        "bdf.plot(df)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "4",
      "metadata": {},
      "outputs": [],
      "source": [
        "# Visualize the data using a customized view\n",
        "bdf.plot(\n",
        "    df,\n",
        "    xdata=\"Test Time / s\", xunit=\"h\",\n",
        "    ydata=\"Voltage / V\", \n",
        "    yydata=\"Current / A\",\n",
        ")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "5",
      "metadata": {},
      "outputs": [],
      "source": [
        "# Save the data as a BDF CSV (column headers unchanged by default)\n",
        "bdf.save(df, \"./out/quickstart/InstitutionCode__CellName__YYYYMMDD_XXX.bdf.csv\")\n",
        "# Optional: write machine-readable (skos:notation) headers instead\n",
        "# bdf.save(df, \"./out/quickstart/InstitutionCode__CellName__YYYYMMDD_XXX.bdf.csv\", labels=\"machine\")"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "6",
      "metadata": {},
      "source": [
        "## Next Steps\n",
        "\n",
        "Additional features are comprehensively presented in dedicated example notebooks. We recommend exploring them in the following order:\n",
        "\n",
        "| Notebook            | Description                                                                 |\n",
        "|---------------------|-----------------------------------------------------------------------------|\n",
        "| read.ipynb          | Load vendor/registry sources and produce a normalized BDF DataFrame.        |\n",
        "| validate.ipynb      | Run BDF schema checks and reports (incl. non-monotonic time warnings).      |\n",
        "| ontology_spec_and_units.ipynb | Inspect the column ontology, load other versions or a custom TTL, and convert units via the spec. |\n",
        "| visualization.ipynb | Plot BDF data with clean styling and on-the-fly unit conversions.           |\n",
        "| repair.ipynb        | Fix timestamps, clean columns, and apply other data repair utilities.       |\n",
        "| ingest.ipynb      | Ingest data from a directory or filepath into BDF. |\n",
        "| metadata.ipynb      | Generate schema.org + CSVW JSON-LD metadata for datasets and distributions. |\n",
        "\n"
      ]
    }
  ],
  "metadata": {
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.10.10"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}