Welcome to the JupyterGIS collaborative features tutorial. JupyterGIS enables the seamless sharing of notebooks and GIS files, allowing teams—including GIS specialists, data analysts, and other experts—to collaborate on spatial projects in a shared environment. This guide will provide the tools and steps needed to collaborate effectively, using features like real-time editing, cursor tracking, follow mode, and annotations.

Comment: Motivation

Collaboration is at the heart of effective GIS projects. Teams often include members with diverse backgrounds, skills, and areas of expertise. Without robust collaborative tools, it can become challenging to share insights, make real-time decisions, and maintain consistency across project workflows. JupyterGIS simplifies collaboration by providing real-time editing, annotations, and interactive features that allow teams to seamlessly integrate their work.

Agenda

In this tutorial, we will learn about:

1. Launching Your Collaborative Session
2. Real-Time Collaboration on a GIS File
3. Tracking Collaborators with Cursors
4. Using Follow Mode
5. Adding Annotations and Comments
6. Collaborating on Notebooks (Optional)

Tip: Simulating Multi-User Environments

The JupyterGIS collaborative training material is designed to help users explore geospatial workflows in a collaborative Jupyter environment. This training is intended to be used in pairs or small teams, even when following a self-paced approach. To simulate real-time collaboration, we recommend using an additional browser window or an anonymous session to represent another user. This setup allows participants to better understand multi-user interactions, shared geospatial analysis, and version control within Jupyter-based environments.

Launching Your Collaborative Session

In this section, we will learn how to launch a collaborative session in JupyterGIS and invite collaborators to join. This section of the tutorial is required to be completed by only one user (the lead user) in the session.

Hands On: Starting a Collaborative Session

1. Open your browser and navigate to https://climate.usegalaxy.eu/, then log in or register for an account if you haven’t already, to access the JupyterGIS platform.
2. On the left sidebar, click Tools.
3. In the search box, type JupyterGIS.
4. Click Interactive JupyterGIS Notebook and then click the Run Tool button.
5. Click on Interactive Tools on the left sidebar.
6. Wait a few minutes until the job status changes to “running.”
7. Click on the Jupyter Interactive GIS Tool link that appears to open JupyterLab.
8. Scroll down to the Other section and click GIS File to open a blank canvas for your project
9. Notice that you are given an anonymous username, which you can see in the upper right corner. Every user in the project will be assigned an anonymous username.
10. Click on the Share button in your interface in the upper right corner, then click on the Copy Link button to invite collaborators to your session.
11. When your colleagues join using the link, their usernames appear in the top right corner. This lets you know exactly who is working on the document. There are two more collaborators in the session in the example below.

Real-Time Collaboration on a GIS File

In this section, we will explore how to collaborate on a GIS file in real time. The remaining sections of the tutorial are required to be completed by both the lead and the collaborating users in the session.

When you make changes to your GIS file such as adding a new layer, or updating the layer appearance, the changes are reflected for all collaborators in your session in real time.

Hands On: Adding and Editing Layers

1. As the lead user, open the layer browser and select OpenStreetMap.Mapnik. Notice that all users in the session can see the new layer in real time.
2. Ask one of the collaborators to add the Libraries in France shapefile layer using the add shapefile layer menu by clicking + -> New Vector Layer → New Shapefile Layer -> pasting the provided URL.

https://public.opendatasoft.com/api/explore/v2.1/catalog/datasets/osm-france-library/exports/shp

Question: Adding a New Layer

1. As the lead user, add the World Administrative Boundaries layer using the add shapefile layer menu.

   https://public.opendatasoft.com/api/explore/v2.1/catalog/datasets/world-administrative-boundaries/exports/shp
   

2. Change the fill color to yellow.
3. Ask one of the collaborators to set the opacity to 0.2.

Solution

• You can add the layer by clicking + → New Vector Layer → New Shapefile Layer → pasting the provided URL.
• To change the fill color, click on the layer in the left sidebar, then select Edit Symbology and choose yellow for the fill color. You can check the Getting Started with JupyterGIS tutorial for more details on how to customize the layer appearance.
• To set the opacity to 0.2, the collaborating user can click on the layer in the left sidebar, then adjust the opacity slider to 0.2 on the right sidebar, then click Ok.

