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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xarray_plotly
-Version: 0.0.6
+Version: 0.0.8
 Summary: Interactive Plotly Express plotting accessor for xarray
 Author: Felix
 License: MIT
@@ -28,7 +28,7 @@ Provides-Extra: dev
 Requires-Dist: pytest==9.0.2; extra == "dev"
 Requires-Dist: pytest-cov==7.0.0; extra == "dev"
 Requires-Dist: mypy==1.19.1; extra == "dev"
-Requires-Dist: ruff==0.14.11; extra == "dev"
+Requires-Dist: ruff==0.14.13; extra == "dev"
 Requires-Dist: pre-commit==4.5.1; extra == "dev"
 Requires-Dist: nbstripout==0.8.2; extra == "dev"
 Provides-Extra: docs

xarray_plotly-0.0.8/docs/examples/combining.ipynb

@@ -0,0 +1,646 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Combining Figures\n",
+    "\n",
+    "xarray-plotly provides helper functions to combine multiple figures:\n",
+    "\n",
+    "- **`overlay`**: Overlay traces on the same axes\n",
+    "- **`add_secondary_y`**: Plot with two independent y-axes"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import plotly.express as px\n",
+    "import xarray as xr\n",
+    "\n",
+    "from xarray_plotly import add_secondary_y, config, overlay, xpx\n",
+    "\n",
+    "config.notebook()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2",
+   "metadata": {},
+   "source": [
+    "## Load Sample Data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Stock prices\n",
+    "df_stocks = px.data.stocks().set_index(\"date\")\n",
+    "df_stocks.index = df_stocks.index.astype(\"datetime64[ns]\")\n",
+    "\n",
+    "stocks = xr.DataArray(\n",
+    "    df_stocks.values,\n",
+    "    dims=[\"date\", \"company\"],\n",
+    "    coords={\"date\": df_stocks.index, \"company\": df_stocks.columns.tolist()},\n",
+    "    name=\"price\",\n",
+    ")\n",
+    "\n",
+    "# Gapminder data (subset: a few countries)\n",
+    "df_gap = px.data.gapminder()\n",
+    "countries = [\"United States\", \"China\", \"Germany\", \"Brazil\"]\n",
+    "df_gap = df_gap[df_gap[\"country\"].isin(countries)]\n",
+    "\n",
+    "# Convert to xarray\n",
+    "gap_pop = df_gap.pivot(index=\"year\", columns=\"country\", values=\"pop\")\n",
+    "gap_gdp = df_gap.pivot(index=\"year\", columns=\"country\", values=\"gdpPercap\")\n",
+    "gap_life = df_gap.pivot(index=\"year\", columns=\"country\", values=\"lifeExp\")\n",
+    "\n",
+    "population = xr.DataArray(\n",
+    "    gap_pop.values,\n",
+    "    dims=[\"year\", \"country\"],\n",
+    "    coords={\"year\": gap_pop.index.values, \"country\": gap_pop.columns.tolist()},\n",
+    "    name=\"Population\",\n",
+    ")\n",
+    "\n",
+    "gdp_per_capita = xr.DataArray(\n",
+    "    gap_gdp.values,\n",
+    "    dims=[\"year\", \"country\"],\n",
+    "    coords={\"year\": gap_gdp.index.values, \"country\": gap_gdp.columns.tolist()},\n",
+    "    name=\"GDP per Capita\",\n",
+    ")\n",
+    "\n",
+    "life_expectancy = xr.DataArray(\n",
+    "    gap_life.values,\n",
+    "    dims=[\"year\", \"country\"],\n",
+    "    coords={\"year\": gap_life.index.values, \"country\": gap_life.columns.tolist()},\n",
+    "    name=\"Life Expectancy\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4",
+   "metadata": {},
+   "source": [
+    "## overlay\n",
+    "\n",
+    "Overlay multiple figures on the same axes. Useful for showing data with a trend line, moving average, or different visualizations of related data."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5",
+   "metadata": {},
+   "source": [
+    "### Stock Price with Moving Average"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Select one company\n",
+    "goog = stocks.sel(company=\"GOOG\")\n",
+    "\n",
+    "# Calculate 20-day moving average\n",
+    "goog_ma = goog.rolling(date=20, center=True).mean()\n",
+    "goog_ma.name = \"20-day MA\"\n",
+    "\n",
+    "# Raw prices as scatter\n",
+    "price_fig = xpx(goog).scatter()\n",
+    "price_fig.update_traces(marker={\"size\": 4, \"opacity\": 0.5}, name=\"Daily Price\")\n",
+    "\n",
+    "# Moving average as line\n",
+    "ma_fig = xpx(goog_ma).line()\n",
+    "ma_fig.update_traces(line={\"color\": \"red\", \"width\": 3}, name=\"20-day MA\")\n",
+    "\n",
+    "combined = overlay(price_fig, ma_fig)\n",
+    "combined.update_layout(title=\"GOOG: Daily Price with Moving Average\")\n",
+    "combined"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7",
+   "metadata": {},
+   "source": [
+    "### Multiple Companies with Moving Averages"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Select a few companies\n",
+    "subset = stocks.sel(company=[\"GOOG\", \"AAPL\", \"MSFT\"])\n",
+    "subset_ma = subset.rolling(date=20, center=True).mean()\n",
+    "\n",
+    "# Raw as scatter (faded)\n",
+    "raw_fig = xpx(subset).scatter()\n",
+    "raw_fig.update_traces(marker={\"size\": 3, \"opacity\": 0.3})\n",
+    "\n",
+    "# MA as lines (bold)\n",
+    "ma_fig = xpx(subset_ma).line()\n",
+    "ma_fig.update_traces(line={\"width\": 3})\n",
+    "\n",
+    "combined = overlay(raw_fig, ma_fig)\n",
+    "combined.update_layout(title=\"Tech Stocks: Raw Prices + Moving Averages\")\n",
+    "combined"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9",
+   "metadata": {},
+   "source": [
+    "### With Facets\n",
+    "\n",
+    "`overlay` works with faceted figures as long as both have the same structure."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "10",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Faceted by company\n",
+    "raw_faceted = xpx(subset).scatter(facet_col=\"company\")\n",
+    "raw_faceted.update_traces(marker={\"size\": 3, \"opacity\": 0.4})\n",
+    "\n",
+    "ma_faceted = xpx(subset_ma).line(facet_col=\"company\")\n",
+    "ma_faceted.update_traces(line={\"color\": \"red\", \"width\": 2})\n",
+    "\n",
+    "combined = overlay(raw_faceted, ma_faceted)\n",
+    "combined.update_layout(title=\"Faceted: Price + Moving Average per Company\")\n",
+    "combined"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "11",
+   "metadata": {},
+   "source": [
+    "### With Animation\n",
+    "\n",
+    "Overlay animated figures - frames are merged correctly."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "12",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Animate through countries, showing population bar + GDP line\n",
+    "# Both use the same animation dimension\n",
+    "pop_anim = xpx(population).bar(animation_frame=\"country\")\n",
+    "pop_anim.update_traces(marker={\"opacity\": 0.6})\n",
+    "\n",
+    "# Create a \"target\" line (e.g., some reference value)\n",
+    "pop_smooth = population.rolling(year=3, center=True).mean()\n",
+    "smooth_anim = xpx(pop_smooth).line(animation_frame=\"country\")\n",
+    "smooth_anim.update_traces(line={\"color\": \"red\", \"width\": 3})\n",
+    "\n",
+    "combined = overlay(pop_anim, smooth_anim)\n",
+    "combined.update_layout(title=\"Population: Raw + Smoothed (animated by country)\")\n",
+    "combined"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "13",
+   "metadata": {},
+   "source": [
+    "### Static Overlay on Animated Base\n",
+    "\n",
+    "A static figure can be overlaid on an animated one - the static traces appear in all frames."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "14",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Animated population\n",
+    "pop_anim = xpx(population).bar(animation_frame=\"country\")\n",
+    "pop_anim.update_traces(marker={\"opacity\": 0.7})\n",
+    "\n",
+    "# Static reference line (global average across all countries)\n",
+    "global_avg = population.mean(dim=\"country\")\n",
+    "avg_fig = xpx(global_avg).line()\n",
+    "avg_fig.update_traces(line={\"color\": \"black\", \"width\": 2, \"dash\": \"dash\"}, name=\"Global Avg\")\n",
+    "\n",
+    "combined = overlay(pop_anim, avg_fig)\n",
+    "combined.update_layout(title=\"Population by Country vs Global Average\")\n",
+    "combined"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "15",
+   "metadata": {},
+   "source": [
+    "## add_secondary_y\n",
+    "\n",
+    "Plot two variables with different scales using independent y-axes. Essential when values have different magnitudes."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "16",
+   "metadata": {},
+   "source": [
+    "### Population vs GDP per Capita"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "17",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Select one country\n",
+    "us_pop = population.sel(country=\"United States\")\n",
+    "us_gdp = gdp_per_capita.sel(country=\"United States\")\n",
+    "\n",
+    "pop_fig = xpx(us_pop).bar()\n",
+    "pop_fig.update_traces(marker={\"color\": \"steelblue\", \"opacity\": 0.7}, name=\"Population\")\n",
+    "\n",
+    "gdp_fig = xpx(us_gdp).line()\n",
+    "gdp_fig.update_traces(line={\"color\": \"red\", \"width\": 3}, name=\"GDP per Capita\")\n",
+    "\n",
+    "combined = add_secondary_y(pop_fig, gdp_fig, secondary_y_title=\"GDP per Capita ($)\")\n",
+    "combined.update_layout(\n",
+    "    title=\"United States: Population vs GDP per Capita\",\n",
+    "    yaxis_title=\"Population\",\n",
+    ")\n",
+    "combined"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "18",
+   "metadata": {},
+   "source": [
+    "### Why Secondary Y-Axis Matters\n",
+    "\n",
+    "Without it, one variable dominates due to scale mismatch:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "19",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Same data on single y-axis - GDP looks flat because population is ~1e8, GDP is ~1e4\n",
+    "pop_fig = xpx(us_pop).line()\n",
+    "pop_fig.update_traces(name=\"Population\", line={\"color\": \"blue\"})\n",
+    "\n",
+    "gdp_fig = xpx(us_gdp).line()\n",
+    "gdp_fig.update_traces(name=\"GDP per Capita\", line={\"color\": \"red\"})\n",
+    "\n",
+    "bad = overlay(pop_fig, gdp_fig)\n",
+    "bad.update_layout(title=\"overlay: GDP invisible (scale mismatch)\")\n",
+    "bad"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "20",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# With add_secondary_y - both variables visible\n",
+    "pop_fig = xpx(us_pop).line()\n",
+    "pop_fig.update_traces(name=\"Population\", line={\"color\": \"blue\", \"width\": 2})\n",
+    "\n",
+    "gdp_fig = xpx(us_gdp).line()\n",
+    "gdp_fig.update_traces(name=\"GDP per Capita\", line={\"color\": \"red\", \"width\": 2})\n",
+    "\n",
+    "good = add_secondary_y(pop_fig, gdp_fig, secondary_y_title=\"GDP per Capita ($)\")\n",
+    "good.update_layout(title=\"add_secondary_y: Both variables clearly visible\")\n",
+    "good"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "21",
+   "metadata": {},
+   "source": [
+    "### With Animation\n",
+    "\n",
+    "`add_secondary_y` supports animated figures with matching frames."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "22",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Animate through countries\n",
+    "pop_anim = xpx(population).bar(animation_frame=\"country\")\n",
+    "pop_anim.update_traces(marker={\"color\": \"steelblue\", \"opacity\": 0.7})\n",
+    "\n",
+    "gdp_anim = xpx(gdp_per_capita).line(animation_frame=\"country\")\n",
+    "gdp_anim.update_traces(line={\"color\": \"red\", \"width\": 3})\n",
+    "\n",
+    "combined = add_secondary_y(pop_anim, gdp_anim, secondary_y_title=\"GDP per Capita ($)\")\n",
+    "combined.update_layout(title=\"Population vs GDP (animated by country)\")\n",
+    "combined"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "23",
+   "metadata": {},
+   "source": [
+    "### Static Secondary on Animated Base\n",
+    "\n",
+    "A static secondary figure is replicated to all animation frames."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "24",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Animated population\n",
+    "pop_anim = xpx(population).bar(animation_frame=\"country\")\n",
+    "pop_anim.update_traces(marker={\"color\": \"steelblue\", \"opacity\": 0.7})\n",
+    "\n",
+    "# Static GDP reference (US only, shown in all frames)\n",
+    "us_gdp_static = xpx(us_gdp).line()\n",
+    "us_gdp_static.update_traces(\n",
+    "    line={\"color\": \"red\", \"width\": 2, \"dash\": \"dash\"}, name=\"US GDP (reference)\"\n",
+    ")\n",
+    "\n",
+    "combined = add_secondary_y(pop_anim, us_gdp_static, secondary_y_title=\"GDP per Capita ($)\")\n",
+    "combined.update_layout(title=\"Population (animated) vs US GDP (static reference)\")\n",
+    "combined"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "25",
+   "metadata": {},
+   "source": [
+    "### With Facets\n",
+    "\n",
+    "`add_secondary_y` works with faceted figures when both have the same facet structure."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "26",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Faceted by country - both figures must have same facet structure\n",
+    "pop_faceted = xpx(population).bar(facet_col=\"country\")\n",
+    "pop_faceted.update_traces(marker={\"color\": \"steelblue\", \"opacity\": 0.7})\n",
+    "\n",
+    "gdp_faceted = xpx(gdp_per_capita).line(facet_col=\"country\")\n",
+    "gdp_faceted.update_traces(line={\"color\": \"red\", \"width\": 3})\n",
+    "\n",
+    "combined = add_secondary_y(pop_faceted, gdp_faceted, secondary_y_title=\"GDP per Capita ($)\")\n",
+    "combined.update_layout(title=\"Population vs GDP per Capita (faceted by country)\")\n",
+    "combined"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "27",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "\n",
+    "## Limitations (with examples)\n",
+    "\n",
+    "Both functions validate inputs and raise clear errors when constraints are violated."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "28",
+   "metadata": {},
+   "source": [
+    "### overlay: Mismatched Facet Structure\n",
+    "\n",
+    "Overlay cannot have subplots that don't exist in base."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "29",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Base: no facets\n",
+    "base = xpx(stocks.sel(company=\"GOOG\")).line()\n",
+    "\n",
+    "# Overlay: has facets\n",
+    "overlay_fig = xpx(stocks.sel(company=[\"GOOG\", \"AAPL\"])).line(facet_col=\"company\")\n",
+    "\n",
+    "try:\n",
+    "    overlay(base, overlay_fig)\n",
+    "except ValueError as e:\n",
+    "    print(f\"ValueError: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "30",
+   "metadata": {},
+   "source": [
+    "### overlay: Animated Overlay on Static Base\n",
+    "\n",
+    "Cannot add an animated overlay to a static base figure."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "31",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Base: static\n",
+    "static_base = xpx(population.sel(country=\"United States\")).line()\n",
+    "\n",
+    "# Overlay: animated\n",
+    "animated_overlay = xpx(population).line(animation_frame=\"country\")\n",
+    "\n",
+    "try:\n",
+    "    overlay(static_base, animated_overlay)\n",
+    "except ValueError as e:\n",
+    "    print(f\"ValueError: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "32",
+   "metadata": {},
+   "source": [
+    "### overlay: Mismatched Animation Frames\n",
+    "\n",
+    "Animation frame names must match exactly."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "33",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Different countries selected = different frame names\n",
+    "fig1 = xpx(population.sel(country=[\"United States\", \"China\"])).line(animation_frame=\"country\")\n",
+    "fig2 = xpx(population.sel(country=[\"Germany\", \"Brazil\"])).line(animation_frame=\"country\")\n",
+    "\n",
+    "try:\n",
+    "    overlay(fig1, fig2)\n",
+    "except ValueError as e:\n",
+    "    print(f\"ValueError: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "34",
+   "metadata": {},
+   "source": [
+    "### add_secondary_y: Mismatched Facet Structure\n",
+    "\n",
+    "Both figures must have the same facet structure."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "35",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Base with facets\n",
+    "pop_faceted = xpx(population).bar(facet_col=\"country\")\n",
+    "\n",
+    "# Secondary without facets (different structure)\n",
+    "gdp_single = xpx(gdp_per_capita.sel(country=\"United States\")).line()\n",
+    "\n",
+    "try:\n",
+    "    add_secondary_y(pop_faceted, gdp_single)\n",
+    "except ValueError as e:\n",
+    "    print(f\"ValueError: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "36",
+   "metadata": {},
+   "source": [
+    "### add_secondary_y: Animated Secondary on Static Base\n",
+    "\n",
+    "Cannot add animated secondary to static base."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "37",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Static base\n",
+    "static_pop = xpx(population.sel(country=\"United States\")).bar()\n",
+    "\n",
+    "# Animated secondary\n",
+    "animated_gdp = xpx(gdp_per_capita).line(animation_frame=\"country\")\n",
+    "\n",
+    "try:\n",
+    "    add_secondary_y(static_pop, animated_gdp)\n",
+    "except ValueError as e:\n",
+    "    print(f\"ValueError: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "38",
+   "metadata": {},
+   "source": [
+    "### add_secondary_y: Mismatched Animation Frames"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "39",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Different countries = different frames\n",
+    "pop_some = xpx(population.sel(country=[\"United States\", \"China\"])).bar(animation_frame=\"country\")\n",
+    "gdp_other = xpx(gdp_per_capita.sel(country=[\"Germany\", \"Brazil\"])).line(animation_frame=\"country\")\n",
+    "\n",
+    "try:\n",
+    "    add_secondary_y(pop_some, gdp_other)\n",
+    "except ValueError as e:\n",
+    "    print(f\"ValueError: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "40",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "| Function | Facets | Animation | Static + Animated |\n",
+    "|----------|--------|-----------|-------------------|\n",
+    "| `overlay` | Yes (must match) | Yes (frames must match) | Static overlay on animated base OK |\n",
+    "| `add_secondary_y` | Yes (must match) | Yes (frames must match) | Static secondary on animated base OK |"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}