ArcGIS Notebooks runs a Jupyter notebook environment, which provides a streamlined cell-based workspace. This topic walks through the basic commands and aspects of working in Notebooks, including shortcuts and best practices.
Specify a cell's type
There are three types of cells you can use in a notebook. When you have selected a cell with the pointer, you can change the cell's type using the drop-down list on the toolbar.
The following are the three available types:
- Code—The notebook will interpret all content in a code cell in the Python language. When writing Python code, typing certain strings, such as from or the equal sign (=), will prompt the notebook to automatically recolor or highlight them for clarity. Any line of code that starts with a number sign (#) will be interpreted as a comment, colored green and italicized, and will not be run as code by the notebook.
- Markdown—The notebook will interpret all content in a Markdown cell in the Markdown language. This is a simple language for formatting rich text, used across the internet by clients such as GitHub. See the Markdown Guide online for a reference to using Markdown. Running a Markdown cell will turn its content into rich text. Any lines that start with one or multiple number signs (#) will be formatted as headings. You can also add raw HTML code to Markdown cells.
- Raw—The notebook will not process content in a Raw cell. This cell type is rarely used.
The use of rich text and code comments will make the notebooks more readable and valuable to users with whom they are shared.
Work with cells
For a notebook to run code, the code must be contained in a cell. The code in cells allows you to define variables and run functions contained in Python libraries.
To define a variable, run a cell that contains a variable statement, including an equal sign (=). The default notebook template, for example, launches having defined a variable gis. If you run a cell containing only that variable name, gis, the notebook will return the URL of your ArcGIS Enterprise portal as an output.
Note:
The iPython commands using exclamation points, such as !cd <directory>, to change directories from the command line will not work in ArcGIS Notebooks. Instead, use commands without exclamation points, such as cd <directory>.
Note:
When authoring notebooks, use full paths to directories and files in the workspace directory.
For example, use /arcgis/home/test.gdb instead of home/test.gdb.
To run a Python function, provide the function's syntax and any arguments required or accepted by the function. See the Use functions in a cell section below to learn more.
You can create a cell by pressing Shift+Enter, or by clicking Insert on the menu ribbon, which allows you to insert a new cell above or below your current cell.
Import libraries and modules
In the default notebook template, ArcGIS Notebooks only imports the gis module from the ArcGIS API for Python. Typically, you will want to use additional Python libraries available in the notebook's runtime. To access these libraries, run an import command.
See all Python libraries available in ArcGIS Notebooks
Create a cell and type import <library>, and then run the cell.
In the ArcGIS API for Python and ArcPy, and in some other cases, Python libraries are organized into modules. To access the libraries within a module, declare the module to access with a from statement and then declare a library using an import statement. For example, to call the WebScene library from the mapping module in the ArcGIS API for Python, run the following command in a cell:
from arcgis.map import Scene
ArcGIS Notebooks includes an autocomplete feature when running cells. You can use it to help you find the libraries and modules you need. In a cell, type the first portion of your command, and press Tab to activate the autocomplete feature. It provides possible values that can complete the command.
For example, if you type arcgis. and then press Tab, the notebook will provide a drop-down list of all the modules available in the ArcGIS API for Python. You can use the up and down arrows to browse the list; when you find the option you want, press Enter to insert it into your line of code.
To learn more about how the ArcGIS API for Python and ArcPy work in notebooks, see the following topics:
Use functions in a cell
To perform analysis and work with data in notebooks, you use Python functions. Functions are contained within Python libraries, and often take input arguments to specify how they will run and what content they will run on.
The notebook's autocomplete tool can help you find functions by providing a drop-down list of what's available. For any library bar, type bar. and press Tab to show the functions available in it.
For example, to view the tools available in the Summarize Data library of the arcgis.features module, enter the following code and press Tab:
features.summarize_data.
The autocomplete tool shows a drop-down list of the tools available in the library.
Often, a command in a notebook has required or optional arguments—parameters that provide information to run a command. If a command's syntax ends with an empty set of parentheses (()), the command requires or can include optional arguments for you to add.
Enter arguments within the parentheses, separating multiple arguments with commas. To view the string of required and optional arguments for any function, replace its empty parentheses with a question mark and run the cell. This will show the function's docstring, which lists all arguments.
For example, all tools available through the notebook editor's Analysis pane require arguments. Adding a tool from this pane to a cell will insert the tool's ArcGIS API for Python syntax, ending in empty parentheses. If you try to run this syntax in a cell without providing one or more arguments, the cell will fail and provide an error message.
To run the Aggregate Points tool in the Summarize Data library, locate the tool in the Analysis pane and add it to a new cell, or type the tool syntax as follows:
features.summarize_data.aggregate_points()
To view the list of arguments for the tool, modify the syntax as follows and run the cell:
features.summarize_data.aggregate_points?
This opens the docstring reference window for the tool. This reference has buttons to expand or close the window in the upper right corner.
When you're working in a cell, keep the following in mind:
- For any function foo(), type foo? and press Enter to show the function's docstring, which describes the function.
- If you start a cell with !, the cell's contents run as a bash command in your notebook container.
Run a cell
When you run a cell, its code is run, and all operations within are performed. You can only run a whole cell, not a subsection of the cell or a specific line of code. Cells can consist of one or multiple lines of code.
To run a selected cell, click the Run button on the toolbar, or click Run > Run Selected Cell. You can also press Ctrl+Enter to run the cell the mouse pointer is in.
To manually stop a cell that is being run, click Interrupt the Kernel on the toolbar or Kernel > Interrupt Kernel in the menu. You can also click the square stop button on the toolbar.
To the left of each code cell is an In [ ] element. If the cell has not yet been run, or if a previously run cell has been cleared of its output, the bracket is empty. While the cell is being run, it contains an asterisk: In [*]. When a cell has completed running, its In [ ] bracket is populated with a number that indicates the order of cells that have been run. Because cells in a notebook can be run in any order and can be run multiple times, the In [ ] numbers in a notebook's cells may not be in sequential order.
Note:
Markdown cells maintain an In [ ] element until they are run, at which point the element disappears and the cell's content becomes rich text.
When a line of code in a cell you run produces an output, the output is displayed in the notebook underneath the cell. Next to the output is an Out [ ] element, which matches what's in the corresponding cell's In [ ] element.
Work with the kernel
When you launch a notebook, a kernel is launched with it. This kernel runs the code you run in the notebook. As you run cells in the notebook (populating their In [ ] elements), variables you have defined in cells you ran are stored in the kernel's memory.
To restart the notebook's kernel and clear in-memory variables, click Restart the Kernel on the toolbar or Kernel > Restart Kernel in the menu. To restart the kernel, clear in-memory variables, and run all cells in the notebook sequentially, click Restart the kernel and run all cells on the toolbar or Kernel > Restart Kernel and Run all Cells in the menu.
When you are finished actively using a notebook, click Kernel > Shut Down Kernel to shut down the notebook's kernel and clear all in-memory variables. The kernel stops running, but it does not erase the outputs of cells that have been run.
When a notebook has been left idle for an extended period of time, the kernel will shut down and clear all in-memory values automatically. This time period is 24 hours by default but can be specified by the site administrator to be shorter or longer.