{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. _introduction:\n",
    "\n",
    "|\n",
    "|\n",
    "\n",
    "Download This Notebook: :download:`Introduction.ipynb`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction\n",
    "\n",
    "This tutorial provides a brief overview of the key features of the GrAF format and demonstrates how to interact with GrAF files in Python."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interacting with a GrAF file\n",
    "\n",
    "### Creating a GrAF file\n",
    "\n",
    "The easiest way to create a GrAF file in Python is to convert a `matplotlib` figure directly to a `Graf` object. The `Graf` class then provides functions for saving it to a file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Adding axes\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from graf.base import *\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "# Example data\n",
    "x1 = [1,2,3,4,5,6,7,8,9,10]\n",
    "y1 = [7,3,7,6,5,7,2,1,9, 0]\n",
    "\n",
    "# Make the plot in matplotlib\n",
    "fig1, ax1 = plt.subplots(nrows=1)\n",
    "ax1.plot(x1, y1, marker='o', linestyle=':', color=(0.8, 0, 0.4))\n",
    "ax1.set_xlabel(\"X-axis\")\n",
    "ax1.set_ylabel(\"Y-axis\")\n",
    "fig1.suptitle(\"GrAF Example 1\")\n",
    "ax1.grid(True)\n",
    "\n",
    "# Now we make the GrAF object. It accepts a matplotlib figure as an optional \n",
    "# parameter which we're using here to initialize the object with our desired\n",
    "# plot.\n",
    "graf_fig1 = Graf(fig1)\n",
    "\n",
    "# Now save it to a file!\n",
    "graf_fig1.save_hdf(\"ex1_fig1.graf\")\n",
    "\n",
    "#NOTE: It's really important that you don't call plt.show() before passing the\n",
    "# matplotlib figure to GrAF! Otherwise, once you close the figure, the figure\n",
    "# handle will point to an empty figure and your GrAF file won't contain any \n",
    "# useful data!\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Reading a GrAF file\n",
    "\n",
    "Reading in the file is similarly easy..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Make the GrAF object. Note that we aren't initializing the object with any\n",
    "# data. That's because we're going to overwrite everything inside this object\n",
    "# with the contents of our GrAF file.\n",
    "graf2 = Graf()\n",
    "\n",
    "# Read the file\n",
    "graf2.load_hdf(\"ex1_fig1.graf\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now the figure data is saved in our `Graf` object. To plot the data, we can use `to_fig()`, which creates a matplotlib graph from the figure data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "sanserif\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Create a matplotlib figure\n",
    "fig2 = graf2.to_fig()\n",
    "\n",
    "# Show the figure\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Great! We just saved a plot to disk using a GrAF file and read it back!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Accessing the Underlying Data\n",
    "\n",
    "One of the most powerful features of GrAF is that saving and restoring graphs isn't all it can do; it also aims to make it easy to access the underlying data. From here, you can merge multiple graphs together, reanalyze data, or whatever else your heart desires <3."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Extracted data:\n",
       "    x: [np.float64(1.0), np.float64(2.0), np.float64(3.0), np.float64(4.0), np.float64(5.0), np.float64(6.0), np.float64(7.0), np.float64(8.0), np.float64(9.0), np.float64(10.0)]\n",
       "    y: [np.float64(7.0), np.float64(3.0), np.float64(7.0), np.float64(6.0), np.float64(5.0), np.float64(7.0), np.float64(2.0), np.float64(1.0), np.float64(9.0), np.float64(0.0)]\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# To directly access the underlying data, we have to specify which axes (Ax0)\n",
    "# and which trace (Tr0) we want to look at.\n",
    "extracted_x_data = graf2.axes['Ax0'].traces['Tr0'].x_data\n",
    "extracted_y_data = graf2.axes['Ax0'].traces['Tr0'].y_data\n",
    "\n",
    "print(f\"Extracted data:\")\n",
    "print(f\"    x: {extracted_x_data}\")\n",
    "print(f\"    y: {extracted_y_data}\")"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python 3.10.4 ('skrf')",
   "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.10.4"
  },
  "vscode": {
   "interpreter": {
    "hash": "6e9ab46c0308d25f8ecf2297d605bcf30c0184a06f23fc8ad30aef47f26c08c0"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}