You may know that the ArcGIS API for Python provides simple and efficient tools for performing GIS analysis, visualizing your spatial data, and administrating your web GIS—but did you also know that the ArcGIS API for Python integrates smoothly with the larger open-source Python ecosystem? These non-Esri software packages are free to use, and many can provide customization options and new features that enhance your Python development experience. There are many software packages worth exploring—but perhaps the most useful of these software offerings is Project Jupyter.
Jupyter’s flagship software offering is the Jupyter Notebook. Jupyter Notebooks are web documents that let you run Python code in an interactive manner, annotate your code with maps/charts/text/equations, and share your results with others seamlessly. Using Python in Jupyter Notebooks has become the preferred workflow for data scientists and GIS analysts in many use cases: data cleaning and transformation, statistical modeling, data visualization, machine learning, and more.
The ArcGIS API for Python is designed to work extremely well with the Jupyter Notebook format. Historically, this was done by running the
jupyter notebook command to launch the ‘Classic Notebook’ server. While we will continue to support this Classic Notebook experience, v1.5.0 of the Python API also supports the JupyterLab experience. JupyterLab interacts with the same Jupyter Notebook format, but offers a robust file explorer, a more intuitive user interface, support for interacting with other file types, etc. This makes JupyterLab more of an IDE when compared to the Classic Notebook server.
In this blog post, we will walk through some of the benefits of using JupyterLab in your development and data science workflows. The below gif shows what this workflow might look like: data is read in from a local csv file, Python code is run in the Jupyter Notebook that transforms that csv data, and the result is visualized on a map.
To start using the ArcGIS API for Python with JupyterLab, follow these installation steps:
1) Install >=v1.5.0 of the ArcGIS API for Python by following this installation guide.
2) Run the following 2 commands:
jupyter labextension install @jupyter-widgets/jupyterlab-manager
jupyter labextension install firstname.lastname@example.org
1.5.0with the exact version number of the Python API you have installed.
3) Now that you have set up the arcgis-map-ipywidget extension, run
jupyter lab from the command prompt to launch an instance of JupyterLab.
If you have never used the ArcGIS API for Python before, read the the getting started guide to see how you can leverage the Python API for GIS visualization and analysis, spatial data management, and GIS system administration.
jupyter lab, you will notice a file explorer on the left pane of the main view. You can navigate through your filesystem for Jupyter Notebook files (.ipynb), JSON files (.json), CSV files (.csv), etc. You can also create new Jupyter Notebooks.
You may noticed that a notebook opened from the file explorer will appear in a new window or a new tab. JupyterLab can manage these windows powerfully: you can place notebooks side by side, resize windows, and organize notebooks by tabs by simply clicking and dragging.
Similar to the windows, JupyterLab allows users to move cells in a notebook by dragging and dropping them. JupyterLab supports dragging cells in the same notebook, as well as dragging cells from one notebook to another notebook. Open a sample notebook in JupyterLab, click the area to the left of a code cell, and drag it around.
JupyterLab offers some additional code cell features, such as
- Selecting multiple cells by holding the Shift key
- The right click context menu for ‘Copy Cells’, ‘Cut Cells’, etc.
- The right click context menu for ‘Create New View For Output’. This context menu option will take any cell output and duplicate it in a new window, allowing you to stack it, split it, etc.
The MapView class allows for visualization of geographic locations, visualizing GIS content, and viewing the results of spatial analysis. To use this map widget, run
map = gis.map() to create a new MapView instance and assign it to the
map variable. You can then display the widget in the output cell of a notebook, in a new window by calling
map.toggle_window_view(), or by pressing the relevant UI button in the widget.
From here, you can programmatically specify properties of the map widget such as
map.mode = '2D' will give you a two-dimensional view of the widget, while
map.mode = '3D' will give you a three-dimensional view. You can add layers via
map.add_layer(some_layer), you can draw geometries via
map.draw(some_featureset), and more. See the API reference or this guide page for more information about these basic map widget use cases, programmatic control of new windows, etc.
You can also view
WebScenes by getting the relevant item , creating a new instance of the
WebScenes class, and displaying it in the output cell. These output cells can also be brought to new window views like the widget.
Have you liked what you’ve seen and can’t wait to do more with ArcGIS API for Python and JupyterLab? View the JupyterLab guide page for some sample code snippets or try one of our sample notebooks! As always, please feel free leave us a comment, suggest a feature, or report a bug about your experience.
We look forward to seeing what you will create in JupyterLab!