{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Representations and Tables\n",
    "\n",
    "Scipp provides a number of options for visualizing the structure and contents of variables, data arrays, and datasets in Jupyter notebooks:\n",
    "\n",
    "- `scipp.to_html` produces a HTML representation.\n",
    "  This is also bound to `_repr_html_`, i.e., Jupyter will display this when the name of a scipp object is typed at the end of a cell.\n",
    "- `scipp.show` draws a SVG representation of the contained items and their shapes.\n",
    "- `scipp.table` outputs a table representation of 0-D and 1-D data.\n",
    "\n",
    "In all cases, these can be called with variable, data array, and dataset, as well as slices or items of any of the former.\n",
    "While the outputs are mostly self-explanatory we discuss some details below.\n",
    "\n",
    "## HTML represenation\n",
    "\n",
    "`scipp.to_html` is used to define `_repr_html_`.\n",
    "This special property is used by Jupyter in place of `__repr__`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import scipp as sc"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = sc.zeros(dims=['x'], shape=(2,))\n",
    "y = sc.zeros(dims=['y'], unit=sc.units.m, shape=(4,))\n",
    "labels = sc.zeros(dims=['y'], shape=(4,))\n",
    "d = sc.Dataset(\n",
    "    data={'a':sc.zeros(dims=['y', 'x'], shape=(3, 2), with_variances=True, unit=sc.units.angstrom)},\n",
    "    coords={'x':x, 'y':y, 'y_label':labels})\n",
    "d['b'] = d['a']\n",
    "d['c'] = 1.0 * sc.units.kg\n",
    "d['a'].attrs['x_attr'] = sc.zeros(dims=['x'], shape=(2,))\n",
    "d['b'].attrs['x_attr'] = sc.zeros(dims=['x'], shape=(2,))\n",
    "d['b'].attrs['b_attr'] = 1.2 * sc.units.m"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Simply typing the name of a variable, data array, or dataset will show the HTML representation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "d"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that (as usual) Jupyter only shows the last variable mentioned in a cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = 1\n",
    "d\n",
    "a"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case, `to_html` can be used to retain the HTML view, e.g., to show multiple objects in a single cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.to_html(d['a'])\n",
    "sc.to_html(d['c'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Typing the scipp module name at the end of a cell yields an HTML view of all scipp objects (variables, data arrays, and datasets):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## SVG representation\n",
    "\n",
    "`scipp.show` works similar to `scipp.to_html`.\n",
    "It should be noted that if a dimension extent is large, `show` will truncate it to avoid generation of massive and unreadable SVGs.\n",
    "Objects with more than three dimensions are not supported and will result in an error message."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.show(d)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Table representation\n",
    "\n",
    "`scipp.table` works similar to `scipp.to_html` and `scipp.show`.\n",
    "Objects with more than one dimension per variable are not supported and are omitted in the output:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.table(d)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In such cases slicing can be used to produce tables from higher-dimensional entries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.table(d['a']['x', 0])"
   ]
  }
 ],
 "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.9.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}