xarray-plotly 0.0.7__tar.gz → 0.0.8__tar.gz

{xarray_plotly-0.0.7 → xarray_plotly-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xarray_plotly
-Version: 0.0.7
+Version: 0.0.8
 Summary: Interactive Plotly Express plotting accessor for xarray
 Author: Felix
 License: MIT

xarray_plotly-0.0.8/docs/examples/fast_bar.ipynb

@@ -0,0 +1,297 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Fast Bar Charts\n",
+    "\n",
+    "The `fast_bar()` method creates bar-like visualizations using stacked areas. This renders much faster than actual bar charts for large datasets because it uses a single polygon per trace instead of individual rectangles."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import xarray as xr\n",
+    "\n",
+    "from xarray_plotly import config, xpx\n",
+    "\n",
+    "config.notebook()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2",
+   "metadata": {},
+   "source": [
+    "## Basic Example"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Quarterly revenue data by product and region\n",
+    "np.random.seed(42)\n",
+    "da = xr.DataArray(\n",
+    "    np.random.rand(4, 3, 2) * 100 + 50,\n",
+    "    dims=[\"quarter\", \"product\", \"region\"],\n",
+    "    coords={\n",
+    "        \"quarter\": [\"Q1\", \"Q2\", \"Q3\", \"Q4\"],\n",
+    "        \"product\": [\"Widgets\", \"Gadgets\", \"Gizmos\"],\n",
+    "        \"region\": [\"North\", \"South\"],\n",
+    "    },\n",
+    "    name=\"revenue\",\n",
+    ")\n",
+    "\n",
+    "xpx(da).fast_bar()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Comparison with regular bar()\n",
+    "xpx(da).bar()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5",
+   "metadata": {},
+   "source": [
+    "## With Faceting"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "xpx(da).fast_bar(facet_col=\"region\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7",
+   "metadata": {},
+   "source": [
+    "## With Animation"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Multi-year data for animation\n",
+    "np.random.seed(123)\n",
+    "da_anim = xr.DataArray(\n",
+    "    np.random.rand(4, 3, 5) * 100 + 20,\n",
+    "    dims=[\"quarter\", \"product\", \"year\"],\n",
+    "    coords={\n",
+    "        \"quarter\": [\"Q1\", \"Q2\", \"Q3\", \"Q4\"],\n",
+    "        \"product\": [\"Widgets\", \"Gadgets\", \"Gizmos\"],\n",
+    "        \"year\": [2020, 2021, 2022, 2023, 2024],\n",
+    "    },\n",
+    "    name=\"revenue\",\n",
+    ")\n",
+    "\n",
+    "xpx(da_anim).fast_bar(animation_frame=\"year\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9",
+   "metadata": {},
+   "source": [
+    "## Faceting + Animation"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "10",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 4D data: quarter x product x region x year\n",
+    "np.random.seed(456)\n",
+    "da_4d = xr.DataArray(\n",
+    "    np.random.rand(4, 3, 2, 4) * 80 + 30,\n",
+    "    dims=[\"quarter\", \"product\", \"region\", \"year\"],\n",
+    "    coords={\n",
+    "        \"quarter\": [\"Q1\", \"Q2\", \"Q3\", \"Q4\"],\n",
+    "        \"product\": [\"Widgets\", \"Gadgets\", \"Gizmos\"],\n",
+    "        \"region\": [\"North\", \"South\"],\n",
+    "        \"year\": [2021, 2022, 2023, 2024],\n",
+    "    },\n",
+    "    name=\"revenue\",\n",
+    ")\n",
+    "\n",
+    "xpx(da_4d).fast_bar(facet_col=\"region\", animation_frame=\"year\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "11",
+   "metadata": {},
+   "source": [
+    "## Positive and Negative Values\n",
+    "\n",
+    "`fast_bar()` classifies each trace by its values:\n",
+    "- **Purely positive** → stacks upward\n",
+    "- **Purely negative** → stacks downward\n",
+    "- **Mixed signs** → warning + dashed line (use `bar()` instead)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "12",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Profit (positive) and Loss (negative) - stacks correctly\n",
+    "np.random.seed(789)\n",
+    "da_split = xr.DataArray(\n",
+    "    np.column_stack(\n",
+    "        [\n",
+    "            np.random.rand(6) * 80 + 20,  # Revenue: positive\n",
+    "            -np.random.rand(6) * 50 - 10,  # Costs: negative\n",
+    "        ]\n",
+    "    ),\n",
+    "    dims=[\"month\", \"category\"],\n",
+    "    coords={\n",
+    "        \"month\": [\"Jan\", \"Feb\", \"Mar\", \"Apr\", \"May\", \"Jun\"],\n",
+    "        \"category\": [\"Revenue\", \"Costs\"],\n",
+    "    },\n",
+    "    name=\"financials\",\n",
+    ")\n",
+    "\n",
+    "xpx(da_split).fast_bar()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "13",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# With animation - sign classification is consistent across frames\n",
+    "np.random.seed(321)\n",
+    "da_split_anim = xr.DataArray(\n",
+    "    np.stack(\n",
+    "        [\n",
+    "            np.column_stack([np.random.rand(6) * 80 + 20, -np.random.rand(6) * 50 - 10])\n",
+    "            for _ in range(4)\n",
+    "        ],\n",
+    "        axis=-1,\n",
+    "    ),\n",
+    "    dims=[\"month\", \"category\", \"year\"],\n",
+    "    coords={\n",
+    "        \"month\": [\"Jan\", \"Feb\", \"Mar\", \"Apr\", \"May\", \"Jun\"],\n",
+    "        \"category\": [\"Revenue\", \"Costs\"],\n",
+    "        \"year\": [2021, 2022, 2023, 2024],\n",
+    "    },\n",
+    "    name=\"financials\",\n",
+    ")\n",
+    "\n",
+    "xpx(da_split_anim).fast_bar(animation_frame=\"year\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "14",
+   "metadata": {},
+   "source": [
+    "## Mixed Sign Warning\n",
+    "\n",
+    "When a trace has both positive and negative values, `fast_bar()` shows a warning and displays it as a dashed line:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "15",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Both columns have mixed signs - triggers warning\n",
+    "da_mixed = xr.DataArray(\n",
+    "    np.array(\n",
+    "        [\n",
+    "            [50, -30],\n",
+    "            [-40, 60],\n",
+    "            [30, -50],\n",
+    "            [-20, 40],\n",
+    "        ]\n",
+    "    ),\n",
+    "    dims=[\"month\", \"category\"],\n",
+    "    coords={\n",
+    "        \"month\": [\"Jan\", \"Feb\", \"Mar\", \"Apr\"],\n",
+    "        \"category\": [\"A\", \"B\"],\n",
+    "    },\n",
+    ")\n",
+    "\n",
+    "# This will show a warning\n",
+    "xpx(da_mixed).fast_bar()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "16",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# For mixed data, use bar() instead\n",
+    "xpx(da_mixed).bar()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "17",
+   "metadata": {},
+   "source": [
+    "## When to Use\n",
+    "\n",
+    "| Method | Use when... |\n",
+    "|--------|-------------|\n",
+    "| `fast_bar()` | Large datasets, animations, performance matters, data is same-sign per trace |\n",
+    "| `bar()` | Need grouped bars, pattern fills, or have mixed +/- values per trace |\n",
+    "| `area()` | Want smooth continuous fills |"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

xarray_plotly-0.0.8/docs/examples/manipulation.ipynb

@@ -0,0 +1,383 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Figure Manipulation\n",
+    "\n",
+    "After creating a figure with `xpx()`, you can manipulate it using standard Plotly methods.\n",
+    "This notebook shows what works out of the box, and where `update_traces` from xarray-plotly helps."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import plotly.express as px\n",
+    "import xarray as xr\n",
+    "\n",
+    "from xarray_plotly import config, update_traces, xpx\n",
+    "\n",
+    "config.notebook()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 4D DataArray: scenario x metric x year x country\n",
+    "df_gap = px.data.gapminder()\n",
+    "countries = [\"United States\", \"China\", \"Germany\", \"Brazil\"]\n",
+    "metrics = [\"lifeExp\", \"gdpPercap\"]\n",
+    "\n",
+    "# Build base 3D array (metric x year x country)\n",
+    "arrays = []\n",
+    "for metric in metrics:\n",
+    "    df_pivot = df_gap[df_gap[\"country\"].isin(countries)].pivot(\n",
+    "        index=\"year\", columns=\"country\", values=metric\n",
+    "    )\n",
+    "    arrays.append(df_pivot.values)\n",
+    "\n",
+    "base_3d = np.stack(arrays)\n",
+    "\n",
+    "# Add scenario dimension (4D): original + 10% higher\n",
+    "scenarios = [\"baseline\", \"optimistic\"]\n",
+    "data_4d = np.stack([base_3d, base_3d * 1.1])\n",
+    "\n",
+    "da = xr.DataArray(\n",
+    "    data_4d,\n",
+    "    dims=[\"scenario\", \"metric\", \"year\", \"country\"],\n",
+    "    coords={\n",
+    "        \"scenario\": scenarios,\n",
+    "        \"metric\": metrics,\n",
+    "        \"year\": df_pivot.index.tolist(),\n",
+    "        \"country\": df_pivot.columns.tolist(),\n",
+    "    },\n",
+    "    name=\"value\",\n",
+    ")\n",
+    "da"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Standard Plotly Methods\n",
+    "\n",
+    "All standard Plotly manipulation methods work on figures created with `xpx()`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Simple 2D slice\n",
+    "fig = xpx(da.sel(scenario=\"baseline\", metric=\"lifeExp\")).line()\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Layout\n",
+    "fig.update_layout(title=\"Life Expectancy Over Time\", template=\"plotly_white\")\n",
+    "\n",
+    "# All traces\n",
+    "fig.update_traces(line_width=3)\n",
+    "\n",
+    "# Specific trace by name\n",
+    "fig.update_traces(line_dash=\"dot\", selector={\"name\": \"Germany\"})\n",
+    "\n",
+    "# Axes\n",
+    "fig.update_xaxes(title=\"Year\", showgrid=False)\n",
+    "fig.update_yaxes(title=\"Life Expectancy (years)\", range=[40, 85])\n",
+    "\n",
+    "# Reference line\n",
+    "fig.add_hline(y=70, line_dash=\"dash\", line_color=\"gray\", annotation_text=\"Target\")\n",
+    "\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Faceted Plots\n",
+    "\n",
+    "`update_traces`, `update_xaxes`, `update_yaxes` work across all facets."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Facet by metric, color by country\n",
+    "fig = xpx(da.sel(scenario=\"baseline\")).line(facet_col=\"metric\")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Update ALL traces across all facets\n",
+    "fig.update_traces(line_width=2)\n",
+    "\n",
+    "# Update ALL axes\n",
+    "fig.update_xaxes(showgrid=False)\n",
+    "\n",
+    "# Target specific facet (1-indexed)\n",
+    "fig.update_yaxes(type=\"log\", col=2)  # log scale only for gdpPercap\n",
+    "\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9",
+   "metadata": {},
+   "source": [
+    "### Grid layout with facet_row"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "10",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 2x2 grid: scenario x metric\n",
+    "fig = xpx(da).line(facet_col=\"metric\", facet_row=\"scenario\")\n",
+    "\n",
+    "fig.update_traces(line_width=2)\n",
+    "fig.update_yaxes(type=\"log\", col=2)  # log scale for gdpPercap column\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "11",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Animation: The Pain Point\n",
+    "\n",
+    "Plotly's `fig.update_traces()` does **not** update animation frames. This is the main gotcha."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "12",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Animated bar chart\n",
+    "fig = xpx(da.sel(scenario=\"baseline\", metric=\"gdpPercap\")).bar(animation_frame=\"year\")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "13",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# This only affects the INITIAL view!\n",
+    "fig.update_traces(marker_color=\"red\")\n",
+    "\n",
+    "print(f\"Base trace color: {fig.data[0].marker.color}\")\n",
+    "print(f\"Frame 0 trace color: {fig.frames[0].data[0].marker.color}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "14",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Play the animation - it reverts to original colors\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "15",
+   "metadata": {},
+   "source": [
+    "### Solution: `update_traces` from xarray-plotly\n",
+    "\n",
+    "This helper updates both base traces and all animation frames."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "16",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = xpx(da.sel(scenario=\"baseline\", metric=\"gdpPercap\")).bar(animation_frame=\"year\")\n",
+    "\n",
+    "update_traces(fig, marker_color=\"red\", marker_opacity=0.8)\n",
+    "\n",
+    "print(f\"Base trace color: {fig.data[0].marker.color}\")\n",
+    "print(f\"Frame 0 trace color: {fig.frames[0].data[0].marker.color}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "17",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Now the style persists through animation\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "18",
+   "metadata": {},
+   "source": [
+    "### Selective updates with selector"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "19",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = xpx(da.sel(scenario=\"baseline\", metric=\"lifeExp\")).line(x=\"year\")\n",
+    "\n",
+    "# Highlight specific countries\n",
+    "update_traces(fig, selector={\"name\": \"China\"}, line_color=\"red\", line_width=4)\n",
+    "update_traces(fig, selector={\"name\": \"United States\"}, line_color=\"blue\", line_width=4)\n",
+    "\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "20",
+   "metadata": {},
+   "source": [
+    "### Unified hover with animation\n",
+    "\n",
+    "A common pattern: unified hover mode with custom formatting.\n",
+    "\n",
+    "- **Layout** (`hovermode`, spikes): Standard Plotly works fine\n",
+    "- **Traces** (`hovertemplate`): Use `update_traces()` for animation support"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "21",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = xpx(da.sel(metric=\"gdpPercap\")).line(x=\"year\", animation_frame=\"scenario\")\n",
+    "\n",
+    "# Layout settings - standard Plotly\n",
+    "fig.update_layout(hovermode=\"x unified\")\n",
+    "fig.update_xaxes(showspikes=True, spikecolor=\"gray\", spikethickness=1)\n",
+    "\n",
+    "# Trace settings - use update_traces for animation support\n",
+    "update_traces(fig, hovertemplate=\"<b>%{fullData.name}</b>: $%{y:,.0f}<extra></extra>\")\n",
+    "\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "22",
+   "metadata": {},
+   "source": [
+    "### Facets + Animation"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "23",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Facet by metric, animate by scenario\n",
+    "fig = xpx(da).line(facet_col=\"metric\", animation_frame=\"scenario\")\n",
+    "\n",
+    "# Standard Plotly for layout\n",
+    "fig.update_yaxes(type=\"log\", col=2)\n",
+    "\n",
+    "# update_traces for trace properties with animation\n",
+    "update_traces(fig, line_width=3)\n",
+    "update_traces(fig, selector={\"name\": \"China\"}, line_dash=\"dot\")\n",
+    "\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "24",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Summary\n",
+    "\n",
+    "| Method | Static/Faceted | Animated |\n",
+    "|--------|----------------|----------|\n",
+    "| `fig.update_layout()` | ✅ | ✅ |\n",
+    "| `fig.update_xaxes()` / `fig.update_yaxes()` | ✅ | ✅ |\n",
+    "| `fig.add_hline()` / `fig.add_vline()` | ✅ | ✅ |\n",
+    "| `fig.update_traces()` | ✅ | ❌ base only |\n",
+    "| `update_traces(fig, ...)` | ✅ | ✅ all frames |"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

{xarray_plotly-0.0.7 → xarray_plotly-0.0.8}/mkdocs.yml

@@ -73,4 +73,7 @@ nav:
       - Dimensions & Facets: examples/dimensions.ipynb
       - Plotly Express Options: examples/kwargs.ipynb
       - Figure Customization: examples/figure.ipynb
+      - Combining Figures: examples/combining.ipynb
+      - Figure Manipulation: examples/manipulation.ipynb
+      - Fast Bar Charts: examples/fast_bar.ipynb
   - API Reference: api.md