{
  "cells": [
    {
      "cell_type": "markdown",
      "id": "0",
      "metadata": {},
      "source": [
        "# Metadata\n",
        "\n",
        "BDF writes rich metadata alongside each dataset (as JSON-LD embedded in an HTML landing page and/or sidecar files), so data are self-describing and web-discoverable. \n",
        "\n",
        "## Design Principles\n",
        "BDF favors schema.org for maximum interoperability on the semantic web (and rich presentation in Dataset Search), while also supporting CSVW for precise tabular schemas. Quantity meanings are grounded in the BDF application ontology to keep terminology consistent across tools and datasets.\n",
        "\n",
        "## Content\n",
        "\n",
        "BDF metadata covers three main categories:\n",
        "\n",
        "1. **Bibliographic (who/what/when).** This includes information about what the dataset is and who made it. The purpose of bibliographic metadata is to enable proper citations, credit, reproducibility, and searching. It features fields like:  \n",
        "\n",
        "    - title, description, keywords  \n",
        "    - creators and contributors  \n",
        "    - date, version, and license  \n",
        "    - provenance  \n",
        "\n",
        "2. **Content (what's in the table).** This describes the quantities in your dataset so tools and search engines can understand them. BDF supports descriptions of table quantities using both schema.org and csvw markup. This mapping is handled automatically by BDF. \n",
        "\n",
        "3. **Distribution (where and how to get the file).** This describes the actual downloadable artifact(s). It includes files like:\n",
        "\n",
        "    - file URL(s), media type (e.g., text/csv, application/parquet)  \n",
        "    - size/checksums (optional), content variants (raw/processed)  \n",
        "    - landing page vs. direct download (schema.org/DataDownload)  "
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "1",
      "metadata": {},
      "outputs": [],
      "source": [
        "import bdf\n",
        "from bdf.metadata import Dataset, Creator, DataDownload, Battery"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "2",
      "metadata": {},
      "outputs": [],
      "source": [
        "# Read the raw source data and display the header\n",
        "# This export stores its time columns in milliseconds under seconds headers;\n",
        "# bdf.read detects the mismatch against the recorded timestamps and raises\n",
        "# unless we explicitly opt into the repair with reconcile_time=True.\n",
        "df, source_meta = bdf.read(\n",
        "    \"https://zenodo.org/records/17295469/files/FZJ__INR21700__20250606__HPPC__25degC__Digatron.csv\",\n",
        "    reconcile_time=True,\n",
        ")\n",
        "df = df.to_pandas()\n",
        "df.head()"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "3",
      "metadata": {},
      "outputs": [],
      "source": [
        "meta = Dataset(\n",
        "    title=\"Digatron INR21700 HPPC\",\n",
        "    creators=[Creator(name=\"Example Creator\", orcid=\"0000-0002-0000-0010\", given_name=\"Example\", family_name=\"Creator\", affiliation=\"Your Lab\")],\n",
        "    description=\"HPPC characterization of an INR21700 cell at 25\u00b0C on a Digatron cycler.\",\n",
        "    keywords=[\"li-ion\", \"inr21700\", \"hppc\"],\n",
        "    license=\"CC-BY-4.0\",\n",
        "    url=\"https://zenodo.org/records/17295469\",\n",
        "    version=\"1.0.0\",\n",
        "    publication_date=\"2025-06-06\",\n",
        ")\n",
        "\n",
        "dist = DataDownload(\n",
        "    url=\"https://zenodo.org/records/17295469/files/FZJ__INR21700__20250606__HPPC__25degC__Digatron.csv\",\n",
        "    name=\"Digatron CSV file\",\n",
        "    encoding_format=\"text/csv\",\n",
        "    description=\"Primary CSV export from Digatron cycler.\"\n",
        ")\n",
        "\n",
        "battery = Battery(\n",
        "    id=\"g20m7\",\n",
        "    model = \"G20M7\",\n",
        "    manufacturer = \"Google\", \n",
        "    iec_code = \"ICP6/65/75\",\n",
        "    form_factor = \"prismatic\",\n",
        "    nominal_voltage_v = 3.90,\n",
        "    rated_capacity_ah = 4.835,\n",
        "    mass_g = 63,\n",
        "    volume_l = 0.02925,\n",
        "    pe_materials = [\"cobalt\"],\n",
        "    ne_materials = [\"graphite\"]\n",
        ")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "4",
      "metadata": {},
      "outputs": [],
      "source": [
        "# Save the metadata to JSON-LD\n",
        "\n",
        "meta.save_jsonld(\n",
        "    \"./out/metadata/dataset.schemaorg.jsonld\",\n",
        "    dataset_uri=\"https://doi.org/10.5281/zenodo.16994937#digatron-csv-li-ion-hppc\",\n",
        "    identifier=\"digatron-csv-li-ion-hppc\",\n",
        "    distributions=[dist],\n",
        "    df=df\n",
        ")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "5",
      "metadata": {},
      "outputs": [],
      "source": [
        "# Save the metadata as rich results html for Google / Semantic Web integration\n",
        "\n",
        "meta.save_rich_results_html(\n",
        "    \"./out/metadata/dataset.schemaorg.html\",\n",
        "    title=\"Digatron INR21700 HPPC\",\n",
        "    graphify=True,\n",
        "    dataset_uri=\"https://doi.org/10.5281/zenodo.16994937#digatron-csv-li-ion-hppc\",\n",
        "    identifier=\"digatron-csv-li-ion-hppc\",\n",
        "    distributions=[dist],\n",
        "    df=df\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
}