Add `explore()` function and `GISDocument.sidecar()` method by mfisher87 · Pull Request #340 · geojupyter/jupytergis

mfisher87 · 2025-01-16T01:04:51Z

Description

Implemens the 💃 GIS Bounce 🕺 in JupyterGIS.

This is a streamlined version of the QGIS Bounce workflow.

jupytergis-explore-demo.mp4

Exploring a dataframe (example notebook) is just one line of code (excluding imports, of course 😉):

from jupytergis import explore

explore(gdf)

This opens a side panel with JupyterGIS displaying the data with a basemap.

Still TODO, and I don't have time today:

Rebase and credit contributors from 4/16 hackathon (see https://github.com/mfisher87/jupytergis/tree/sidecar-experiment-bkp commits)
Add a video demo to this PR
Pass in dataframe directly
Support more file types and data types -- future PR?
BUG: The layers list is empty when the sidecar is first focused. Workaround: Load a different .jGIS file or open a notebook widget to trigger the layers list to populate; then focus back to the sidecar to update the layers list to show the layers in the sidecar.
Open the JGIS sidebars when displaying. This can be implemented using the docmanager approach, or we can find another way.

Checklist

PR has a descriptive title and content.
PR description contains references to any issues the PR resolves, e.g. Resolves #XXX.
PR has one of the labels: documentation, bug, enhancement, feature, maintenance
Checks are passing.
Failing lint checks can be resolved with:
- pre-commit run --all-files
- jlpm run lint

📚 Documentation preview: https://jupytergis--340.org.readthedocs.build/en/340/
💡 JupyterLite preview is available from the doc, by clicking on

github-actions · 2025-01-16T01:05:05Z

👈 Launch a Binder on branch mfisher87/jupytergis/sidecar-experiment

github-actions · 2025-01-16T01:14:32Z

Integration tests report: appsharing.space

python/jupytergis_lab/src/notebookrenderer.ts

brichet · 2025-02-06T14:30:19Z

FYI @mfisher87 #419 has been merged, you can probably revive or remake this PR.

mfisher87 · 2025-02-06T17:59:34Z

Awesome work @brichet !! I hope to have some time to play with this tomorrow.

python/jupytergis_lab/jupytergis_lab/notebook/geo_debug.py

python/jupytergis_lab/src/notebookrenderer.ts

mfisher87 · 2025-04-17T20:13:44Z

python/jupytergis_lab/jupytergis_lab/notebook/gis_document.py

        """
        return self._layerTree.to_py()

-    def save_as(self, path: str | Path) -> None:


This copies the document, whereas a "save as" operation would also change the current working document to alter the new file. We don't have the comms setup to do this yet. Restored the export_to_qgis public API function for now as well.

mfisher87 · 2025-04-17T20:26:39Z

BUG: The layers list is empty even when the sidecar is focused. I need to load a .jGIS file or open a notebook widget to populate the layers list, then focus back to the sidecar, and then it works.

mfisher87 · 2025-04-18T00:25:23Z

All, we gave an internal demo of this feature today, and @fperez was over the moon to see it in action, even at this early stage. Couldn't have shown it today without your support. It will be even more impressive when we show it at the conference in a couple weeks :)

Thank you!! ❤️

fperez · 2025-04-18T00:30:36Z

Indeed, while there's still work to do, this is already very impressive progress!! Thanks team and congrats!!! 🚀🎉

SylvainCorlay · 2025-04-18T08:07:36Z

Hey @mfisher87 I extracted the CSS fix on output views in #643, so that it can be merged independently, cherry-picking your commit.

mfisher87 · 2025-04-23T03:20:19Z

All, [WIP] tag removed; ready for review!

arjxn-py · 2025-04-23T17:38:31Z

Just triggered the lite integration test again
As i don't see it failing with the latest lite deployment:

mfisher87 · 2025-04-24T03:12:12Z

https://jupytergis--340.org.readthedocs.build/en/340/lite/lab/

Oof. I'm not sure what's up here; jupyter-collaboration v4 is out which eliminates the RTC prefix, but we are pinned to <4.

martinRenou · 2025-04-24T07:08:53Z

docs/environment-docs.yml

      # See: https://github.com/geojupyter/jupytergis/issues/585
      - ../python/jupytergis_core
      - ../python/jupytergis_lab
+      - ../python/jupytergis


I believe this is the culprit for the failure in the docs. We can't have jupytergis installed in the lite deployment of the docs.

It needs to be jupytergis_lite or nothing.

brichet

Thanks for working on this @mfisher87 .
I added a few comments below.

docs/environment-docs.yml

docs/user_guide/python_api.md

python/jupytergis_lab/jupytergis_lab/explore.py

python/jupytergis_lab/jupytergis_lab/notebook/gis_document.py

python/jupytergis_lab/style/base.css

geojupyter#340 (comment)

geojupyter#340 (comment) Co-authored-by: martinRenou <martin.renou@gmail.com> Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com>

Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com>

Co-authored-by: martinRenou <martin.renou@gmail.com> Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com>

mfisher87 · 2025-04-24T23:14:50Z

The Lite tests are still timing out 😖

martinRenou · 2025-04-25T06:03:53Z

@mfisher87 I tried the lite deployment in the docs, it looks like the import fails with:

I assume this is the reason for the timeout (waiting for the map that never shows up in the notebook cell output because of the import error)

I believe it's due to jupyterlite-xeus installing pip dependencies with --no-deps (that's another story...). Can you try adding the sidecar dependency here: https://github.com/geojupyter/jupytergis/blob/main/lite/environment.yml#L13

Also, we should export explore here like you did for the main metapackage https://github.com/geojupyter/jupytergis/blob/main/python/jupytergis_lite/jupytergis/__init__.py

martinRenou

I took the liberty to make the last remaining changes to get the lite deployment to work, I hope you don't mind! Thanks 🚀

mfisher87 · 2025-04-25T17:39:28Z

I took the liberty to make the last remaining changes to get the lite deployment to work, I hope you don't mind! Thanks 🚀

Not at all, that's greatly appreciated 🙇

mfisher87 · 2025-04-25T17:40:13Z

python/jupytergis_lite/jupytergis/__init__.py

 __version__ = "0.4.4"

-from jupytergis_lab import GISDocument  # noqa
+from jupytergis_lab import GISDocument, explore  # noqa


Ahh, didn't know this was needed, thanks so much 🙇

…er#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 <gjmooney@asu.edu> Co-authored-by: Kristin Davis <kristin.p.davis@gmail.com> Co-authored-by: Sanjay Bhangar <sanjay@developmentseed.org> Co-authored-by: Aman Ahuja <amanahuja@gmail> Co-authored-by: Jonathan Marokhovsky <jmarokhovsky@clarku> Co-authored-by: Tammy Woodard <tawoodard@clarku.edu> * 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 <32258950+brichet@users.noreply.github.com> * Copy docstring raises entries from underlying method docstring * Attempt to fix lite integration tests geojupyter#340 (comment) Co-authored-by: martinRenou <martin.renou@gmail.com> Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com> * Add note about CSS eventually added in JupyterLab Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com> * Move explore module into notebook subpackage Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com> * Make generic add_layer method a private internal function Co-authored-by: martinRenou <martin.renou@gmail.com> Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com> * 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 <gjmooney@asu.edu> Co-authored-by: Kristin Davis <kristin.p.davis@gmail.com> Co-authored-by: Sanjay Bhangar <sanjay@developmentseed.org> Co-authored-by: Aman Ahuja <amanahuja@gmail> Co-authored-by: Jonathan Marokhovsky <jmarokhovsky@clarku> Co-authored-by: Tammy Woodard <tawoodard@clarku.edu> Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com> Co-authored-by: martinRenou <martin.renou@gmail.com>

mfisher87 added the enhancement New feature or request label Jan 16, 2025

mfisher87 changed the title ~~Prototype of streamlined Graphical GIS <-> Notebook "bounce" workflow~~ [WIP] Prototype of streamlined Graphical GIS <-> Notebook "bounce" workflow Jan 16, 2025

martinRenou reviewed Jan 16, 2025

View reviewed changes

python/jupytergis_lab/src/notebookrenderer.ts Outdated Show resolved Hide resolved

mfisher87 force-pushed the sidecar-experiment branch 3 times, most recently from 9103433 to 5b96097 Compare January 28, 2025 02:03

brichet mentioned this pull request Jan 28, 2025

Display toolbar in widget view #397

Closed

mfisher87 linked an issue Mar 3, 2025 that may be closed by this pull request

Implement a JGIS workflow to streamline the "QGIS bounce" pattern #513

Closed

mfisher87 force-pushed the sidecar-experiment branch from 8cd5bbc to fe74cbf Compare March 25, 2025 23:11

martinRenou reviewed Mar 26, 2025

View reviewed changes

python/jupytergis_lab/jupytergis_lab/notebook/geo_debug.py Outdated Show resolved Hide resolved

martinRenou reviewed Mar 26, 2025

View reviewed changes

python/jupytergis_lab/jupytergis_lab/notebook/geo_debug.py Outdated Show resolved Hide resolved

mfisher87 mentioned this pull request Mar 31, 2025

Implement a JGIS workflow to streamline the "QGIS bounce" pattern #513

Closed

mfisher87 force-pushed the sidecar-experiment branch from 1840aff to 829c307 Compare April 2, 2025 00:03

mfisher87 force-pushed the sidecar-experiment branch 4 times, most recently from 3ad817a to 12fae9c Compare April 17, 2025 04:06

mfisher87 commented Apr 17, 2025

View reviewed changes

python/jupytergis_lab/src/notebookrenderer.ts Outdated Show resolved Hide resolved

mfisher87 force-pushed the sidecar-experiment branch from 12fae9c to 44f805a Compare April 17, 2025 19:16

mfisher87 commented Apr 17, 2025

View reviewed changes

mfisher87 changed the title ~~[WIP] Prototype of streamlined Graphical GIS <-> Notebook "bounce" workflow~~ [WIP] Streamlined Graphical GIS <-> Notebook "bounce" workflow Apr 17, 2025

SylvainCorlay mentioned this pull request Apr 18, 2025

Fill vertical space in linked output & sidecar views #643

Merged

mfisher87 force-pushed the sidecar-experiment branch from 29e7b31 to b47a01e Compare April 23, 2025 02:29

mfisher87 changed the title ~~[WIP] Add explore() function and GISDocument.sidecar() method~~ Add explore() function and GISDocument.sidecar() method Apr 23, 2025

mfisher87 requested a review from gjmooney April 23, 2025 03:16

Copy docstring raises entries from underlying method docstring

ddf3d48

mfisher87 mentioned this pull request Apr 23, 2025

Lite integration tests timing out #622

Closed

martinRenou reviewed Apr 24, 2025

View reviewed changes

brichet reviewed Apr 24, 2025

View reviewed changes

mfisher87 mentioned this pull request Apr 24, 2025

Generate API docs from jupytergis instead of jupytergis_lab #661

Open

mfisher87 added a commit to mfisher87/jupytergis that referenced this pull request Apr 24, 2025

Attempt to fix lite integration tests

7165e27

geojupyter#340 (comment)

Attempt to fix lite integration tests

0b2eab4

geojupyter#340 (comment) Co-authored-by: martinRenou <martin.renou@gmail.com> Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com>

mfisher87 force-pushed the sidecar-experiment branch from 66c3cd6 to b84c701 Compare April 24, 2025 22:37

Add note about CSS eventually added in JupyterLab

1503af3

Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com>

mfisher87 force-pushed the sidecar-experiment branch from b84c701 to 1503af3 Compare April 24, 2025 22:38

mfisher87 and others added 2 commits April 24, 2025 16:50

Move explore module into notebook subpackage

595dfa3

Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com>

Make generic add_layer method a private internal function

119c281

Co-authored-by: martinRenou <martin.renou@gmail.com> Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com>

Merge branch 'main' into sidecar-experiment

9994796

martinRenou added 3 commits April 25, 2025 08:38

Missing sidecar and export

56bc8bd

Merge branch 'main' into sidecar-experiment

dff4346

Missing sidecar in docs

9a909e4

martinRenou approved these changes Apr 25, 2025

View reviewed changes

martinRenou merged commit 8f2ff7f into geojupyter:main Apr 25, 2025
14 checks passed

mfisher87 commented Apr 25, 2025

View reviewed changes

mfisher87 deleted the sidecar-experiment branch April 25, 2025 17:40

Conversation

mfisher87 commented Jan 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

github-actions bot commented Jan 16, 2025

Uh oh!

github-actions bot commented Jan 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

brichet commented Feb 6, 2025

Uh oh!

mfisher87 commented Feb 6, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mfisher87 Apr 17, 2025

Choose a reason for hiding this comment

Uh oh!

mfisher87 commented Apr 17, 2025

Uh oh!

mfisher87 commented Apr 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fperez commented Apr 18, 2025

Uh oh!

SylvainCorlay commented Apr 18, 2025

Uh oh!

mfisher87 commented Apr 23, 2025

Uh oh!

arjxn-py commented Apr 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mfisher87 commented Apr 24, 2025

Uh oh!

martinRenou Apr 24, 2025

Choose a reason for hiding this comment

Uh oh!

brichet left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mfisher87 commented Apr 24, 2025

Uh oh!

martinRenou commented Apr 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

martinRenou left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mfisher87 commented Apr 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mfisher87 Apr 25, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

mfisher87 commented Jan 16, 2025 •

edited

Loading

github-actions bot commented Jan 16, 2025 •

edited

Loading

mfisher87 commented Apr 18, 2025 •

edited

Loading

arjxn-py commented Apr 23, 2025 •

edited

Loading

martinRenou commented Apr 25, 2025 •

edited

Loading

martinRenou left a comment •

edited

Loading

mfisher87 commented Apr 25, 2025 •

edited

Loading