diff --git a/doc/explanation/index.md b/doc/explanation/index.md new file mode 100644 index 000000000..d35053c02 --- /dev/null +++ b/doc/explanation/index.md @@ -0,0 +1,11 @@ +# 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 + +statistical_plot_types +``` diff --git a/doc/explanation/statistical_plot_types.ipynb b/doc/explanation/statistical_plot_types.ipynb new file mode 100644 index 000000000..19abe1579 --- /dev/null +++ b/doc/explanation/statistical_plot_types.ipynb @@ -0,0 +1,612 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "1aaf9273", + "metadata": {}, + "source": [ + "# Understanding hvPlot's Statistical Plot Types\n", + "\n", + "hvPlot provides several statistical plotting functions that go beyond basic charts. Each plot type reveals different aspects of your data and has specific strengths and limitations. This guide explains when and why to use each type.\n", + "\n", + "## Load sample data for examples" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b8294f32", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.pandas # noqa\n", + "from sklearn.preprocessing import StandardScaler\n", + "import pandas as pd\n", + "\n", + "\n", + "penguins = hvplot.sampledata.penguins(\"pandas\").dropna()\n", + "stocks = hvplot.sampledata.stocks(\"pandas\")\n", + "\n", + "# Prepare data for multivariate examples\n", + "num_cols = ['bill_length_mm', 'bill_depth_mm', 'flipper_length_mm', 'body_mass_g']\n", + "penguins_subset = penguins[['species'] + num_cols]#.sample(100, random_state=42)\n", + "\n", + "# Normalized version for some plots\n", + "scaler = StandardScaler()\n", + "scaled_features = scaler.fit_transform(penguins_subset[num_cols])\n", + "penguins_scaled = pd.DataFrame(scaled_features, columns=num_cols)\n", + "penguins_scaled['species'] = penguins_subset['species'].values" + ] + }, + { + "cell_type": "markdown", + "id": "3f9e7bfb-276c-4746-8ec9-9d58a7f09d91", + "metadata": {}, + "source": [ + "## Distribution Analysis\n", + "\n", + "Understanding the distribution of your data is fundamental to statistical analysis. hvPlot provides several plot types that reveal different aspects of data distributions:\n", + "\n", + "### Histograms\n", + "\n", + "**What it shows:** Frequency distribution of values in a single variable\n", + "\n", + "**Strengths:**\n", + "- Clear visualization of data distribution shape\n", + "- Easy to identify skewness, modality, and outliers\n", + "- Familiar and intuitive for most users\n", + "- Customizable bin sizes for different levels of detail\n", + "\n", + "**Best for:** Understanding the overall shape and spread of a single variable, identifying distribution patterns\n", + "\n", + "**Limitations:** Can be sensitive to bin size choices; doesn't show relationships between variables" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b1fb63ce-738d-49fe-ae3d-e21918769e88", + "metadata": {}, + "outputs": [], + "source": [ + "# Example: Histogram showing distribution shape\n", + "\n", + "penguins.hvplot.hist(y='body_mass_g', by='species', alpha=0.6, bins=20)" + ] + }, + { + "cell_type": "markdown", + "id": "98fdcf50", + "metadata": {}, + "source": [ + "Notice how each species shows a different distribution shape: Adelie penguins have a wider spread and lower average body mass, while Gentoo penguins are clearly heavier with less overlap with the other species." + ] + }, + { + "cell_type": "markdown", + "id": "2ecfb43c", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "See the reference guide for [Histograms](../ref/api/manual/hvplot.hvPlot.hist.ipynb)\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "5189025d-5a08-485e-beaf-f8af6f60b3ef", + "metadata": {}, + "source": [ + "### Box Plots\n", + "\n", + "**What it shows:** Five-number summary (minimum, Q1, median, Q3, maximum) plus outliers\n", + "\n", + "**Strengths:**\n", + "- Compact summary of distribution characteristics\n", + "- Excellent for comparing distributions across groups\n", + "- Clearly identifies outliers and quartile ranges\n", + "- Robust to extreme values\n", + "\n", + "**Best for:** Comparing distributions between groups, identifying outliers, understanding data spread and central tendency\n", + "\n", + "**Limitations:** Hides detailed distribution shape; can miss bimodal or complex distributions" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ea44af35-33de-4b54-8bee-24e216d2583f", + "metadata": {}, + "outputs": [], + "source": [ + "# Example: Box plot comparing distributions across groups\n", + "penguins.hvplot.box(y='flipper_length_mm', by='species')" + ] + }, + { + "cell_type": "markdown", + "id": "6e3e2afd-48bb-4895-9a9a-ffa1069a6cd6", + "metadata": {}, + "source": [ + "The box plots provide a compact summary showing that Gentoo penguins have notably longer flippers with less variability, while Adelie penguins show the shortest flipper lengths. The boxes show quartiles, and any points beyond the whiskers would indicate outliers." + ] + }, + { + "cell_type": "markdown", + "id": "0b83df85-8346-4536-899c-d81bb17cc314", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "See the reference guide for [Box plots](../ref/api/manual/hvplot.hvPlot.box.ipynb)\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "78b9159f-dcbd-431b-9c36-87084ba83cc9", + "metadata": {}, + "source": [ + "### Violin Plots\n", + "\n", + "**What it shows:** Combination of box plot information with kernel density estimation\n", + "\n", + "**Strengths:**\n", + "- Shows both summary statistics and distribution shape\n", + "- Reveals multimodal distributions that box plots miss\n", + "- Good for comparing complex distributions across groups\n", + "- More informative than box plots for understanding distribution shape\n", + "\n", + "**Best for:** Comparing detailed distribution shapes across groups, when you need both summary statistics and distribution density\n", + "\n", + "**Limitations:** Can be more complex to interpret; kernel density estimation may smooth over important details" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "47816f95", + "metadata": {}, + "outputs": [], + "source": [ + "# Example: Violin plot showing detailed distribution shapes\n", + "penguins.hvplot.violin(y='bill_length_mm', by='species')" + ] + }, + { + "cell_type": "markdown", + "id": "168e1418-cc07-4cd5-ae37-dfcab390f072", + "metadata": {}, + "source": [ + "The violin plots reveal the full distribution shape within each group. Notice how Chinstrap penguins show a slightly bimodal distribution in bill length, while Gentoo and Adelie show more symmetric, unimodal distributions. The white dot shows the median, and the thick black bar represents the interquartile range." + ] + }, + { + "cell_type": "markdown", + "id": "00cf02bf-60d7-44e3-b357-8f4ed21a6967", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "See the reference guide for [Violin plots](../ref/api/manual/hvplot.hvPlot.violin.ipynb)\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "098c30b2-5aff-48b1-be0f-90d32065ee0e", + "metadata": {}, + "source": [ + "### Heatmaps\n", + "\n", + "**What it shows:** Matrix of values represented as colors, often used for correlation matrices or 2D binned data\n", + "\n", + "**Strengths:**\n", + "- Excellent for visualizing correlation matrices\n", + "- Clear representation of patterns in 2D gridded data\n", + "- Good for showing relationships across many variable pairs simultaneously\n", + "- Effective for identifying clusters and patterns in matrix data\n", + "\n", + "**Best for:** Visualizing correlation matrices, 2D binned data, confusion matrices, or any matrix-structured data\n", + "\n", + "**Limitations:** Requires gridded or matrix-structured data; can lose individual data point information" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e897a9ba", + "metadata": {}, + "outputs": [], + "source": [ + "# Example: Heatmap showing correlation matrix\n", + "correlation_matrix = penguins[num_cols].corr()\n", + "correlation_matrix.hvplot.heatmap(cmap='coolwarm')" + ] + }, + { + "cell_type": "markdown", + "id": "f0940211", + "metadata": {}, + "source": [ + "The heatmap reveals strong positive correlations (darker red) between flipper length and body mass, and between bill length and bill depth. These relationships suggest that larger penguins tend to have proportionally larger features overall." + ] + }, + { + "cell_type": "markdown", + "id": "fa0a0db3", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "See the reference guide for [Heatmaps](../ref/api/manual/hvplot.hvPlot.heatmap.ipynb)\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "acea8c30-54ef-4359-911b-1e637d3c5cf7", + "metadata": {}, + "source": [ + "### KDE (Kernel Density Estimation) Plots\n", + "\n", + "**What it shows:** Smooth density estimation of data distribution using kernel functions\n", + "\n", + "**Strengths:**\n", + "- Provides smooth, continuous representation of data density\n", + "- Good for overlaying multiple distributions for comparison\n", + "- Less sensitive to bin choices than histograms\n", + "- Effective for showing distribution shape and identifying modes\n", + "\n", + "**Best for:** Comparing multiple distributions, showing smooth density estimates, identifying distribution modes\n", + "\n", + "**Limitations:** Bandwidth selection can affect results; may smooth over important details; computationally more expensive than histograms" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "dcf6eb80", + "metadata": {}, + "outputs": [], + "source": [ + "# Example: KDE plot comparing smooth density distributions\n", + "penguins.hvplot.kde(y='body_mass_g', by='species', alpha=0.6)" + ] + }, + { + "cell_type": "markdown", + "id": "82eb2970", + "metadata": {}, + "source": [ + "The smooth KDE curves make it easy to compare distribution shapes across species. Note how Gentoo penguins show a distinct peak at higher body mass values, while Adelie and Chinstrap distributions overlap more significantly." + ] + }, + { + "cell_type": "markdown", + "id": "fdfb9a7e", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "See the reference guide for [KDE plots](../ref/api/manual/hvplot.hvPlot.kde.ipynb)\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "b8b10a4b", + "metadata": {}, + "source": [ + "## Multivariate Data Visualization\n", + "\n", + "When working with datasets containing multiple variables, understanding relationships between all dimensions becomes challenging. hvPlot offers three complementary approaches:" + ] + }, + { + "cell_type": "markdown", + "id": "5f52ca70", + "metadata": {}, + "source": [ + "### Scatter Matrix\n", + "\n", + "**What it shows:** All pairwise relationships between numeric variables\n", + "\n", + "**Strengths:**\n", + "- Provides quantitative insights into correlations\n", + "- Interactive linking allows exploration across all variable pairs\n", + "- Familiar scatter plot format is easy to interpret\n", + "\n", + "**Best for:** Identifying correlations, outliers, and clustering patterns between variable pairs\n", + "\n", + "**Limitations:** Can become cluttered with many variables; doesn't show patterns across all dimensions simultaneously" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "06816511", + "metadata": {}, + "outputs": [], + "source": [ + "# Example: Scatter matrix showing pairwise relationships\n", + "hvplot.scatter_matrix(penguins_subset, c=\"species\", alpha=0.6)" + ] + }, + { + "cell_type": "markdown", + "id": "b5e79450", + "metadata": {}, + "source": [ + "The scatter matrix shows that Gentoo penguins (orange) form distinct clusters in most variable pairs, particularly visible in flipper length vs body mass. The diagonal histograms reveal the distribution of each individual variable." + ] + }, + { + "cell_type": "markdown", + "id": "8f31353b", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "See the reference guide for [Scatter Matrix](../ref/api/manual/hvplot.plotting.scatter_matrix.ipynb)\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "2d894a15", + "metadata": {}, + "source": [ + "### Parallel Coordinates\n", + "\n", + "**What it shows:** Patterns and relationships across all variables simultaneously\n", + "\n", + "**Strengths:**\n", + "- Reveals patterns across all dimensions at once\n", + "- Excellent for identifying distinct groups or classes\n", + "- Shows which variables contribute most to group differences\n", + "\n", + "**Best for:** Comparing groups across multiple dimensions, identifying which variables distinguish different classes\n", + "\n", + "**Limitations:** Can be difficult to read with many observations; requires some practice to interpret effectively" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "de380135", + "metadata": {}, + "outputs": [], + "source": [ + "# Example: Parallel coordinates showing patterns across all dimensions\n", + "hvplot.parallel_coordinates(penguins_scaled, \"species\", alpha=0.7)" + ] + }, + { + "cell_type": "markdown", + "id": "8e9dfda1", + "metadata": {}, + "source": [ + "The parallel coordinates plot reveals that Gentoo penguins consistently have higher values across most features (especially flipper length and body mass), while Adelie and Chinstrap show more similar patterns with some overlap." + ] + }, + { + "cell_type": "markdown", + "id": "29afd03f", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "See the reference guide for [Parallel Coordinates](../ref/api/manual/hvplot.plotting.parallel_coordinates.ipynb)\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "9d1ba8b8", + "metadata": {}, + "source": [ + "### Andrews Curves\n", + "\n", + "**What it shows:** Aggregate differences between classes using Fourier series representation\n", + "\n", + "**Strengths:**\n", + "- Smooth curves make group differences visually apparent\n", + "- Good for showing overall class separation\n", + "- Less cluttered than parallel coordinates with many observations\n", + "\n", + "**Best for:** Visualizing overall differences between classes when you care more about separation than specific variable contributions\n", + "\n", + "**Limitations:** Provides less quantitative insight into which specific features drive differences; mathematical transformation makes individual variable contributions less interpretable" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "45b8b826", + "metadata": {}, + "outputs": [], + "source": [ + "# Example: Andrews curves showing class separation\n", + "hvplot.andrews_curves(penguins_scaled, \"species\", samples=30)" + ] + }, + { + "cell_type": "markdown", + "id": "959f3215", + "metadata": {}, + "source": [ + "The Andrews curves transform the multi-dimensional data into smooth periodic functions. Notice how Gentoo penguins form a distinct curve pattern that's clearly separated from the other two species, confirming their distinctiveness across multiple dimensions." + ] + }, + { + "cell_type": "markdown", + "id": "6bd0fe5e", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "See the reference guide for [Andrews Curves](../ref/api/manual/hvplot.plotting.andrews_curves.ipynb)\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "be99e06a-88fb-4761-97c6-cc6854cba2bb", + "metadata": {}, + "source": [ + "## Bivariate Analysis\n", + "\n", + "Understanding relationships between pairs of variables requires specialized visualization approaches. hvPlot provides several methods for bivariate exploration:\n", + "\n", + "### Bivariate Plots\n", + "\n", + "**What it shows:** Joint distribution and relationship between two continuous variables\n", + "\n", + "**Strengths:**\n", + "- Combines scatter plot with marginal distributions\n", + "- Shows both individual variable distributions and their relationship\n", + "- Excellent for understanding correlation patterns and outliers\n", + "- Provides comprehensive view of two-variable relationships\n", + "\n", + "**Best for:** Exploring relationships between two continuous variables, understanding joint distributions\n", + "\n", + "**Limitations:** Limited to two variables at a time; can become cluttered with many data points" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6b1bb8b0", + "metadata": {}, + "outputs": [], + "source": [ + "# Example: Bivariate plot showing joint distribution\n", + "penguins.hvplot.bivariate('bill_length_mm', 'flipper_length_mm', by='species')" + ] + }, + { + "cell_type": "markdown", + "id": "665b752b", + "metadata": {}, + "source": [ + "The bivariate plot combines scatter plots with marginal histograms, showing both the relationship between bill length and flipper length and the individual distributions. The clear clustering by species in the main plot confirms these measurements are good discriminators." + ] + }, + { + "cell_type": "markdown", + "id": "7e34c3cb", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "See the reference guide for [Bivariate plots](../ref/api/manual/hvplot.hvPlot.bivariate.ipynb)\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "b925b654", + "metadata": {}, + "source": [ + "## Time Series Analysis\n", + "\n", + "### Lag Plots\n", + "\n", + "**What it shows:** Relationship between current values and values at a previous time point\n", + "\n", + "**Strengths:**\n", + "- Reveals autocorrelation patterns in time series\n", + "- Identifies volatility and stability in temporal data\n", + "- Helps detect seasonal or cyclical patterns\n", + "\n", + "**Best for:** Understanding temporal dependencies, comparing volatility between different time series, detecting autocorrelation\n", + "\n", + "**Key insight:** Tight clustering around the diagonal indicates stable, predictable behavior; scattered points indicate high volatility or weak temporal correlation" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f42e0ac3", + "metadata": {}, + "outputs": [], + "source": [ + "# Example: Lag plot comparing stock volatility\n", + "stock_subset = stocks[['Apple', 'Microsoft']].iloc[:200] # Subset for clarity\n", + "hvplot.lag_plot(stock_subset, lag=30, alpha=0.6)" + ] + }, + { + "cell_type": "markdown", + "id": "a8b1db2d", + "metadata": {}, + "source": [ + "The lag plot shows the relationship between stock prices and their values 30 days earlier. Points scattered widely from the diagonal indicate high volatility, while points close to the diagonal suggest more predictable, stable price movements." + ] + }, + { + "cell_type": "markdown", + "id": "7b82506d", + "metadata": {}, + "source": [ + ":::{seealso}\n", + "See the reference guide for [Lag plots](../ref/api/manual/hvplot.plotting.lag_plot.ipynb)\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "3969834d", + "metadata": {}, + "source": [ + "## Interactive Advantages\n", + "\n", + "All hvPlot statistical plots benefit from Bokeh's interactive features:\n", + "\n", + "- **Shared axes:** Multiple subplots automatically share the same axis ranges, so zooming or panning in one subplot synchronizes across all related plots\n", + "- **Linked zooming/panning:** Coordinated exploration across multiple plot panels\n", + "- **Hover tooltips:** Detailed information about individual data points\n", + "\n", + "These features make hvPlot's statistical plots significantly more powerful than static alternatives for data exploration." + ] + }, + { + "cell_type": "markdown", + "id": "5dd00ffb", + "metadata": {}, + "source": [ + "## Choosing the Right Plot Type\n", + "\n", + "| Goal | Recommended Plot | Why |\n", + "|------|------------------|-----|\n", + "| Find correlations between variable pairs | Scatter Matrix | Shows quantitative relationships clearly |\n", + "| Compare groups across many variables | Parallel Coordinates | Reveals which variables distinguish groups |\n", + "| Show overall class separation | Andrews Curves | Emphasizes aggregate differences |\n", + "| Analyze temporal dependencies | Lag Plot | Designed specifically for time series patterns |\n", + "| Understand single variable distribution | Histogram or KDE | Histograms for frequency, KDE for smooth density |\n", + "| Compare distributions across groups | Box Plot or Violin Plot | Box plots for simple comparisons, violin plots for detailed shapes |\n", + "| Identify outliers | Box Plot | Explicitly shows outliers beyond quartile ranges |\n", + "| Detect multimodal distributions | Violin Plot, KDE, or Histogram | Multiple approaches reveal different aspects of modes |\n", + "| Quick distribution summary | Box Plot | Compact five-number summary |\n", + "| Detailed distribution analysis | Violin Plot | Combines summary statistics with full distribution shape |\n", + "| Explore two-variable relationships | Bivariate Plot | Shows joint distribution and marginal distributions |\n", + "| Visualize correlation patterns | Heatmap | Clear matrix representation of correlations |\n", + "| Compare multiple distributions smoothly | KDE Plot | Smooth density curves for easy comparison |\n", + "| Analyze matrix or gridded data | Heatmap | Designed specifically for matrix visualization |\n", + "| Detect outliers in multivariate data | Scatter Matrix + Parallel Coordinates | Combine pairwise and multi-dimensional views |" + ] + }, + { + "cell_type": "markdown", + "id": "41d345c1", + "metadata": {}, + "source": [ + ":::{admonition} Next Steps\n", + ":class: seealso\n", + "Explore more visualization options at [holoviews.org](https://holoviews.org)\n", + ":::" + ] + } + ], + "metadata": { + "language_info": { + "name": "python", + "pygments_lexer": "ipython3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/doc/how_to/index.md b/doc/how_to/index.md new file mode 100644 index 000000000..f1c886fff --- /dev/null +++ b/doc/how_to/index.md @@ -0,0 +1,10 @@ +# How-To Guides + +How-to guides are practical, problem-oriented instructions that help you accomplish specific tasks with hvPlot. These guides assume you're already familiar with the basics and want to solve particular problems or achieve specific goals. + +```{toctree} +:titlesonly: +:hidden: +:maxdepth: 2 + +``` diff --git a/doc/index.md b/doc/index.md index e868f5cec..5340961fd 100644 --- a/doc/index.md +++ b/doc/index.md @@ -434,8 +434,10 @@ align: center Tutorials User Guide +How-To Guides Gallery Reference +Explanation Developer Guide Releases Roadmap