doc/InteractivePlotter.ipynb

{
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  },
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "TRAPpy: Interactive Plotting"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<span style=\"font-size: 150%\">Re Run the cells to generate the graphs</span>"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import sys,os\n",
      "sys.path.append(\"..\")\n",
      "import numpy.random\n",
      "import pandas as pd\n",
      "import shutil\n",
      "import tempfile\n",
      "import trappy\n",
      "trace_thermal = \"./trace.txt\"\n",
      "trace_sched = \"../tests/raw_trace.dat\"\n",
      "TEMP_BASE = \"/tmp\""
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "code",
     "collapsed": true,
     "input": [
      "def setup_thermal():\n",
      "    tDir = tempfile.mkdtemp(dir=\"/tmp\", prefix=\"trappy_doc\", suffix = \".tempDir\")\n",
      "    shutil.copyfile(trace_thermal, os.path.join(tDir, \"trace.txt\"))\n",
      "    return tDir\n",
      "\n",
      "def setup_sched():\n",
      "    tDir = tempfile.mkdtemp(dir=\"/tmp\", prefix=\"trappy_doc\", suffix = \".tempDir\")\n",
      "    shutil.copyfile(trace_sched, os.path.join(tDir, \"trace.dat\"))\n",
      "    return tDir"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "code",
     "collapsed": true,
     "input": [
      "temp_thermal_location = setup_thermal()\n",
      "trace1 = trappy.FTrace(temp_thermal_location)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Interactive Line Plotting of Data Frames"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Interactive Line Plots Supports the same API as the LinePlot but provide an interactive plot that can be zoomed by clicking and dragging on the desired area. Double clicking resets the zoom."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "We can create an interactive plot easily from a dataframe by passing the data frame and the columns we want to plot as parameters:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "columns = [\"tick\", \"tock\"]\n",
      "df = pd.DataFrame(numpy.random.randn(1000, 2), columns=columns).cumsum()\n",
      "\n",
      "trappy.ILinePlot(df, column=columns).view()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Plotting independent series"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "It is also possible to plot traces with different index values (i.e. x-axis values)"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "columns = [\"tick\", \"tock\", \"bang\"]\n",
      "df_len = 1000\n",
      "df1 = pd.DataFrame(numpy.random.randn(df_len, 3), columns=columns, index=range(df_len)).cumsum()\n",
      "df2 = pd.DataFrame(numpy.random.randn(df_len, 3), columns=columns, index=(numpy.arange(0.5, df_len, 1))).cumsum()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "trappy.ILinePlot([df1, df2], column=\"tick\").view()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This does not affect filtering or pivoting in any way"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "df1[\"bang\"] = df1[\"bang\"].apply(lambda x: numpy.random.randint(0, 4))\n",
      "df2[\"bang\"] = df2[\"bang\"].apply(lambda x: numpy.random.randint(0, 4))"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "trappy.ILinePlot([df1, df2], column=\"tick\", filters = {'bang' : [2]}, title=\"tick column values for which bang is 2\").view()"
     ],
     "language": "python",
     "metadata": {
      "scrolled": true
     },
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "code",
     "collapsed": true,
     "input": [
      "trappy.ILinePlot([df1, df2], column=\"tick\", pivot=\"bang\", title=\"tick column pivoted on bang column\").view()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Interactive Line Plotting of Traces"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "We can also create them from trace objects"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "map_label = {\n",
      "        \"00000000,00000006\" : \"A57\",\n",
      "        \"00000000,00000039\" : \"A53\",\n",
      "}\n",
      "\n",
      "l = trappy.ILinePlot(\n",
      "        trace1,                                          # TRAPpy FTrace Object\n",
      "        trappy.cpu_power.CpuInPower,                     # TRAPpy Event (maps to a unique word in the Trace)\n",
      "        column=[                                         # Column(s)\n",
      "            \"dynamic_power\",\n",
      "            \"load1\"],\n",
      "\n",
      "        filters={                                        # Filter the data  \n",
      "            \"cdev_state\": [\n",
      "                1,\n",
      "                0]},\n",
      "        pivot=\"cpus\",                                    # One plot for each pivot will be created\n",
      "        map_label=map_label,                             # Optionally, provide an alternative label for pivots\n",
      "        per_line=1)                                      # Number of graphs per line\n",
      "l.view()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "You can also change the drawstyle to \"steps-post\" for step plots. These are suited if the data is discrete \n",
      "and linear interploation is not required between two data points"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "l = trappy.ILinePlot(\n",
      "    trace1,                                          # TRAPpy FTrace Object\n",
      "    trappy.cpu_power.CpuInPower,                     # TRAPpy Event (maps to a unique word in the Trace)\n",
      "    column=[                                         # Column(s)\n",
      "        \"dynamic_power\",\n",
      "        \"load1\"],\n",
      "\n",
      "    filters={                                        # Filter the data  \n",
      "        \"cdev_state\": [\n",
      "            1,\n",
      "            0]},\n",
      "    pivot=\"cpus\",                                    # One plot for each pivot will be created\n",
      "\n",
      "    per_line=1,                                      # Number of graphs per line\n",
      "    drawstyle=\"steps-post\")                                     \n",
      "l.view()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Plots for a given time range"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Performance can suffer if ILinePlot tries to make a huge plot.  One way of fixing it is by limiting the period of time plotted using the `xlim` parameter:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "trappy.ILinePlot(\n",
      "    trace1,\n",
      "    signals=[\"thermal:temp\"],\n",
      "    xlim=(1, 4),           # Only between seconds 1 and 4\n",
      ").view()"
     ],
     "language": "python",
     "metadata": {
      "run_control": {
       "marked": true
      }
     },
     "outputs": []
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Synchronized zoom in multiple plots"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "ILinePlots can zoom all at the same time.  You can do so using the `group` and `sync_zoom` parameter.  All ILinePlots using the same group name zoom at the same time.  Note the use of signals with colors."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "trappy.ILinePlot(\n",
      "    trace1,\n",
      "    signals=[\"cpu_in_power:dynamic_power:18,140,171\", \"cpu_in_power:load1:0xcf,0x36,0x4a\"],\n",
      "    pivot=\"cpus\",\n",
      "    group=\"synchronized\",\n",
      "    sync_zoom=True\n",
      ").view()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Styling ILinePlots"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Use `fill=True` to colour-fill the space under the line. `fill_alpha` optionally sets the opacity."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "trappy.ILinePlot(\n",
      "    trace1,\n",
      "    signals=[\"thermal:temp\"],\n",
      "    fill=True,\n",
      "    fill_alpha=0.5\n",
      ").view()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "EventPlot"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "TRAPpy's  Interactive Plotter features an Interactive Event TimeLine Plot. It accepts an input data of the type\n",
      "<pre>\n",
      "<code>\n",
      "                   { \"A\" : [\n",
      "                                    [event_start, event_end, lane],\n",
      "                                    .\n",
      "                                    .\n",
      "                                    [event_start, event_end, lane],\n",
      "                                 ],\n",
      "                     .\n",
      "                     .\n",
      "                     .\n",
      "\n",
      "                     \"B\" : [\n",
      "                                    [event_start, event_end, lane],\n",
      "                                    .\n",
      "                                    .\n",
      "                                    [event_start, event_end, lane],\n",
      "                    .\n",
      "                    .\n",
      "                    .\n",
      "                   }\n",
      "                                \n",
      "</code>\n",
      "</pre>\n",
      "\n",
      "Hovering on the rectangles gives the name of the process element and scrolling on the Plot Area and the window in the summary controls the zoom. One can also click and drag for panning a zoomed graph.\n",
      "\n",
      "For Example:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "A = [\n",
      "    \n",
      "        [0, 3, 0],\n",
      "        [4, 5, 2],\n",
      "]\n",
      "\n",
      "B = [\n",
      "        [0, 2, 1],\n",
      "        [2, 3, 3],\n",
      "        [3, 4, 0],\n",
      "]\n",
      "\n",
      "C =  [\n",
      "        [0, 2, 3],\n",
      "        [2, 3, 2],\n",
      "        [3, 4, 1],\n",
      "]\n",
      "\n",
      "EVENTS = {}\n",
      "EVENTS[\"A\"] = A\n",
      "EVENTS[\"B\"] = B\n",
      "EVENTS[\"C\"] = C\n",
      "\n",
      "trappy.EventPlot(EVENTS,\n",
      "                 keys=EVENTS.keys,                     # Name of the Process Element\n",
      "                 lane_prefix=\"LANE: \",                 # Name of Each TimeLine\n",
      "                 num_lanes=4,                          # Number of Timelines\n",
      "                 domain=[0,5]                          # Time Domain\n",
      "                ).view()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Lane names can also be specified as strings (or hashable objects that have an str representation) as follows"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "A = [\n",
      "    \n",
      "        [0, 3, \"zero\"],\n",
      "        [4, 5, \"two\"],\n",
      "]\n",
      "\n",
      "B = [\n",
      "        [0, 2, 1],\n",
      "        [2, 3, \"three\"],\n",
      "        [3, 4, \"zero\"],\n",
      "]\n",
      "\n",
      "C =  [\n",
      "        [0, 2, \"three\"],\n",
      "        [2, 3, \"two\"],\n",
      "        [3, 4, 1],\n",
      "]\n",
      "\n",
      "EVENTS = {}\n",
      "EVENTS[\"A\"] = A\n",
      "EVENTS[\"B\"] = B\n",
      "EVENTS[\"C\"] = C\n",
      "\n",
      "trappy.EventPlot(EVENTS,\n",
      "                 keys=EVENTS.keys,                     # Name of the Process Element\n",
      "                 lanes=[\"zero\", 1, \"two\", \"three\"],\n",
      "                 domain=[0,5]                          # Time Domain\n",
      "                ).view()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "It is also possible to define a colour map to associate a specific colour to each event. A colour string can be:\n",
      "\n",
      " - a colour name, `green`, `red`, `blue`, etc.\n",
      " \n",
      " - the HEX representation of the colour, `#0000FF` for blue, `#FF0000` for red\n",
      " "
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# Using colour names\n",
      "trappy.EventPlot(EVENTS,\n",
      "                 keys=EVENTS.keys,                     # Name of the Process Element\n",
      "                 lanes=[\"zero\", 1, \"two\", \"three\"],\n",
      "                 domain=[0,5],                         # Time Domain\n",
      "                 color_map={\"A\" : \"blue\", \"B\" : \"red\", \"C\" : \"green\"}\n",
      "                ).view()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# Using HEX representation of colours\n",
      "trappy.EventPlot(EVENTS,\n",
      "                 keys=EVENTS.keys,                     # Name of the Process Element\n",
      "                 lanes=[\"zero\", 1, \"two\", \"three\"],\n",
      "                 domain=[0,5],                         # Time Domain\n",
      "                 color_map={\"A\" : \"\t#ffa07a\", \"B\" : \"#f08080\", \"C\" : \"#add8e6\"}\n",
      "                ).view()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "TracePlot"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "A specification of the EventPlot creates a kernelshark like plot if the sched_switch event is enabled in the traces"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "f = setup_sched()\n",
      "trappy.plotter.plot_trace(f)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": null
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Exporting notebooks with interactive plots to HTML"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Notebooks with ILinePlot or EventPlot can't be exported to HTML using File->Download as->HTML.  They need to be converted from the command line:\n",
      "```\n",
      "jupyter nbconvert --to=trappy.nbexport.HTML notebook.ipynb\n",
      "```\n",
      "You need nbconvert >= 4.2 and trappy has to be in your `PYTHONPATH`."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}