Create How-tos for Subplots user guide

doc/explanation/index.md

@@ -0,0 +1,10 @@
+# Explanation
+
+Explanation guides provide in-depth understanding of key concepts in hvPlot. These guides help you understand the reasoning behind design decisions and when to use different approaches.
+
+```{toctree}
+:titlesonly:
+:hidden:
+:maxdepth: 2
+
+```

doc/how_to/create_advanced_layouts.ipynb

@@ -0,0 +1,284 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "8597e294",
+   "metadata": {},
+   "source": [
+    "# How to Create Advanced Plot Layouts\n",
+    "\n",
+    "This guide shows you how to create sophisticated plot layouts using hvPlot and Panel for more complex arrangements beyond basic subplots and grids.\n",
+    "\n",
+    "## When to use advanced layouts\n",
+    "\n",
+    "Use advanced layouts when:\n",
+    "- You need precise control over plot positioning and sizing beyond basic faceting\n",
+    "- You want to combine different types of visualizations (plots, tables, widgets)\n",
+    "- You need interactive dashboards with custom arrangements\n",
+    "- Basic subplots and grids don't provide the flexibility you need"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e4ffad99",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import hvplot.pandas  # noqa\n",
+    "import panel as pn\n",
+    "\n",
+    "pn.extension('tabulator')\n",
+    "\n",
+    "penguins = hvplot.sampledata.penguins(\"pandas\").dropna().reset_index(drop=True)\n",
+    "stocks = hvplot.sampledata.stocks(\"pandas\")\n",
+    "earthquakes = hvplot.sampledata.earthquakes(\"pandas\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "96dc3ecf",
+   "metadata": {},
+   "source": [
+    "## Using the `+` operator for side-by-side layouts"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ded095ba",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "size_opts = {\"frame_width\": 250, \"aspect\": \"square\"}\n",
+    "\n",
+    "scatter = penguins.hvplot.scatter(\n",
+    "    x='bill_length_mm',\n",
+    "    y='bill_depth_mm',\n",
+    "    color='species',\n",
+    "    title='Bill Dimensions',\n",
+    "    **size_opts\n",
+    ")\n",
+    "hist = penguins.hvplot.hist(\n",
+    "    y='body_mass_g',\n",
+    "    by='species',\n",
+    "    title='Body Mass Distribution',\n",
+    "    **size_opts\n",
+    ")\n",
+    "\n",
+    "scatter + hist"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "276c2afe",
+   "metadata": {},
+   "source": [
+    "## Using the `*` operator for overlays"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a6810b4f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "line_plot = stocks.hvplot.line(x='date', y='Apple', label=\"Line\")\n",
+    "scatter_plot = stocks[::20].hvplot.scatter(x='date', y='Apple', color=\"red\",\n",
+    "                                           size=50, alpha=0.7, label=\"Marker\")\n",
+    "\n",
+    "line_plot * scatter_plot"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f377395b",
+   "metadata": {},
+   "source": [
+    "### Complex layouts with custom arrangements"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f8ccd32a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "size_opts = {\"frame_width\": 250, \"aspect\": \"square\"}\n",
+    "\n",
+    "p1 = penguins.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm',\n",
+    "                             color='species', size=80, alpha=0.7,\n",
+    "                             title='Bill Dimensions', **size_opts)\n",
+    "\n",
+    "p2 = penguins.hvplot.scatter(x='flipper_length_mm', y='body_mass_g',\n",
+    "                             color='species', size=80, alpha=0.7,\n",
+    "                             title='Size Measurements',  **size_opts)\n",
+    "\n",
+    "p3 = penguins.hvplot.box(y='bill_length_mm', by='species',\n",
+    "                         title='Bill Length by Species',  **size_opts)\n",
+    "\n",
+    "p4 = penguins.hvplot.violin(y='body_mass_g', by='species',\n",
+    "                            title='Body Mass Distribution',  **size_opts)\n",
+    "\n",
+    "\n",
+    "layout = (p1 + p2 + p3 + p4).cols(2)\n",
+    "layout"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2105758a",
+   "metadata": {},
+   "source": [
+    "## Panel Layouts for Dashboard Creation\n",
+    "\n",
+    "Panel provides even more flexibility for creating complex dashboards:\n",
+    "\n",
+    "### Basic Panel layouts"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "df356385",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "trend_plot = stocks.hvplot.line(x='date', title='Stock Trends', height=300)\n",
+    "\n",
+    "correlation_plot = hvplot.plotting.scatter_matrix(stocks, alpha=0.5)\n",
+    "\n",
+    "# Create a Panel Column layout\n",
+    "pn.Column(trend_plot, correlation_plot)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "736a01b8",
+   "metadata": {},
+   "source": [
+    "### Combining plots with data tables"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3368427e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "summary_plot = earthquakes.hvplot.scatter(x='lon', y='lat', color='mag',\n",
+    "                                           size='mag', alpha=0.7,\n",
+    "                                           title='Earthquake Locations',\n",
+    "                                           frame_height=300, aspect='square',\n",
+    "                                           tiles=True)\n",
+    "\n",
+    "data_table = pn.widgets.Tabulator(earthquakes, height=400, width=400,\n",
+    "                                  pagination='remote', page_size=10)\n",
+    "\n",
+    "pn.Row(summary_plot, data_table)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7bf9ee23",
+   "metadata": {},
+   "source": [
+    "### Creating tabbed layouts"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b20ecfc6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "overview_tab = penguins.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm',\n",
+    "                                       color='species', size=80, alpha=0.7,\n",
+    "                                       title='Species Overview')\n",
+    "\n",
+    "detailed_tab = penguins.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm',\n",
+    "                                        by='species', subplots=True,\n",
+    "                                        width=250, height=200, alpha=0.7)\n",
+    "\n",
+    "data_tab = pn.widgets.Tabulator(penguins, pagination='remote', page_size=10)\n",
+    "\n",
+    "tabs = pn.Tabs(\n",
+    "    ('Overview', overview_tab),\n",
+    "    ('Detailed View', detailed_tab),\n",
+    "    ('Data Table', data_tab)\n",
+    ")\n",
+    "tabs"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1ff9aaa7",
+   "metadata": {},
+   "source": [
+    "### Advanced Panel layouts with custom sizing"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7a26cb55",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "main_plot = stocks.hvplot.line(x='date', y=['Apple', 'Google'], title='Main Trends')\n",
+    "\n",
+    "side_plot1 = stocks.hvplot.hist(y='Apple', title='Apple Distribution',\n",
+    "                                height=170, width=340)\n",
+    "\n",
+    "side_plot2 = stocks.hvplot.hist(y='Google', title='Google Distribution',\n",
+    "                                height=170, width=340)\n",
+    "\n",
+    "# Create complex layout\n",
+    "layout = pn.Column(\n",
+    "    main_plot,\n",
+    "    pn.Row(side_plot1, side_plot2)\n",
+    ")\n",
+    "layout"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "18e62ac5",
+   "metadata": {},
+   "source": [
+    "## Best practices for advanced layouts\n",
+    "\n",
+    "1. **Start simple**: Begin with basic layouts and add complexity gradually\n",
+    "2. **Consider screen size**: Test your layouts on different screen sizes\n",
+    "3. **Use consistent sizing**: Maintain visual harmony with consistent dimensions\n",
+    "4. **Optimize for your use case**: Choose HvPlot/HoloViews for analysis and basic faceting, Panel for dashboards\n",
+    "\n",
+    ":::{admonition} Summary\n",
+    "\n",
+    "- Use `+` operator for side-by-side layouts\n",
+    "- Use `*` operator for overlays\n",
+    "- Panel provides `Row`, `Column`, and `Tabs` for complex dashboard layouts\n",
+    "- Panel can combine plots with tables, widgets, and other components\n",
+    "- Use `responsive=True` and Panel's sizing modes for adaptive layouts\n",
+    ":::\n",
+    "\n",
+    ":::{admonition} Further Reading\n",
+    ":class: seealso\n",
+    "See the [Panel layouts tutorial](https://panel.holoviz.org/tutorials/basic/layouts.html) for more on layouting Python objects\n",
+    ":::"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}