feat: add Polars support with version-locked dependencies

.gitignore

@@ -11,3 +11,7 @@ docs/generated
 docs/gallery_scripts
 docs/_build
 .DS_Store
+venv/
+.venv/
+_build/
+tmpclaude-c0db-cwd

README.md

@@ -32,6 +32,19 @@ pyOpenMS-Viz is a Python library that provides a simple interface for extending
 | PeakMap 3D      | x, y, z                 | peakmap (plot3d=True)                                     | ✓              |           | ✓          |
 
 
+### Note on Polars DataFrames
+`pyopenms_viz` can work with [Polars](https://pola.rs/) DataFrames by internally converting them to pandas, often via an Arrow-backed representation where possible. This conversion may involve data copies depending on data types and configuration, and plotting is ultimately delegated to the pandas-based plotting backends. Due to API differences, you must use the `.ms_plot()` namespace instead of `.plot()` when working with Polars.
+
+**Pandas:**
+```python
+df_pandas.plot(kind="spectrum", x="m/z", y="intensity", backend="ms_plotly")
+```
+
+**Polars:**
+```python
+df_polars.ms_plot(kind="spectrum", x="m/z", y="intensity", backend="ms_plotly")
+```
+
 ## (Recommended) Pip Installation
 
 The recommended way of installing pyopenms_viz is through the Python Package Index (PyPI). We recommend installing pyopenms_viz in its own virtual environment using Anaconda to avoid packaging conflicts.

docs/Getting Started.ipynb

@@ -3227,6 +3227,40 @@
     "               x_kind='chromatogram', # specify on x marginal axis to plot as a chromatogram rather than a spectrum  \n",
     "               grid=False) "
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4b971b57",
+   "metadata": {},
+   "source": [
+    "Using Polars DataFrames\n",
+    "\n",
+    "pyopenms_viz is deeply optimized for Pandas. While you can use Polars for high-speed data manipulation, downstream plotting libraries often force silent C-API memory materialization when handling PyArrow extension arrays.\n",
+    "\n",
+    "To maintain a strictly native, memory-safe footprint for large datasets, the recommended approach is to process your data in Polars, and then explicitly convert it to Pandas before calling the .ms_plot accessor."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "12fa9e5a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import polars as pl\n",
+    "\n",
+    "# Convert the existing 'spectrum_df' to Polars\n",
+    "df_polars = pl.from_pandas(spectrum_df)\n",
+    "\n",
+    "# ... perform your high-speed Polars operations here ...\n",
+    "\n",
+    "# Explicitly convert back to Pandas for memory-safe rendering\n",
+    "df_safe = df_polars.to_pandas()\n",
+    "\n",
+    "# Plot using the native pyopenms_viz plotting method\n",
+    "# (Using the 'mz' and 'intensity' columns from this notebook)\n",
+    "df_safe.plot(kind='spectrum', x='mz', y='intensity', backend='ms_bokeh')"
+   ]
   }
  ],
  "metadata": {

docs/conf.py

@@ -312,7 +312,8 @@ def bokeh_scraper(block, block_vars, gallery_conf, **kwargs):
     "binder": {
         "org": "OpenMS",
         "repo": "pyopenms_viz",
-        "branch": "gh_pages",
+        # Use the source branch for Binder launches; gh_pages is a deploy artifact branch.
+        "branch": "main",
         "binderhub_url": "https://notebooks.gesis.org/binder",
         "dependencies": "./requirements.txt",
     },

pyopenms_viz/__init__.py

@@ -1,7 +1,7 @@
 """
 init
 """
-
+from . import _polars_accessor  # Import for side effects: registers pandas accessors. noqa: F401
 from pandas.plotting._core import PlotAccessor
 from pandas.core.frame import DataFrame
 from typing import Any

pyopenms_viz/_polars_accessor.py

@@ -0,0 +1,30 @@
+"""
+Polars namespace extension for pyopenms_viz.
+"""
+try:
+    import polars as pl
+    POLARS_AVAILABLE = True
+except ImportError:
+    POLARS_AVAILABLE = False
+
+if POLARS_AVAILABLE:
+    @pl.api.register_dataframe_namespace("ms_plot")
+    class PolarsPlotAccessor:
+        def __init__(self, df: pl.DataFrame):
+            self._df = df
+
+        def __call__(self, *args, **kwargs):
+            try:
+                # 1. Safety Catch: Use Arrow-backed arrays with a clear error fallback
+                pandas_df = self._df.to_pandas(use_pyarrow_extension_array=True)
+            except (ImportError, ModuleNotFoundError) as exc:
+                raise ImportError(
+                    "Converting a Polars DataFrame to pandas failed because required "
+                    "optional dependencies are missing. Please install 'pyarrow':\n"
+                    "  pip install pyarrow"
+                ) from exc
+
+            # 2. Delegate to pandas' plotting API.
+            # This lets pandas resolve ms_* backends via entry points and respect
+            # the global `pd.options.plotting.backend` setting.
+            return pandas_df.plot(*args, **kwargs)

requirements.txt

@@ -177,6 +177,8 @@ plotly==5.24.1
     # via pyopenms_viz (pyproject.toml)
 pluggy==1.6.0
     # via pytest
+polars==1.38.1
+
 prompt-toolkit==3.0.52
     # via ipython
 psutil==7.2.2
@@ -185,6 +187,8 @@ ptyprocess==0.7.0
     # via pexpect
 pure-eval==0.2.3
     # via stack-data
+pyarrow==23.0.1
+    # via polars
 pycparser==3.0
     # via cffi
 pydata-sphinx-theme==0.16.1
@@ -215,6 +219,7 @@ pytz==2025.2
     # via pandas
 pyyaml==6.0.3
     # via bokeh
+
 pyzmq==27.1.0
     # via
     #   ipykernel
@@ -307,3 +312,4 @@ webencodings==0.5.1
     #   tinycss2
 xyzservices==2025.11.0
     # via bokeh
+