{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Plotting Overview\n",
    "\n",
    "## Getting started\n",
    "\n",
    "Scipp offers a number of different ways to plot data from a `Variable`, `DataArray`, or a `Dataset`.\n",
    "It uses the `matplotlib` graphing library to do so, as well as the `pythreejs` project for 3D visualizations.\n",
    "\n",
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "*How to make plots interactive*\n",
    "\n",
    "Matplotlib makes static plots by default in Jupyter notebooks. To enable interactive plots, use\n",
    "```\n",
    "%matplotlib widget\n",
    "```\n",
    "at the start of your notebook\n",
    "(see [here](https://matplotlib.org/stable/users/explain/backends.html#the-builtin-backends)\n",
    "for more details on Matplotlib backends).\n",
    "    \n",
    "</div>\n",
    "\n",
    "Plotting functionality is available in two different ways:\n",
    "\n",
    "- using the [plot()](../generated/functions/scipp.plot.rst) free function\n",
    "- using the `.plot()` method on a Scipp object (variable, data array or dataset)\n",
    "\n",
    "The difference between the two possible plot functions is that the free function can accept more input types than just the Scipp objects.\n",
    "It can also plot raw NumPy arrays, as well as Python dicts of Scipp variables or data arrays.\n",
    "For Scipp objects, the produced plot will be the same with either approach: \n",
    "Internally, the `.plot()` method just forwards the Scipp object to the free function `plot()`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "*Note*\n",
    "\n",
    "Plot settings are cached in a scipp `config.yaml` file.\n",
    "See <a href=\"../python-reference/runtime-configuration.ipynb\">runtime-configuration</a> for more information\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Consider two data arrays storing 1-D data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "import scipp as sc\n",
    "\n",
    "size = 50\n",
    "rng = np.random.default_rng(seed=0)\n",
    "x = sc.linspace('x', 0.0, 2.0, num=size, unit='m')\n",
    "y = sc.linspace('y', 0.0, 1.0, num=5, unit='us')\n",
    "temp1 = sc.array(dims=['x'], values=rng.random(size), unit='K')\n",
    "temp1 += sc.linspace('x', 100, 105, num=size, unit='K')\n",
    "da1 = sc.DataArray(temp1, coords={'x': x})\n",
    "da1.name = 'temp1'  # Data array name is optional and will be used as a label\n",
    "temp2 = sc.array(dims=['x'], values=rng.random(size), unit='K')\n",
    "temp2.variances = temp2.values + 1\n",
    "temp2 += sc.linspace('x', 99, 102, num=size, unit='K')\n",
    "da2 = sc.DataArray(temp2, coords={'x': x})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The information in a data array or dataset is typically enough to create meaningful plots:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "da1.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the plot above, the `x` dimension has an associated `x` coordinate and its values are used to label the ticks on the horizontal axis.\n",
    "The coordinate name and the unit (here: `m`) are used as a label for the horizontal axis.\n",
    "In a 1-D plot the unit of the data values (here `K`) labels the vertical axis.\n",
    "\n",
    "Multiple data arrays can be plotted by passing a Python dict to the `plot` function.\n",
    "This example also illustrates how a data array with uncertainties results in a plot with error bars:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.plot({'temp1': da1, 'temp2': da2})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the data arrays are part of a dataset, we can plot this directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ds = sc.Dataset({'temp1': da1, 'temp2': da2})\n",
    "ds.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting slices or items of a dataset\n",
    "\n",
    "The usual indexing and slicing can be used to create plots of slices of data, or plots of individual items from a dataset.\n",
    "\n",
    "### Plot a single entry of a dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ds['temp2'].plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Plot a slice range"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ds['x', 10:30].plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2-D data\n",
    "\n",
    "### Creating a 2-D plot\n",
    "\n",
    "2-D data arrays can be plotted directly, just like 1-D data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "size = 50\n",
    "rng = np.random.default_rng(seed=0)\n",
    "x = sc.linspace('x', 1.0, 3.0, num=size, unit='m')\n",
    "time = sc.linspace('time', 1.0, 2.0, num=2 * size, unit='us')\n",
    "temp = sc.array(dims=['x', 'time'], values=rng.random((size, 2 * size)), unit='K')\n",
    "temp += sc.linspace('x', 100, 105, num=size, unit='K')\n",
    "da = sc.DataArray(temp, coords={'x': x, 'time': time})\n",
    "da.name = 'temperature'  # Data array name is optional and will be used as a label"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This result in the following 2-D plot:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "da.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Plot a 1-D slice of 2-D data\n",
    "\n",
    "When slicing without a range, the dimensionality reduces.\n",
    "This can be used to, e.g., plot a 1-D slice through 2-D data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "da['time', 4].plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Transpose axes\n",
    "\n",
    "To control which dimensions are shown along which axes of the matplotlib figure transpose data before calling `plot`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "da.transpose().plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the Matplotlib \"widget\" backend is activate it is also possible to transpose the axes via a button in the toolbar."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Logarithmic scale\n",
    "\n",
    "Data can be plotted on a logarithmic scale on one or both axes.\n",
    "For the independent axis (the coordinate axis, i.e., the horizontal axis) this can be set using the `scale` option:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "da1.plot(scale={'x': 'log'})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "da.plot(scale={'x': 'log', 'time': 'log'})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note the the keys in the `scale` dict are dimension labels and *not* \"x\" and \"y\" as Matplotlib would refer to its axes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the dependent axis (the data axis, i.e., vetical axis) use the `norm` option:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "(100 * (da1 - da1.min())).plot(norm='log')"
   ]
  }
 ],
 "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"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}