ArcGIS Pro and Python - Session 1

This workshop introduces you to using Python code with spatial data in ArcGIS Pro. You will also learn how to run stand-alone Python scripts with spatial data outside ArcGIS Pro using third party Python editors, as well as best practices for writing simple, yet effective Python scripts that will automate your ArcGIS Pro workflows.

Learning Objectives

By the end of this workshop, you will be able to:

  • Understand how to use Python in ArcGIS Pro

  • Use Python to access and examine GIS data

    • Understand the geoprocessing workflow in ArcGIS Pro to write effective Python scripts

  • Use ArcGIS Pro Notebook to perform spatial analysis on GIS data

  • Use the ArcPy package with Python IDEs.

1. Getting started with ArcGIS Pro and Python: Finding SC Counties within the probable hit zone

In this exercise, your goal is to find the SC counties that are within the probable hit zone of a hurricane. You will first use traditional spatial analysis tools, and then will learn how to accomplish the same result using Python inside ArcGIS Pro.

To get started, open ArcGIS Pro.

In the window that appears, click create a new project using the Map template.

Type in your project name: SC_Counties_within_Hit_Zone.

Navigate to C:\Users\YourClemsonID\Documents.

In the top right corner of ArcGIS Pro, make sure to sign into ArcGIS Online with your Clemson ID and password.

If you are signed in, you should see your name on the top right corner of ArcGIS Pro window as shown in the figure below.

1.1 Adding and exploring data: Wind speed probability & SC counties

1.1.1 Adding wind speed probability

For this session, one of the datasets you will utilize is the wind speed probability provided by National Hurricane Center. A sample dataset for very recent hurricanes are available on ArcGIS Online.

To add the historical hurricanes tracks to your map, these are the steps to take:

1. Open the Catalog Pane. In the top menu, select Portal.

2. In the menu bar below Portal, select the ArcGIS Online button.

3. Use the search bar, and type 2021100118_wsp64knt120hr_5km.

4. Find the layer with the same name in the search results. Right-click the layer and select Add to Current Map.

If you need detailed information about a layer, you can hover the mouse on the layer in Catalog Pane. A message box will appear showing a link to where you can learn more about the layer, its owner(s), and terms of use.

In order to find the SC counties that are within the probable hit zone of the hurricane, you will need the spatial data of South Carolina counties.

1.1.2 Adding South Carolina counties

Follow steps 1 and 2 from the above to search USA Counties in the Living Atlas. In the results list, find USA Counties, then right click the layer and add it to your current map.

Now you have two GIS datasets, one containing wind speed probability and the other containing the spatial data for the SC counties.

1.2 Running Spatial Tools: Finding SC counties within the probable hit zone

In this section, I will walk you through the conventional approach in running spatial analysis tools. Sections 1.3 and 1.4 will show how to learn about the corresponding Python command that essentially performs the same analysis and outputs the same results as you analyzed without Python.

First you will create a layer containing SC counties from the USA_Counties data.

Go to the Map tab.

Click on Select by Attributes.

The Input Rows are USA_Counties.

Click on New Expression.

Set Where to State Name.

Set the middle parameter to is equal.

Select South Carolina in the drop-down list.

Click Ok.

Go to Analysis tab.

Use the search field and type in Copy Feature.

Find and click the Copy Feature tool.

In the geoprocessing window, set the input feature as USA_Counties.

Name the output feature class to SC_Counties.

Hit Run.

In the Contents pane uncheck USA_Counties.

Using the SC_Counties and the hurricane data, you can find the counties within the hit zone of the hurricane. In this example, we use an arbitrary definition of the probable "hit zone" of a hurricane as the areas within 1200 miles of the hurricane forecast.

Spatial Join is one tool that you can use to create a new dataset with that indicates which counties are within the probable hit zone.

Go to the Analysis tab.

Select Tools to open the Geoprocessing window.

Use the search field and type in Spatial.

Find and click the Spatial Join tool.

In the Geoprocessing window for the spatial join tool,

The SC counties is your Target Feature.

