{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# How to plot.\n\nThere exist multiple ways to plot using Or\u00edon. We will start with the most convenient one, the\nexperiment object plot accessor.\n\n\n## Accessor ``experiment.plot``\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>It only supports single experiment plots. It does not support ``regrets`` and ``averages``.</p></div>\n\nIt is possible to render most plots directly with \nthe :py:class:`ExperimentClient <orion.client.experiment.ExperimentClient>` object.\nThe accessor ``ExperimentClient.plot`` can be used to plot the results of the experiment.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from orion.client import get_experiment\n\n# Specify the database where the experiments are stored. We use a local PickleDB here.\nstorage = dict(type=\"legacy\", database=dict(type=\"pickleddb\", host=\"../../db.pkl\"))\n\n# Load the data for the specified experiment\nexperiment = get_experiment(\"2-dim-exp\", storage=storage)\nfig = experiment.plot.regret()\nfig.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Module ``plotting``\n\nThe plotting module can used as well to plot experiments.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import orion.plotting.base as plot\n\nfig = plot.regret(experiment)\nfig.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The advantage of the plotting module is that it can render plots using\nmultiple examples as shown in the example below.\n\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fig = plot.regret(experiment)\nfig.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Command ``orion plot``\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>The plotting command line utility does not support arguments for now. Contributions are\n    welcome! :)</p></div>\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>Only supports single experiment plots. It does not support ``regrets`` and ``averages``.</p></div>\n\nThis section refers to the use of the ``orion plot ...`` subcommand.\n\n### Usage\n\nThe arguments expected by the \"plot\" subcommand are as follows\n\n.. code-block :: console\n\n   usage: orion plot [-h] [-n stringID] [-u USER] [-v VERSION] [-c path-to-config]\n                     [-t {png,jpg,jpeg,webp,svg,pdf,html,json}]\n                     [-o OUTPUT] [--scale SCALE]\n                     {lpi,parallel_coordinates,partial_dependencies,regret}\n\n   Produce plots for Or\u00edon experiments\n\n   positional arguments:\n   {lpi,parallel_coordinates,partial_dependencies,regret}\n                           kind of plot to generate.\n\n   optional arguments:\n   -h, --help            show this help message and exit\n   -t {png,jpg,jpeg,webp,svg,pdf,html,json}, --type {png,jpg,jpeg,webp,svg,pdf,html,json}\n                           type of plot to return. (default: png)\n   -o OUTPUT, --output OUTPUT\n                           path where plot is saved. Will override the `type` argument.\n                           (default is {exp.name}-v{exp.version}_{kind}.{type})\n   --scale SCALE         more pixels, but same proportions of the plot.\n                           Scale acts as multiplier on height and width of resulting image.\n                           Overrides value of 'scale' in plotly.io.write_image.\n\n   Or\u00edon arguments:\n   These arguments determine orion's behaviour\n\n   -n stringID, --name stringID\n                           experiment's unique name;\n                           (default: None - specified either here or in a config)\n   -u USER, --user USER  user associated to experiment's unique name;\n                           (default: $USER - can be overriden either here or in a config)\n   -v VERSION, --version VERSION\n                           specific version of experiment to fetch; (default: None - latest experiment.)\n   -c path-to-config, --config path-to-config\n                           user provided orion configuration file\n\n### More about the arguments\n\nThe ``kind`` positional argument is the only mandatory argument.\nAssuming that the user identified the experiment in the usual\nway (e.g. using ``--name`` or a config file), the default behavior\nis to generate the correct ``kind`` of plot, and to save it\nas a \"png\" file in the current directory and with a filename\nautomatically formatted as \"{experiment.name}_{kind}.png\".\n\n#### kind\n\nThe plotting command requires a ``kind`` argument to determine which\nof the four kinds of plots to generate.\nThe choice is between 'lpi', 'partial_dependencies', 'parallel_coordinates'\nor 'regret'.\n\n\n#### type\n\nThe ``type`` is basically the filename extension. This governs more than just the name of the file\nbecause it determines the actual format of the output. The default is to give the user a 'png' file.\n\nBehind the scenes, *plotly* generates an initial 'json' file, and renders it as an image\nto be saved in the desired format. With ``type`` being 'json', that original file\nis saved without rendering it to an image.\n\nThe accepted values of ``type`` are 'png', 'jpg', 'jpeg', 'webp', 'svg', 'pdf', 'html' and 'json'.\n\n#### output\n\nThe default value for the output filename is an automatically-generated\nstring formatted as \"{experiment.name}_{kind}.{type}\".\nThis also implies that the plot will be saved in the current directory.\n\nWhen ``output`` is specified by the user with a file extension, the ``type`` argument\nwill be ignored because the value of ``type`` will be instead inferred by\nthe file extension in the ``output``.\nFor example, with ``--output=../myplot.jpg``, the results will be saved\nin the parent directory and the ``type`` will be 'jpg'.\n\n#### scale\n\nWith certain types of plots, it can be desirable to increase the\nresolution of the output image in terms of pixel counts (equivalent to dpi).\nThis applies particularly to 'jpg' and 'png', but it does not affect 'json' or 'html'.\n\nThe reference value of ``scale`` is 1.0.\nWith ``--scale 2.0``, the height and width are going to be doubled.\n\n## Web API\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>Only supports single experiment plots. It does not support ``regrets`` and ``averages``.</p></div>\n\nThe `web-api` supports queries for single experiment plots. See documentation for\nall queries. The JSON output is generated automatically according to the\n`Plotly.js schema reference <https://plotly.com/python/reference/index/>`_.\n\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "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.7.9"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}