xarray-plotly 0.0.1__tar.gz → 0.0.3__tar.gz

xarray_plotly-0.0.3/.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      dev-dependencies:
+        patterns:
+          - "pytest*"
+          - "mypy"
+          - "ruff"
+          - "pre-commit"
+          - "nbstripout"
+      docs-dependencies:
+        patterns:
+          - "mkdocs*"
+          - "pooch"
+          - "netcdf4"
+          - "jupyter"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

xarray_plotly-0.0.3/.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,24 @@
+name: Dependabot auto-merge
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependabot:
+    runs-on: ubuntu-latest
+    if: github.actor == 'dependabot[bot]'
+    steps:
+      - name: Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v2
+        with:
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+
+      - name: Auto-merge minor and patch updates
+        if: steps.metadata.outputs.update-type == 'version-update:semver-patch' || steps.metadata.outputs.update-type == 'version-update:semver-minor'
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

xarray_plotly-0.0.3/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: xarray_plotly
+Version: 0.0.3
+Summary: Interactive Plotly Express plotting accessor for xarray
+Author: Felix
+License: MIT
+Project-URL: Homepage, https://github.com/FBumann/xarray_plotly
+Project-URL: Documentation, https://fbumann.github.io/xarray_plotly
+Project-URL: Repository, https://github.com/FBumann/xarray_plotly
+Keywords: xarray,plotly,visualization,interactive,plotting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: xarray>=2023.1.0
+Requires-Dist: plotly>=5.0.0
+Requires-Dist: pandas>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest==8.3.5; extra == "dev"
+Requires-Dist: pytest-cov==6.0.0; extra == "dev"
+Requires-Dist: mypy==1.14.1; extra == "dev"
+Requires-Dist: ruff==0.9.2; extra == "dev"
+Requires-Dist: pre-commit==4.0.1; extra == "dev"
+Requires-Dist: nbstripout==0.8.1; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs==1.6.1; extra == "docs"
+Requires-Dist: mkdocs-material==9.5.49; extra == "docs"
+Requires-Dist: mkdocstrings[python]==0.27.0; extra == "docs"
+Requires-Dist: mkdocs-jupyter==0.25.1; extra == "docs"
+Requires-Dist: mkdocs-plotly-plugin==0.1.3; extra == "docs"
+Requires-Dist: jupyter==1.1.1; extra == "docs"
+Dynamic: license-file
+
+# xarray_plotly
+
+**Interactive Plotly Express plotting for xarray**
+
+[![PyPI version](https://badge.fury.io/py/xarray_plotly.svg)](https://badge.fury.io/py/xarray_plotly)
+[![Python](https://img.shields.io/pypi/pyversions/xarray_plotly.svg)](https://pypi.org/project/xarray_plotly/)
+[![CI](https://github.com/FBumann/xarray_plotly/actions/workflows/ci.yml/badge.svg)](https://github.com/FBumann/xarray_plotly/actions)
+[![Docs](https://img.shields.io/badge/docs-fbumann.github.io-blue)](https://fbumann.github.io/xarray_plotly/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install xarray_plotly
+```
+
+## Quick Start
+
+```python
+import xarray as xr
+import numpy as np
+import xarray_plotly  # registers the accessor
+
+da = xr.DataArray(
+    np.random.randn(100, 3).cumsum(axis=0),
+    dims=["time", "city"],
+    coords={"time": np.arange(100), "city": ["NYC", "LA", "Chicago"]},
+)
+
+# Accessor style
+fig = da.plotly.line()
+fig.show()
+
+# Or with xpx() for IDE code completion
+from xarray_plotly import xpx
+fig = xpx(da).line()
+```
+
+**Why `xpx()`?** The accessor (`da.plotly`) works but IDEs can't provide code completion for it. This is because xarray accessors are registered dynamically at runtime, making them invisible to static type checkers. The `xpx()` function provides the same functionality with full IDE support. This limitation could only be solved by xarray itself, if at all — it may be a fundamental Python limitation.
+
+## Documentation
+
+Full documentation: [https://fbumann.github.io/xarray_plotly](https://fbumann.github.io/xarray_plotly)
+
+## License
+
+MIT

xarray_plotly-0.0.3/README.md

@@ -0,0 +1,47 @@
+# xarray_plotly
+
+**Interactive Plotly Express plotting for xarray**
+
+[![PyPI version](https://badge.fury.io/py/xarray_plotly.svg)](https://badge.fury.io/py/xarray_plotly)
+[![Python](https://img.shields.io/pypi/pyversions/xarray_plotly.svg)](https://pypi.org/project/xarray_plotly/)
+[![CI](https://github.com/FBumann/xarray_plotly/actions/workflows/ci.yml/badge.svg)](https://github.com/FBumann/xarray_plotly/actions)
+[![Docs](https://img.shields.io/badge/docs-fbumann.github.io-blue)](https://fbumann.github.io/xarray_plotly/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install xarray_plotly
+```
+
+## Quick Start
+
+```python
+import xarray as xr
+import numpy as np
+import xarray_plotly  # registers the accessor
+
+da = xr.DataArray(
+    np.random.randn(100, 3).cumsum(axis=0),
+    dims=["time", "city"],
+    coords={"time": np.arange(100), "city": ["NYC", "LA", "Chicago"]},
+)
+
+# Accessor style
+fig = da.plotly.line()
+fig.show()
+
+# Or with xpx() for IDE code completion
+from xarray_plotly import xpx
+fig = xpx(da).line()
+```
+
+**Why `xpx()`?** The accessor (`da.plotly`) works but IDEs can't provide code completion for it. This is because xarray accessors are registered dynamically at runtime, making them invisible to static type checkers. The `xpx()` function provides the same functionality with full IDE support. This limitation could only be solved by xarray itself, if at all — it may be a fundamental Python limitation.
+
+## Documentation
+
+Full documentation: [https://fbumann.github.io/xarray_plotly](https://fbumann.github.io/xarray_plotly)
+
+## License
+
+MIT

xarray_plotly-0.0.3/docs/api.md

@@ -0,0 +1,28 @@
+# API Reference
+
+::: xarray_plotly.xpx
+
+::: xarray_plotly.accessor.DataArrayPlotlyAccessor
+    options:
+      members:
+        - line
+        - bar
+        - area
+        - scatter
+        - box
+        - imshow
+
+::: xarray_plotly.config
+    options:
+      members:
+        - notebook
+        - get_options
+        - set_options
+        - Options
+
+::: xarray_plotly.common
+    options:
+      members:
+        - auto
+        - SLOT_ORDERS
+        - assign_slots

xarray_plotly-0.0.3/docs/examples/advanced.ipynb

@@ -0,0 +1,320 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Advanced Usage\n",
+    "\n",
+    "This notebook covers advanced Plotly customization. All kwargs are passed directly to [Plotly Express](https://plotly.com/python/plotly-express/), and figures can be modified using the full [Plotly Graph Objects API](https://plotly.com/python/graph-objects/)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import plotly.express as px\n",
+    "import plotly.graph_objects as go\n",
+    "import xarray as xr\n",
+    "\n",
+    "from xarray_plotly import config, xpx\n",
+    "\n",
+    "config.notebook()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Load sample data\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",
+    "df_gap = px.data.gapminder()\n",
+    "countries = [\"United States\", \"China\", \"Germany\", \"Brazil\", \"Nigeria\"]\n",
+    "df_life = df_gap[df_gap[\"country\"].isin(countries)].pivot(\n",
+    "    index=\"year\", columns=\"country\", values=\"lifeExp\"\n",
+    ")\n",
+    "life_exp = xr.DataArray(\n",
+    "    df_life.values,\n",
+    "    dims=[\"year\", \"country\"],\n",
+    "    coords={\"year\": df_life.index, \"country\": df_life.columns.tolist()},\n",
+    "    name=\"life_exp\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Passing Kwargs to Plotly Express\n",
+    "\n",
+    "All keyword arguments are passed directly to [Plotly Express functions](https://plotly.com/python-api-reference/plotly.express.html):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# All px.line kwargs work: template, labels, colors, etc.\n",
+    "fig = xpx(stocks).line(\n",
+    "    title=\"Stock Performance\",\n",
+    "    template=\"plotly_white\",\n",
+    "    labels={\"price\": \"Normalized Price\", \"date\": \"Date\", \"company\": \"Ticker\"},\n",
+    "    color_discrete_sequence=px.colors.qualitative.Set2,\n",
+    ")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# px.imshow kwargs: colorscale, midpoint, aspect\n",
+    "# See: https://plotly.com/python/imshow/\n",
+    "life_change = life_exp - life_exp.isel(year=0)\n",
+    "\n",
+    "fig = xpx(life_change).imshow(\n",
+    "    color_continuous_scale=\"RdBu\",\n",
+    "    color_continuous_midpoint=0,\n",
+    "    aspect=\"auto\",\n",
+    "    title=\"Life Expectancy Change Since 1952\",\n",
+    ")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# px.bar kwargs: barmode, text_auto\n",
+    "# See: https://plotly.com/python/bar-charts/\n",
+    "fig = xpx(life_exp.sel(year=[1952, 1982, 2007])).bar(\n",
+    "    barmode=\"group\",\n",
+    "    text_auto=\".1f\",\n",
+    "    title=\"Life Expectancy\",\n",
+    ")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Modifying Figures After Creation\n",
+    "\n",
+    "All methods return a Plotly `Figure`. Use the [Figure API](https://plotly.com/python/creating-and-updating-figures/) to customize:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### update_layout\n",
+    "\n",
+    "Modify [layout properties](https://plotly.com/python/reference/layout/): legend, margins, fonts, etc."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = xpx(stocks).line()\n",
+    "\n",
+    "fig.update_layout(\n",
+    "    title={\"text\": \"Stock Prices\", \"x\": 0.5, \"font\": {\"size\": 24}},\n",
+    "    legend={\n",
+    "        \"orientation\": \"h\",\n",
+    "        \"yanchor\": \"bottom\",\n",
+    "        \"y\": 1.02,\n",
+    "        \"xanchor\": \"center\",\n",
+    "        \"x\": 0.5,\n",
+    "    },\n",
+    "    margin={\"t\": 80},\n",
+    ")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### update_traces\n",
+    "\n",
+    "Modify [trace properties](https://plotly.com/python/reference/): line width, markers, opacity, etc."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = xpx(stocks).line()\n",
+    "fig.update_traces(line={\"width\": 3})\n",
+    "fig.update_layout(title=\"Thicker Lines\")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = xpx(stocks).scatter()\n",
+    "fig.update_traces(marker={\"size\": 12, \"opacity\": 0.7, \"line\": {\"width\": 1, \"color\": \"white\"}})\n",
+    "fig.update_layout(title=\"Custom Markers\")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### update_xaxes / update_yaxes\n",
+    "\n",
+    "Modify [axis properties](https://plotly.com/python/axes/): range slider, tick format, etc."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = xpx(stocks).line(title=\"With Range Slider\")\n",
+    "fig.update_xaxes(rangeslider_visible=True)\n",
+    "fig.update_yaxes(tickformat=\".0%\")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Adding Shapes and Annotations\n",
+    "\n",
+    "Add reference lines, [shapes](https://plotly.com/python/shapes/), and [annotations](https://plotly.com/python/text-and-annotations/):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = xpx(stocks).line(title=\"With Reference Lines and Annotations\")\n",
+    "\n",
+    "fig.add_hline(y=1.0, line_dash=\"dash\", line_color=\"gray\", annotation_text=\"Baseline\")\n",
+    "fig.add_vline(x=\"2018-10-01\", line_dash=\"dot\", line_color=\"red\")\n",
+    "\n",
+    "fig.add_annotation(\n",
+    "    x=\"2018-10-01\",\n",
+    "    y=1.4,\n",
+    "    text=\"Market correction\",\n",
+    "    showarrow=True,\n",
+    "    arrowhead=2,\n",
+    "    ax=40,\n",
+    "    ay=-40,\n",
+    ")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Adding Traces with Graph Objects\n",
+    "\n",
+    "Add custom traces using [Plotly Graph Objects](https://plotly.com/python/graph-objects/):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = xpx(stocks.sel(company=\"GOOG\")).line(title=\"GOOG with Moving Average\")\n",
+    "\n",
+    "# Add moving average as a new trace\n",
+    "goog = stocks.sel(company=\"GOOG\")\n",
+    "ma_20 = goog.rolling(date=20, center=True).mean()\n",
+    "\n",
+    "fig.add_trace(\n",
+    "    go.Scatter(\n",
+    "        x=ma_20.coords[\"date\"].values,\n",
+    "        y=ma_20.values,\n",
+    "        mode=\"lines\",\n",
+    "        name=\"20-day MA\",\n",
+    "        line={\"dash\": \"dash\", \"color\": \"red\", \"width\": 2},\n",
+    "    )\n",
+    ")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Exporting Figures\n",
+    "\n",
+    "See [static image export](https://plotly.com/python/static-image-export/) and [HTML export](https://plotly.com/python/interactive-html-export/).\n",
+    "\n",
+    "```python\n",
+    "# Interactive HTML\n",
+    "fig.write_html(\"plot.html\")\n",
+    "\n",
+    "# Static images (requires: pip install kaleido)\n",
+    "fig.write_image(\"plot.png\", scale=2)\n",
+    "fig.write_image(\"plot.svg\")\n",
+    "fig.write_image(\"plot.pdf\")\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## More Resources\n",
+    "\n",
+    "- [Plotly Express API](https://plotly.com/python-api-reference/plotly.express.html)\n",
+    "- [Figure Reference](https://plotly.com/python/reference/)\n",
+    "- [Plotly Tutorials](https://plotly.com/python/)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}