The hurricane layer is the Join Feature.

For the Output Feature Class type in: SC_counties_in_hit_zone.

Make sure Join Operation is set to Join one to many.

Use the dropdown list for Match Option and select Within a distance.

Set search radius to 1100.

Make sure you selected Miles.

Click Run.

Once the analysis is complete, a new layer will be created and automatically added to your map.

1.3 Exploring the syntax of a geoprocessing tool

With the geoprocessing window open, if you click the help icon , it will take you to the ArcGIS help page for the spatial join tool where you can find the Python syntax of the spatial join tool. In the help page for the spatial join tool, scroll down to Parameters section,

Select the Python tab.

Find the Python command for the spatial join tool.

Check out the required and optional parameters in the table below the Python command.

2. Using the Python window inside ArcGIS Pro

The Python window in ArcGIS Pro is a quick and convenient way to write short Python code to run geoprocessing tools while taking advantage of the full functionality of Python without having to work in a separate application. When writing code in the Python window in ArcGIS Pro, there is no need to import ArcPy or check for licensing. Because you are running code from within the ArcGIS Pro application, the availability and licensing of ArcPy is implicit.

To open the Python window in ArcGIS Pro,

Click on the Analysis tab,

Find the Python button,

Click the small triangle,

Click Show Python Window.

A screenshot of the Python Window in ArcGIS Pro is shown below. In the Python window, the top section is called the “transcript,” and the bottom section is called the Python “prompt.”

You can type your line of code in the Python prompt. Once the code is typed, press Enter to execute the code.

2.1 Running the spatial join tool using the Python Window

The availability of Python functionality directly within ArcGIS Pro also provides an efficient mechanism for accessing and executing geoprocessing tasks. You can drag many elements from other panes in ArcGIS Pro, including tools from the Geoprocessing pane, one or more data layers from the Contents pane, and even tools you have already run from the History pane.

Now let's bring the spatial join tool that you have already run, directly into the Python window.

Click the Analysis tab.

On the left side, click the History button.

In the History pane, right click the spatial join tool.

Select Open in Python Window. Tip: You could also drag the tool into the prompt section of the Python window.

Rename the output feature class to SC_counties_in_hit_zone_pw.

Press Enter to run the spatial join tool from the Python window.

As you can see, the Python command for geoprocessing tools could be too lengthy to type. Dragging and dropping things directly into the Python window can greatly save on typing.

Congratulations! You successfully performed a spatial analysis using the Python window in ArcGIS Pro.

2.2 Saving your work in the Python window

The Python window is great for running relatively short sections of Python code. You can experiment with Python statements and get immediate results. The Python window, however, is not intended to create longer and more complex Python code. For this, you need Python scripts.

To save the code that you have already written in the Python window,

Right-click in the Python window.

Select Save Transcript.

Name your script, Find_vulnerable_counties.py

Note: The contents of the Python window can be saved as a Python file (.py) that you can then open in your preferred IDE.

2.3 Loading code into the Python window

You can copy code from a Python editor or text editor and paste it into the Python window. You can also use the Load Code option to import the complete contents of a script.

Consider the script that was previously exported (i.e. Find_vulnerable_counties.py). Starting off with an empty prompt section in the Python window, right-click and click Load Code. Then choose a Python script file, such as the Find_vulnerable_counties.py script.

When the script is loaded, all the lines are added to the prompt section, including any comments. You can preview all the lines of code and make any necessary changes before running the code.

When you run the code by pressing Enter, the code is executed and appears in the transcript, again including any comments.

3. Using ArcGIS Notebooks in ArcGIS Pro

Another way to use Python in ArcGIS Pro is through Python notebooks. With ArcGIS notebooks integrated into ArcGIS Pro, you can perform analysis and immediately view results in a geographic context, interact with the emerging data, document and automate your workflow, and save it for later use or share it. We are going to learn more about ArcGIS Notebooks later on this section.

3.1 Running the spatial join tool in ArcGIS Notebooks

