{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Adding custom metadata\n",
    "It is possible to attach and store arbitrary metadata to WelDX objects as python attributes.\n",
    "The WelDX API reserves the attribute names `wx_metadata` and `wx_user` for these use cases.\n",
    "\n",
    "The `wx_metadata` field is intended for additional information that might be required as part of a custom Quality Standard. The `wx_user` attribute is intended to add any user data and should only be used for additional information that will not get accessed by the API. \n",
    "\n",
    "## A small example\n",
    "Let's say we want to use metadata to add a custom information to a current-sensor used during a welding experiment. As an example we want to add a timestamp to indicate when the sensor was last calibrated."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We start by creating the sensor object as a `MeasurementEquipment`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from weldx.measurement import MeasurementEquipment\n",
    "\n",
    "HKS_sensor = MeasurementEquipment(name=\"HKS P1000-S3\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we want to add the timestamp of the last time the sensor was calibrated as additional metadata. To do this we simple assign a new `.wx_metadata` attribute to the sensor. We will also add a small personal note to `wx_user`.\n",
    "\n",
    "*Note: By convention the metadata fields should be python dictionaries.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "HKS_sensor.wx_metadata = {\"calibration\": pd.Timestamp(\"2020-06-01\")}\n",
    "HKS_sensor.wx_user = {\"notes\": [\"wallmounted\", \"The cable seems to be a bit loose.\"]}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's look at the ASDF file contents with our metadata. We will find our data\n",
    "at the very end after the ASDF header."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from weldx import WeldxFile\n",
    "\n",
    "file = WeldxFile(tree={\"sensor\": HKS_sensor}, mode=\"rw\")\n",
    "file.header()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we can see, our custom metadata gets serialized into the ASDF tree:\n",
    "```yaml\n",
    "wx_metadata:\n",
    "    calibration: !<asdf://weldx.bam.de/weldx/tags/time/timestamp-1.0.0> {value: '2020-06-01T00:00:00'}\n",
    "  wx_user:\n",
    "    notes: [wallmounted, The cable seems to be a bit loose.]\n",
    "```\n",
    "Let's check if we keep the information upon reading the file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "in_memory_file = WeldxFile(file.write_to())\n",
    "\n",
    "from IPython.display import display\n",
    "\n",
    "display(in_memory_file[\"sensor\"].wx_metadata)\n",
    "display(in_memory_file[\"sensor\"].wx_user)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "",
   "language": "python",
   "name": ""
  },
  "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.8.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}