Tracking Collaborators with Cursors

Each user’s cursor appears on the document in the same color as their icon. This feature makes it easy to see what your teammates are focused on.

Hands On: Tracking Collaborators with Cursors

1. Ask one of the collaborators to move their cursor around the document.
2. Spot their cursor to find out where on the map they are working.

Using Follow Mode

Follow mode allows you to track another user’s activity in the document in real time. When enabled, you’ll see their actions as they navigate and edit. This feature is ideal for live demonstrations, interactive sessions, and collaborative meetings, as it lets you quickly align your view with a teammate’s actions and provide immediate feedback.

Hands On: Activating Follow Mode

1. Click on a collaborator’s user icon in the upper right corner to activate the follow mode. Observe that the document will then have a frame in their assigned color.
2. Ask the followed user to pan and zoom the map. Notice that your screen will follow their movements in real time.
3. Click on the user icon again to exit follow mode.

Question: Using Follow Mode

• When you activate follow mode, what color appears around the document frame?
• Ask one of the collaborators to activate follow mode on you.
• What color do they see?

Solution

• The color of the frame is the same as the color of the user icon. This indicates the user whose activity is being followed.

Adding Annotations and Comments

Annotations and comments let you add notes directly on your GIS file, which makes it easier for your team to track important details, provide context, ask questions, or share insights.

Hands On: Adding Annotations and Comments

1. Right-click anywhere on your GIS file to open the context menu, then select Add Annotation from the menu to create an annotation. All collaborators can see the new annotation in real time.
2. Click on the created annotation and type a comment.
3. Ask one of the collaborators to open the right sidebar to view all annotations and comments in the document, and click on the middle button to locate the annotation.
4. Click on the user icon again to exit follow mode.

Collaborating on Notebooks (Optional)

Real-time collaboration in notebooks is a powerful tool for teams working on code together. It enables multiple users to write, edit, and run code simultaneously. This feature is ideal for live coding sessions, debugging, and data analysis projects.

Tip: Prerequisite

This section requires basic Python programming knowledge. If you are not familiar with Python, we recommend completing the Introduction to Python tutorial first.

Hands On: Real-Time Code Collaboration

1. Click on the + icon to open the Launcher, then select the Python kernel under Notebook to create a notebook. Once a notebook is created, it is automatically accessible to all collaborators—no additional sharing is needed.
2. Ask one of the collaborators to open the newly created notebook by clicking on the explorer button in the left sidebar, then locating and clicking on the notebook. Anyone in the session can open, edit, and run the notebooks.
3. As you write or execute code, every change is visible to your team instantly. Create a new code cell and write the following code. Notice that all collaborators can see the code in real time.

   from jupytergis import GISDocument
   doc = GISDocument('untitled.jGIS')
   doc
   

4. Rename the “Custom Shapefile Layer” to “libraries” in the GIS file.
5. Find the layer ID of the libraries layer.

   layers = doc.layers
   libraries_layer_id = None
   for layer_id, data in layers.items():
       if data.get("name", "").lower() == "libraries":
           libraries_layer_id = layer_id
           break
   

6. Ask one of the collaborators to filter all libraries that have wheelchair access. They can do this by running the following code:

   doc.add_filter(libraries_layer_id, 'all', 'wheelchair', '==', 'yes')
   

Question

• Create a new notebook and load your GIS document.
• In the GIS file, add a new layer with the following URL: https://public.opendatasoft.com/api/explore/v2.1/catalog/datasets/openaq/exports/geojson
• Ask one of the collaborators to open the notebook, write the code to remove the air quality layer of the GIS file and run the code cell.

Solution

• Create a new notebook from the JupyterLab launcher (select Python kernel).
• Load your GIS document using the following Python code:

  from jupytergis import GISDocument
  doc = GISDocument("untitled.jGIS")
  