Now let's run the spatial join tool that you have run in the previous sections, but this time using the Python notebook in ArcGIS Pro.

Go to Analysis tab.

Click the History button.

Right click the Spatial Join tool.

Select Copy Python command.

Paste the command you just copied into the ArcGIS notebook.

Rename the output feature class to SC_counties_in_hit_zone_nb.

Click the Run button to run the tool.

3.2 Exercise: Finding evacuation routes in South Carolina

In this section you will do an exercise on your own. You can choose either the Python window or ArcGIS notebook to perform this analysis. You will use what you have learned today to find evacuation routes in South Carolina.

Hint 1: Hurricane evacuation routes are available on living atlas as, Hurricane_Evacuation_Routes.

Hint 2: You can use the Clip tool for this exercise. The Intersect or Spatial Join tools are alternative tools for such analysis.

Note: For the Output Feature Class type in: Hurricane_Evacuation_Routes_SC.

Note: New ArcGIS notebooks are automatically added to your project. To add an existing notebook to the project, right-click the notebooks folder and choose Add Notebook .

Note: You cannot drag and drop things directly into the notebook. However, you can copy code snippets and paste into the notebook.

3.3 What is an ArcGIS Notebook?

Who has used Python within a Jupyter Notebook?

ArcGIS Notebooks within ArcGIS Pro are very similar to Python Jupyter Notebooks.

ArcGIS Notebooks are basically a self contained Python IDE (Integrated Development Environment) and interpreter.

ArcGIS Notebooks provide an environment, where you can document your code,

run it, look at the outcome, visualize data, and see the results without leaving the environment.

ArcGIS Notebooks incorporate spatial analysis functionality and visualizations in addition to what a normal Jupyter Notebook provides.

If you're not familiar with Jupyter Notebooks, that's okay. We'll go over basic Notebook functionality.

3.3.1 What are some of the ways that ArcGIS Notebooks can help you?

  • Useful when learning about spatial data science workflows.

    • Can help you understand spatial data processes.

    • There are lots of examples out there to look at and run on your own.

    • Notebook code is easily modified and manipulated to work with your own data.

  • Prototyping, Development, and Documenting is made much easier with ArcGIS Notebooks.

    • You can quickly create examples to show others.

    • Can run cells out of order and don't have to keep rerunning the entire Notebook for a section of code.

    • It's easy to add documentation in order to remind yourself and to help others understand the process.

  • Well suited for sharing and Collaboration.

    • A Notebook is just a single text file that can be easily zipped. This makes it easy to:

      • Distribute your notebooks for others to use.

      • Receive notebooks from others that you can utilize.

