Add explore() function and GISDocument.sidecar() method (#340)

* Create GISDocuments as untitled when no path provided

* Remove `save_as()` method from GISDocument API, re-add `export_to_qgis()`

We now create untitled documents when no path is passed in, so users can
use the JupyterLab facilities to rename the document.

* Prefer `const`

* Fix unit test

* Test untitled document numbering

* Update docstring

* Stub out geo_debug function with jupyterlab-sidecar

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* WIP

* Add ESPM-157 notebook as example user of geo-debug workflow WIP

* Use correct .jGIS extension

* Dunno, rebase me later

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Open JGIS in sidecar

* Create an anonymous project

* Open in a new JupyterLab window/tab!

* Update TODO comments

* Rename geo_debug -> explore

Also move it up a level in the package

* Explore explore function at jupytergis package

* Update docstring and parameter type

* Open JGIS Document as a full window, not widget

* Hack around document opening but not displaying layers as expected

Co-authored-by: Greg Mooney <[email protected]>
Co-authored-by: Kristin Davis <[email protected]>
Co-authored-by: Sanjay Bhangar <[email protected]>
Co-authored-by: Aman Ahuja <amanahuja@gmail>
Co-authored-by: Jonathan Marokhovsky <jmarokhovsky@clarku>
Co-authored-by: Tammy Woodard <[email protected]>

* Switch back to sidecar approach, use CSS to handle filling space

* Add dedicated explore example

* Cleanup OBE comment

* Remove OBE test

* Extract sidecar-opening to GISDocument API

User can open sidecar with one line of code. They can learn how to do it
from reading our API docs only.

* Dynamically determine type of object passed to explore()

Currently only support geodataframes and GeoJSON.

* Update example notebook to explore a geodataframe

* Remove debugging print statement

* Move "smart" layer add into GISDocument method

* Add basemap parameter to `explore()`

* Autodoc `explore()`

* Bugfix: don't pass name=None to methods that don't support it

* Fix incorrect docstring raises directive

* Install jupytergis metapackage in docs environment

Autogenerated docs will document `jupytergis.GISDocument` and
`jupytergis.explore` instead of `jupytergis_lab.GISDocument` and
`jupytergis_lab.explore`. As `jupytergis` is the package we instruct
end-users to install, documenting `jupytergis_lab` is confusing.

* Fix CSS to properly use vertical space in linked output & sidecar views

We expect this change to be eventually included in JupyterLab:
jupyterlab/jupyterlab#17487

Including in JGIS for compatibility with versions of JupyterLab that
don't include this CSS.

* Fix autodoc typo

* Fix layer panel not updating in sidecar view

Co-authored-by: Nicolas Brichet <[email protected]>

* Copy docstring raises entries from underlying method docstring

* Attempt to fix lite integration tests

#340 (comment)

Co-authored-by: martinRenou <[email protected]>
Co-authored-by: Nicolas Brichet <[email protected]>

* Add note about CSS eventually added in JupyterLab

Co-authored-by: Nicolas Brichet <[email protected]>

* Move explore module into notebook subpackage

Co-authored-by: Nicolas Brichet <[email protected]>

* Make generic add_layer method a private internal function

Co-authored-by: martinRenou <[email protected]>
Co-authored-by: Nicolas Brichet <[email protected]>

* Missing sidecar and export

* Missing sidecar in docs

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Greg Mooney <[email protected]>
Co-authored-by: Kristin Davis <[email protected]>
Co-authored-by: Sanjay Bhangar <[email protected]>
Co-authored-by: Aman Ahuja <amanahuja@gmail>
Co-authored-by: Jonathan Marokhovsky <jmarokhovsky@clarku>
Co-authored-by: Tammy Woodard <[email protected]>
Co-authored-by: Nicolas Brichet <[email protected]>
Co-authored-by: martinRenou <[email protected]>

Author: 10 people

docs/environment.yml

@@ -11,6 +11,7 @@ dependencies:
   - ypywidgets>=0.9.6,<0.10.0
   - comm>=0.1.2,<0.2.0
   - pydantic>=2,<3
+  - sidecar
   - pip:
       - yjs-widgets>=0.4,<0.5
       - my-jupyter-shared-drive<0.2.0

docs/user_guide/python_api.md

@@ -34,7 +34,13 @@ doc
 
 Once the document is opened/created, you can start creating GIS layers.
 
-## `GISDocument` API Reference
+## `explore`
+
+```{eval-rst}
+.. autofunction:: jupytergis_lab.explore
+```
+
+## `GISDocument`
 
 ```{eval-rst}
 .. autoclass:: jupytergis_lab.GISDocument

examples/explore.ipynb

@@ -0,0 +1,111 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "c3f4096f-cbd3-43e8-a986-520681f03581",
+   "metadata": {},
+   "source": [
+    "# ESPM 157 - Intro to Spatial Data\n",
+    "\n",
+    "<https://espm-157.carlboettiger.info/spatial-1>\n",
+    "\n",
+    "Install dependencies:\n",
+    "\n",
+    "```bash\n",
+    "micromamba install geopandas ibis-duckdb\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b76ae1f0-334e-41c0-9533-407c879b4ad6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import ibis\n",
+    "\n",
+    "con = ibis.duckdb.connect()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "837aa4e0-5eeb-48c1-97ce-3f8706503911",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "redlines = con.read_geo(\n",
+    "    \"/vsicurl/https://dsl.richmond.edu/panorama/redlining/static/mappinginequality.gpkg\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4d3319fa-b3b4-4931-b073-98b649e41b65",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "city = redlines.filter(redlines.city == \"New Haven\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "34f7f4d6-28d6-4716-8e03-ac32c6ae3bb7",
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "city_gdf = city.head().execute()\n",
+    "city_gdf.plot()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d37a610a-1444-43a3-900f-dfe16a890ab9",
+   "metadata": {},
+   "source": [
+    "## OK, but what about spatial context?\n",
+    "\n",
+    "I want to explore this data more interactively."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6e68aaac-dfc0-42d8-a3b9-05fce59524b2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from jupytergis import explore\n",
+    "\n",
+    "# Open a new exploration window\n",
+    "explore(city_gdf, layer_name=\"New Haven\", basemap=\"dark\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

lite/environment.yml

@@ -11,6 +11,7 @@ dependencies:
   - ypywidgets>=0.9.6,<0.10.0
   - comm>=0.1.2,<0.2.0
   - pydantic>=2,<3
+  - sidecar
   - pip:
       - yjs-widgets>=0.4,<0.5
       - my-jupyter-shared-drive<0.2.0

packages/base/src/panelview/components/layers.tsx

@@ -171,6 +171,7 @@ function LayersBodyComponent(props: IBodyProps): JSX.Element {
     model?.sharedModel.layersChanged.connect(updateLayers);
     model?.sharedModel.layerTreeChanged.connect(updateLayers);
 
+    updateLayers();
     return () => {
       model?.sharedModel.layersChanged.disconnect(updateLayers);
       model?.sharedModel.layerTreeChanged.disconnect(updateLayers);

python/jupytergis/jupytergis/__init__.py

@@ -1,3 +1,3 @@
 __version__ = "0.4.4"
 
-from jupytergis_lab import GISDocument  # noqa
+from jupytergis_lab import GISDocument, explore  # noqa

python/jupytergis_lab/jupytergis_lab/__init__.py

@@ -9,6 +9,7 @@
     __version__ = "dev"
 
 from .notebook import GISDocument  # noqa
+from .notebook.explore import explore
 
 
 def _jupyter_labextension_paths():

python/jupytergis_lab/jupytergis_lab/notebook/explore.py

@@ -0,0 +1,127 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal, Optional
+import re
+
+from jupytergis_lab import GISDocument
+
+
+@dataclass
+class Basemap:
+    name: str
+    url: str
+
+
+BasemapChoice = Literal["light", "dark", "topo"]
+_basemaps: dict[BasemapChoice, list[Basemap]] = {
+    "light": [
+        Basemap(
+            name="ArcGIS dark basemap",
+            url="https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Base/MapServer/tile/{z}/{y}/{x}.pbf",
+        ),
+        Basemap(
+            name="ArcGIS dark basemap reference",
+            url="https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Reference/MapServer/tile/{z}/{y}/{x}.pbf",
+        ),
+    ],
+    "dark": [
+        Basemap(
+            name="ArcGIS light basemap",
+            url="https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Dark_Gray_Base/MapServer/tile/{z}/{y}/{x}.pbf",
+        ),
+        Basemap(
+            name="ArcGIS light basemap reference",
+            url="https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Dark_Gray_Reference/MapServer/tile/{z}/{y}/{x}.pbf",
+        ),
+    ],
+    "topo": [
+        Basemap(
+            name="USGS topographic basemap",
+            url="https://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/tile/{z}/{y}/{x}",
+        ),
+    ],
+}
+
+
+def explore(
+    data: str | Path | Any,
+    *,
+    layer_name: Optional[str] = "Exploration layer",
+    basemap: BasemapChoice = "topo",
+) -> GISDocument:
+    """Run a JupyterGIS data interaction interface alongside a Notebook.
+
+    :param data: A GeoDataFrame or path to a GeoJSON file.
+
+    :raises FileNotFoundError: Received a file path that doesn't exist.
+    :raises NotImplementedError: Received an input value that isn't supported yet.
+    :raises TypeError: Received an object type that isn't supported.
+    :raises ValueError: Received an input value that isn't supported.
+    """
+    doc = GISDocument()
+
+    for basemap_obj in _basemaps[basemap]:
+        doc.add_raster_layer(basemap_obj.url, name=basemap_obj.name)
+
+    _add_layer(doc=doc, data=data, name=layer_name)
+
+    # TODO: Zoom to layer. Currently not exposed in Python API.
+
+    doc.sidecar(title="JupyterGIS explorer")
+
+    # TODO: should we return `doc`? It enables the exploration environment more usable,
+    # but by default, `explore(...)` would display a widget in the notebook _and_ open a
+    # sidecar for the same widget. The user would need to append a semicolon to disable
+    # that behavior. We can't disable that behavior from within this function to the
+    # best of my knowlwedge.
+
+
+def _add_layer(
+    *,
+    doc: GISDocument,
+    data: Any,
+    name: str,
+) -> str:
+    """Add a layer to the document, autodetecting its type.
+
+    This method currently supports only GeoDataFrames and GeoJSON files.
+
+    :param doc: A GISDocument to add the layer to.
+    :param data: A data object. Valid data objects include geopandas GeoDataFrames and paths to GeoJSON files.
+    :param name: The name that will be used for the layer.
+
+    :return: A layer ID string.
+
+    :raises FileNotFoundError: Received a file path that doesn't exist.
+    :raises NotImplementedError: Received an input value that isn't supported yet.
+    :raises TypeError: Received an object type that isn't supported.
+    :raises ValueError: Received an input value that isn't supported.
+    """
+    if isinstance(data, str):
+        if re.match(r"^(http|https)://", data) is not None:
+            raise NotImplementedError("URLs not yet supported.")
+        else:
+            data = Path(data)
+
+    if isinstance(data, Path):
+        if not data.exists():
+            raise FileNotFoundError(f"File not found: {data}")
+
+        ext = data.suffix.lower()
+
+        if ext in [".geojson", ".json"]:
+            return doc.add_geojson_layer(path=data, name=name)
+        elif ext in [".tif", ".tiff"]:
+            raise NotImplementedError("GeoTIFFs not yet supported.")
+        else:
+            raise ValueError(f"Unsupported file type: {data}")
+
+    try:
+        from geopandas import GeoDataFrame
+
+        if isinstance(data, GeoDataFrame):
+            return doc.add_geojson_layer(data=data.to_geo_dict(), name=name)
+    except ImportError:
+        pass
+
+    raise TypeError(f"Unsupported input type: {type(data)}")