• Add the air quality layer by clicking + → New Vector Layer → Add GeoJSON Layer → pasting the provided URL.
• The collaborator can add and execute the following code to list all layers:

  doc.layers
  

• Then they can find the air quality layer ID (the layer with the name Custom GeoJSON Layer) and remove it using:

  air_quality_layer_id = "your_layer_id"
  doc.remove_layer(air_quality_layer_id)
  

Congratulations! You have completed the Collaboration Features of JupyerGIS tutorial. You now have the knowledge and tools to collaborate effectively with your team on GIS files and notebooks.

If you’d like to explore more of JupyterGIS’ functionality, please view our JupyterGIS announcement blog post for video demos of more features.

You've Finished the Tutorial

Please also consider filling out the Feedback Form as well!

Frequently Asked Questions

• Topic FAQs
• Galaxy FAQs
• GTN Matrix Chat
• Galaxy Help Forum

Feedback

Did you use this material as an instructor? Feel free to give us feedback on how it went.
Did you use this material as a learner or student? Click the form below to leave feedback.

Citing this Tutorial

1. Elifsu Filiz, Anne Fouilloux, Collaboration with JupyterGIS (Galaxy Training Materials). https://training.galaxyproject.org/training-material/topics/climate/tutorials/jupytergis_collaboration/tutorial.html Online; accessed TODAY
2. Hiltemann, Saskia, Rasche, Helena et al., 2023 Galaxy Training: A Powerful Framework for Teaching! PLOS Computational Biology 10.1371/journal.pcbi.1010752
3. Batut et al., 2018 Community-Driven Data Analysis Training for Biology Cell Systems 10.1016/j.cels.2018.05.012

BibTeX

@misc{climate-jupytergis_collaboration,
author = "Elifsu Filiz and Anne Fouilloux",
	title = "Collaboration with JupyterGIS (Galaxy Training Materials)",
	year = "",
	month = "",
	day = "",
	url = "\url{https://training.galaxyproject.org/training-material/topics/climate/tutorials/jupytergis_collaboration/tutorial.html}",
	note = "[Online; accessed TODAY]"
}
@article{Hiltemann_2023,
	doi = {10.1371/journal.pcbi.1010752},
	url = {https://doi.org/10.1371%2Fjournal.pcbi.1010752},
	year = 2023,
	month = {jan},
	publisher = {Public Library of Science ({PLoS})},
	volume = {19},
	number = {1},
	pages = {e1010752},
	author = {Saskia Hiltemann and Helena Rasche and Simon Gladman and Hans-Rudolf Hotz and Delphine Larivi{\`{e}}re and Daniel Blankenberg and Pratik D. Jagtap and Thomas Wollmann and Anthony Bretaudeau and Nadia Gou{\'{e}} and Timothy J. Griffin and Coline Royaux and Yvan Le Bras and Subina Mehta and Anna Syme and Frederik Coppens and Bert Droesbeke and Nicola Soranzo and Wendi Bacon and Fotis Psomopoulos and Crist{\'{o}}bal Gallardo-Alba and John Davis and Melanie Christine Föll and Matthias Fahrner and Maria A. Doyle and Beatriz Serrano-Solano and Anne Claire Fouilloux and Peter van Heusden and Wolfgang Maier and Dave Clements and Florian Heyl and Björn Grüning and B{\'{e}}r{\'{e}}nice Batut and},
	editor = {Francis Ouellette},
	title = {Galaxy Training: A powerful framework for teaching!},
	journal = {PLoS Comput Biol}
}

                   

Galaxy Administrators: Install the missing tools

You can use Ephemeris's shed-tools install command to install the tools used in this tutorial.

shed-tools install [-g GALAXY] [-a API_KEY] -t <(curl https://training.galaxyproject.org/training-material/api/topics/climate/tutorials/jupytergis_collaboration/tutorial.json | jq .admin_install_yaml -r)

Alternatively you can copy and paste the following YAML

---
install_tool_dependencies: true
install_repository_dependencies: true
install_resolver_dependencies: true
tools: []

Feedback

No feedback has been recieved yet for this training. Be the first one by filling in the feedback form.