3.3.2 What are things for which ArcGIS Notebooks shouldn't be used

  • Automated scripts that run on a regular schedule.

  • Scripts that will not incorporate any type of user interaction or visualization.

  • Large scripts (over 500 lines of code? It's subjective)

    • Can be unwieldy to traverse all that code in a Notebook.

    • There are better IDEs that can be used to create large scripts:

      • Visual Studio Code

      • PyCharm

      • Sublime Text

3.4 ArcGIS Notebooks: A Dive In

3.4.1 Creating a new Notebook

  • Open ArcGIS Pro

  • Within ArcGIS Pro you can click on the "Insert" tab and then click on the "New Notebook" button.

  • A new Project object called "Notebooks" will appear in the Catalog Pane.

  • Click the drop down arrow besides "Notebooks" and your new Notebook should be listed.

    • Right click on the "New Notebook.ipynb" and select "Rename" to change the name of your Notebook.

    • This will also change the Notebook filename.

3.4.2 Other options for manipulating notebooks

  • The "Remove" option removes the notebook from your project. Doesn't delete it.

    • The "Add Notebook" allows you to add notebook files to your project.

    • Accidentally remove Notebook or want to add a Notebook to your project?

      • Under "Insert" tab click down arrow next to "New Notebook"

      • Select "Add Notebook"

      • In the Project Explore window which opens, navigate to the Notebook file and select it.

  • Adding a notebook does not copy the Notebook file to your project folder. It just points to that

  • Notebook file.

      • Any modifications will affect the original Notebook file.

    • To create a duplicate to play with, you can right click on the Notebook select "Copy" and

    • then "Paste" it in your project folder.

  • The "Delete" option removes and deletes the notebook file.

  • You're ready to play with an ArcGIS Notebooks.

3.4.2 Parts of an ArcGIS Notebook

  • A Notebook's contents are made up of cells.

  • Each cell is self contained and independent from any other cell.

  • To process a cell you Run that cell

  • Cells can be run in any order

  • Contents of a cell are made up of 3 cell types:

    • Markdown

      • Allows you to document your notebook with visual formatting

      • Can be HTML or Markdown syntax

    • Code

      • Python code that can accept input and process data to create information

      • Follows Python syntactical processing

    • Raw

      • Can be any type of text that doesn't have a specific format

  • Python code cells are global in scope which means they share their data with all the other cells.

    • This includes variables, functions, and objects.

  • Notebook Icon Bar:

  1. Insert Cell Below - Inserts a new cell below the currently selected cells

  2. Cut / Copy / Paste Selected Cells

  3. Move selected cells up / down - Allows you to reposition selected cells within the Notebook.

  4. Run selected cells

  5. Specify cell type for selected cells.

  6. Increase / Decrease cell font size.

Practice with me

    • Download NotebookExamine.zip

    • Extract folder someplace where it will be easy to find.

    • Open ArcGIS Pro.

    • Within the Open Menu choose "Open another project".

    • Navigate into the newly extracted "Notebook Examine" folder.

    • Select the NotebookExamine.aprx file and click "OK"

    • A Notebook should be open within the main window with ArcGIS Pro.

    • Four cells should be shown within your notebook.

    • If not already selected, click on first cell to select it.

      • Click the "Run" button in the icon bar above to run the selected cell.

      • You can also run the cell by holding the "Shift" key and pressing the "Enter" key.

    • What are the results?

    • By default each newly created cell is specified to be a Python code cell.

    • The first cell is supposed to be of cell type Markdown.

    • Select the first cell again.

    • In the icon bar, click the drop down arrow within the text box that shows the word: "Code"

    • Select "Markdown"

    • Run the first cell again

    • We can change the type of each cell by using this drop down box.

      • The fourth Cell is supposed to be markdown using markdown syntax

    • Here is a Markdown Cheat Sheet

    • Select the fourth cell by clicking on it and then run the cell

    • What are the results?

Because the "#" sign is a valid syntactical character in Python (comment symbol) no syntax error is generated when the cell is run.

    • Change the cell type to "Markdown" using the drop down box

    • Select and run the fourth cell.

    • Notice that after the fourth cell is run a new cell is created below.

    • Select and run the second cell

    • What are the results

    • Select and run the third cell

    • Select and run the second cell.

      • All the cells in a Notebook are globally scoped which means they have access to objects, functions, and variables within each cell.

      • Be mindful that this can cause hard to find bugs if variables with the same name in different cells are changed unintentionally.

3.4.3 Some other helpful tidbits about ArcGIS Notebooks

  • Selecting outside the cells content box allows you to select the whole cell.

  • Holding the "Shift" key while selecting a cell will allow you to select multiple cells.

  • Explore and play with the ArcGIS Notebook to become more familiar with all the features available.

    • There are many shortcut keys that help with coding efficiency.

      • One of my favorites is "<Ctrl> + </>". Allows you to toggle selected lines of code as commented or un-commented.

      • For more shortcuts click on the Keyboard Shortcuts menu item under the "Help" menu bar within the Notebook.

3.4.4 Getting help in ArcGIS Notebooks

Python tools, modules, functions, classes, and keywords all store documentation that provides information on their use.

You can activate documentations at the pointer by pressing Shift+Tab. The figure shows the documentations displayed for the spatial join tool.

Alternatively, the same documentation can be accessed using the built-in Python help function. The figure shows the help documentation displayed for arcpy.analysis.SpatialJoin.

.