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 your 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 executed 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 NBConvert—The notebook will not process content in a Raw NBConvert cell. This cell type is rarely used.
Note:
The Heading cell type is also available in the drop-down list. However, this cell type is no longer used in Jupyter notebook environments. Clicking this cell type will turn the cell into a Markdown cell and append an number sign (#), which denotes a top-level heading in Markdown.
The use of rich text and code comments will make your notebooks more readable and valuable to users with whom they are shared.
Work with cells
For a notebook to execute 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 new cell by pressing Shift+Enter, or by clicking Insert on the menu ribbon, which gives you the option to insert a new cell above or below your current cell.
Cell toolbar options
You can include additional information about individual cells in a notebook using the options in the cell toolbar:
- None—Do not show cell toolbars.
- Edit Metadata—Enter metadata for each cell using JSON.
- Raw Cell Format—Raw cells allow you to write output directly; the content of these cells is not evaluated by the notebook.
- Slideshow—Specify how each cell will display in a slide show. Helpful when presenting code.
- Attachments—Manage the associated attachments within each cell in the notebook workspace.
- Tags—Create and manage tags for each cell within the notebook workspace.
When any of these options are on, a bar appears above each cell in the notebook. Only one option can be on at a time, but any information you add to the toolbar remains even when switched off. You can change the cell toolbar options by clicking View > Cell Toolbar.
The Tags option can be used when you are preparing a notebook to be scheduled or remotely executed. This provides the option to insert parameters as a new cell at execution time, such as account credentials or variables to define. You can designate the place in the notebook where this new cell is added by adding the tag parameters to a cell in your notebook. The new cell is inserted after this cell. Only one cell with the parameters tag is recognized by the operation.
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 your notebook's runtime. To access these libraries, run an import command.
See all Python libraries available in ArcGIS Notebooks
Create a new 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.mapping import WebSceneArcGIS 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 navigate 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 your 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 execute and what content they will execute 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 execute 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.
If you want 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 executed, 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 Cells > Run Cells. You can also press Ctrl+Enter to run the cell your mouse pointer is in.
To manually stop a cell that is being run, click Kernel > Interrupt. You can also click the square stop button in 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 your notebook underneath the executed 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 new notebook, a kernel is launched with it. This kernel executes the code you run in the notebook. As you run cells in the notebook (populating their In [ ] elements), variables you have defined in executed cells are stored in the kernel's memory.
To restart your notebook's kernel and clear in-memory variables, click Kernel > Restart. If you want to restart the kernel, clear in-memory variables, and run all cells in the notebook sequentially, click Kernel > Restart & Run All.
When you are done actively using a notebook, click Kernel > Shutdown 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 your site administrator to be shorter or longer.