{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "73f9d4fd-b593-4c64-8196-ca1c2752ab21",
   "metadata": {},
   "source": [
    "# Dataset Attributes"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8e85a060-f6e8-403c-b75a-73f570bfdaf9",
   "metadata": {},
   "source": [
    "(dataset-spec-attrs-required)=\n",
    "## Required dataset attributes\n",
    "\n",
    "Required dataset {attr}`attributes <xarray.Dataset.attrs>` are specified in a dataclass {class}`~quantify_core.data.dataset_attrs.QDatasetAttrs`.\n",
    "All attributes are mandatory to be present in the dataset but can be ``None`` or empty."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "18f53562-09b9-4d2a-a65a-764442abb32f",
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime\n",
    "from quantify_core.utilities import examples_support\n",
    "\n",
    "examples_support.mk_dataset_attrs(\n",
    "    dataset_name=\"Bias scan\",\n",
    "    timestamp_start=datetime.datetime.now().astimezone().isoformat(),\n",
    "    timestamp_end=(datetime.datetime.now().astimezone() + datetime.timedelta(seconds=120)).isoformat(),\n",
    "    dataset_state=\"done\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "686b6157-53ca-420c-b891-1bdac2ea6398",
   "metadata": {},
   "source": [
    "It may be necessary to specify versions of the key software components that were used to generate a dataset.\n",
    "This can be done using `software_versions` attribute, using either a published version or Git commit hash:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "96cefcfc-9bf8-4c18-bed2-605e063f623f",
   "metadata": {},
   "outputs": [],
   "source": [
    "examples_support.mk_dataset_attrs(\n",
    "    dataset_name=\"My experiment\",\n",
    "    timestamp_start=datetime.datetime.now().astimezone().isoformat(),\n",
    "    timestamp_end=(datetime.datetime.now().astimezone() + datetime.timedelta(seconds=120)).isoformat(),\n",
    "    software_versions={\n",
    "        \"lab_fridge_magnet_driver\": \"1.4.2\",  # software version/tag\n",
    "        \"my_lab_repo\": \"9d8acf63f48c469c1b9fa9f2c3cf230845f67b18\",  # git commit hash\n",
    "    },\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3de313b3-2610-43f3-b33b-8323b65bc47d",
   "metadata": {},
   "source": [
    "(dataset-spec-coord-attrs-required)=\n",
    "## Required dataset coordinate attributes\n",
    "\n",
    "Required coordinate {attr}`data array attributes <xarray.DataArray.attrs>` are specified in a dataclass {class}`~quantify_core.data.dataset_attrs.QCoordAttrs`.\n",
    "All attributes are mandatory to be present in the dataset but can be ``None``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c1be116c-6a4d-48ce-9ff5-1593d89fbdeb",
   "metadata": {},
   "outputs": [],
   "source": [
    "from quantify_core.utilities import examples_support\n",
    "examples_support.mk_main_coord_attrs() "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c0490ef4-b52b-43a6-bafa-36afcdd84836",
   "metadata": {},
   "outputs": [],
   "source": [
    "examples_support.mk_secondary_coord_attrs()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0dbef4af-97c9-490a-8f31-0dbf7ae6e1a4",
   "metadata": {},
   "source": [
    "(dataset-spec-vars-attrs-required)=\n",
    "## Required dataset data variables attributes\n",
    "\n",
    "Required data variable {attr}`data array attributes <xarray.DataArray.attrs>` are specified in a dataclass {class}`~quantify_core.data.dataset_attrs.QVarAttrs`.\n",
    "All attributes are mandatory to be present in the dataset but can be ``None``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d7b1b455-73c6-4a0d-9898-af029e8cb09f",
   "metadata": {},
   "outputs": [],
   "source": [
    "from quantify_core.utilities import examples_support\n",
    "examples_support.mk_main_var_attrs(coords=[\"time\"])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "966e6a51-b9af-4356-b275-884f3aa32a47",
   "metadata": {},
   "outputs": [],
   "source": [
    "examples_support.mk_secondary_var_attrs(coords=[\"cal\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a370078b-eecf-4ed2-8571-b953a8c5781f",
   "metadata": {},
   "source": [
    "(dataset-spec-attributes-primary-secondary-rel)=\n",
    "## Relationship between primary and secondary variables\n",
    "\n",
    "This is how the attributes of a dataset containing a ``q0`` main variable and ``q0_cal`` secondary variables would look like.\n",
    "The ``q0_cal`` corresponds to calibrations datapoints."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ad657327-b8b0-4b47-a2aa-4e1481841b55",
   "metadata": {},
   "outputs": [],
   "source": [
    "from quantify_core.data.dataset_attrs import QDatasetIntraRelationship\n",
    "from quantify_core.utilities import examples_support\n",
    "\n",
    "examples_support.mk_dataset_attrs(\n",
    "    relationships=[\n",
    "        QDatasetIntraRelationship(\n",
    "            item_name=\"q0\",\n",
    "            relation_type=\"calibration\",\n",
    "            related_names=[\"q0_cal\"],\n",
    "        ).to_dict()\n",
    "    ]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d4e11d0b-8f20-4679-b09d-78ab328275d7",
   "metadata": {},
   "source": [
    "See {ref}`sec-dataset-examples` for examples with more context."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "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.9.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}