document vega dataframe support (#7024)

examples/reference/panes/Vega.ipynb

@@ -6,37 +6,43 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "import pandas as pd\n",
     "import panel as pn\n",
+    "\n",
     "pn.extension('vega')"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The ``Vega`` pane renders Vega-based plots (including those from Altair) inside a panel. It optimizes the plot rendering by using binary serialization for any array data found on the Vega/Altair object, providing huge speedups over the standard JSON serialization employed by Vega natively. Note that to use the ``Vega`` pane in the notebook the Panel extension has to be loaded with 'vega' as an argument to ensure that vega.js is initialized.\n",
+    "The ``Vega`` pane renders Vega-based plots (including those from Altair) inside a panel. It optimizes plot rendering by using binary serialization for any array data found in the Vega/Altair object, providing significant speedups over the standard JSON serialization employed by Vega natively. Note that to use the ``Vega`` pane in the notebook, the Panel extension must be loaded with 'vega' as an argument to ensure that vega.js is initialized.\n",
     "\n",
     "#### Parameters:\n",
     "\n",
-    "For details on other options for customizing the component see the [layout](../../how_to/layout/index.md) and [styling](../../how_to/styling/index.md) how-to guides.\n",
+    "For details on other options for customizing the component, see the [layout](../../how_to/layout/index.md) and [styling](../../how_to/styling/index.md) how-to guides.\n",
     "\n",
     "* **``debounce``** (int or dict): The debounce timeout to apply to selection events, either specified as a single integer value (in milliseconds) or a dictionary that declares a debounce value per event. Debouncing ensures that events are only dispatched N milliseconds after a user is done interacting with the plot.\n",
-    "* **``object``** (dict or altair Chart): Either a dictionary containing a Vega or Vega-Lite plot specification, or an Altair Chart\n",
-    "* **``theme``** (str): A theme to apply to the plot, must be one of 'excel', 'ggplot2', 'quartz', 'vox', 'fivethirtyeight', 'dark', 'latimes', 'urbaninstitute', 'googlecharts'.\n",
-    "* **``show_actions``** (boolean): Whether to show chart actions menu such as save, edit etc.\n",
+    "* **``object``** (dict or altair Chart): Either a dictionary containing a Vega or Vega-Lite plot specification, or an Altair Chart.\n",
+    "* **``show_actions``** (boolean): Whether to show the chart actions menu, such as save, edit, etc.\n",
+    "* **``theme``** (str): A theme to apply to the plot. Must be one of 'excel', 'ggplot2', 'quartz', 'vox', 'fivethirtyeight', 'dark', 'latimes', 'urbaninstitute', or 'googlecharts'.\n",
     "\n",
     "Readonly parameters:\n",
     "\n",
-    "* **``selection``** (Selection): The Selection object exposes parameters which reflect the selections declared on the plot into Python. \n",
+    "* **``selection``** (Selection): The Selection object exposes parameters that reflect the selections declared on the plot into Python.\n",
+    "\n",
+    "___\n",
     "\n",
-    "___"
+    "The ``Vega`` pane supports both [`vega`](https://vega.github.io/vega/docs/specification/) and [`vega-lite`](https://vega.github.io/vega-lite/docs/spec.html) specifications, which may be provided in raw form (i.e., a dictionary) or by defining an ``altair`` plot.\n",
+    "\n",
+    "---"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The ``Vega`` pane supports both ``vega`` and ``vega-lite`` specs which may be provided in a raw form (i.e. a dictionary) or by defining an ``altair`` plot.\n",
+    "### Vega and Vega-lite\n",
     "\n",
     "To display ``vega`` and ``vega-lite`` specification simply construct a ``Vega`` pane directly or pass it to ``pn.panel``:"
    ]
@@ -91,7 +97,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "vgl_pane.object = {\n",
+    "vega_disasters = {\n",
     "  \"$schema\": \"https://vega.github.io/schema/vega-lite/v5.json\",\n",
     "  \"data\": {\n",
     "    \"url\": \"https://raw.githubusercontent.com/vega/vega/master/docs/data/disasters.csv\"\n",
@@ -127,13 +133,32 @@
     "    },\n",
     "    \"color\": {\"field\": \"Entity\", \"type\": \"nominal\", \"legend\": None}\n",
     "  }\n",
-    "}"
+    "}\n",
+    "vgl_pane.object = vega_disasters"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Lets reset the plot back to the original:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "vgl_pane.object = vegalite"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "#### Responsive Sizing\n",
+    "\n",
     "The `vega-lite` specification can also be responsively sized by declaring the width or height to match the container:"
    ]
   },
@@ -143,7 +168,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "responsive_spec = dict(vgl_pane.object, width='container')\n",
+    "responsive_spec = dict(vega_disasters, width='container', title=\"Responsive Plot\")\n",
     "\n",
     "vgl_responsive_pane = pn.pane.Vega(responsive_spec)\n",
     "vgl_responsive_pane"
@@ -156,6 +181,36 @@
     "Please note that the `vega` specification does not support setting `width` and `height` to `container`."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### DataFrame Data Values\n",
+    "\n",
+    "For convenience we support a Pandas DataFrame as `data` `values`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "dataframe_spec = {\n",
+    "    \"title\": \"A Simple Bar Chart from a Pandas DataFrame\",\n",
+    "    'config': {\n",
+    "        'mark': {'tooltip': None},\n",
+    "        'view': {'height': 200, 'width': 500}\n",
+    "    },\n",
+    "    'data': {'values': pd.DataFrame({'x': ['A', 'B', 'C', 'D', 'E'], 'y': [5, 3, 6, 7, 2]})},\n",
+    "    'mark': 'bar',\n",
+    "    'encoding': {'x': {'type': 'ordinal', 'field': 'x'},\n",
+    "                 'y': {'type': 'quantitative', 'field': 'y'}},\n",
+    "    '$schema': 'https://vega.github.io/schema/vega-lite/v3.2.1.json'\n",
+    "}\n",
+    "pn.pane.Vega(dataframe_spec)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},