Open Python for Geospatial Professionals

Preface

This web text can be viewed in a light mode or a dark mode. A toggle is provided in the sidebar.

Goals of Text

Open Python for Geospatial Professionals introduces the Python language to those interested in using it for data processing, analysis, and visualization tasks generally and tasks involving spatial data more specifically. It covers the base Python language along with core data science libraries, including NumPy and Xarray for working with data arrays; Pandas and Polars for working with tabulated data; matplotlib and Seaborn for data visualization; SciPy and Statsmodels for statistical inference; GeoPandas and Rasterio for mapping and working with vector and raster geospatial data; pystac-client for downloading remotely sensed data; libpysal and esda for spatial statistics; and scikit-learn and InterpretML for machine learning. This book has a follow-up, companion text titled Geospatial Deep Learning with Python and PyTorch. This text does not cover deep learning topics.

Use of AI Tools

Portions of this text were developed with the assistance of Claude, an AI model developed by Anthropic, used through the Claude Code tool in 2026. Claude drafted the initial versions of several sections, including the sections on Xarray and Polars, the chapters on statistical inference, making maps, vector geoprocessing, raster processing, downloading remotely sensed data, using WhiteboxTools, spatial statistics, accuracy assessment, linear regression, and random forest (adapted from the corresponding chapters of the author’s R text), the chapter on running Python scripts from the command line, and the material on setting up the Python environment and using Python in RStudio with reticulate. It also reviewed the chapters for typographical, grammatical, and coding errors; updated code for current package versions; and assisted with restyling and reorganizing the text. All AI-generated content was reviewed, tested, revised, and approved by the author, who designed the scope and structure of the text, selected the datasets and methods, executed and verified all code, and takes full responsibility for the content, including any errors. Claude is not an author of this work.

Error Statement

We have tried our best to provide accurate and complete information. Any errors are unintentional. The code has been tested using the package versions listed in the provided environment.yml file. Python packages change over time, so you may encounter warnings or errors if you use different package versions than those used to build this text. If you would like to comment on any material in this text, please feel free to contact the author, Aaron Maxwell, at Aaron.Maxwell@mail.wvu.edu.

Audience

This text was written for two audiences.

Geospatial professionals interested in developing or further developing their data analysis skills and learning to work in the Python environment.
General data scientists and analysts needing to learn more about working with data, including geospatial data, in Python.

The material covered in this text may be appropriate for an advanced undergraduate course or a graduate-level course. Since the focus is code implementation and practical considerations, a more theoretical companion text may be necessary.

Structure of Text

This text consists of 17 chapters organized into three parts: Basic Python, Working with Geospatial Data in Python, and Geospatial Machine Learning. Each chapter consists of examples with associated code and explanations. The covered topics are listed at the beginning of each chapter in the Topics Covered section. Each chapter ends with a set of review questions, and some chapters also include exercises. The data to complete the examples and exercises have been provided, which is described below.

Basic Python introduces the Python language and the core libraries used for data science in Python. 1 The Basics covers the basics of the language, including variables, data types, and data models, while 2 Python Language Deeper Dive further explores the language and discusses functions, control flow, loops, list comprehension, classes, modules, and working with files. 3 NumPy and Xarray explores NumPy and Xarray, which are central to scientific computing in Python and working with data arrays, while 4 Pandas and Polars covers working with tabulated data using Pandas and Polars. 5 Visualize Data with matplotlib, Seaborn, and Pandas explores data visualization using matplotlib, Seaborn, and Pandas. 6 Statistical Inference explores statistical inference, including confidence intervals, hypothesis tests, and statistical power, using SciPy and Statsmodels, along with simulation-based methods. 7 Running Python Scripts from the Command Line discusses running code at the command line, organizing and documenting a script file, and accepting user-provided arguments using argparse.

Working with Geospatial Data in Python applies these skills to geospatial data. 8 Making Maps explores making static and interactive maps using GeoPandas, matplotlib, contextily, and mapclassify. 9 Vector Geoprocessing with GeoPandas covers vector geoprocessing with GeoPandas, including table and spatial joins, overlay, buffering, and summarizing features relative to polygons, while 10 Raster Processing with Rasterio covers raster processing with Rasterio, NumPy, and SciPy, including cropping, masking, re-projecting, reclassifying, summarizing, and rasterizing data and deriving band ratios, principal components, and land surface parameters from imagery and digital terrain models. 11 Downloading Remotely Sensed Data demonstrates searching for and downloading Sentinel-2, Landsat 9, Sentinel-1, and 3DEP data using the SpatioTemporal Asset Catalog (STAC) specification and pystac-client. 12 Using WhiteboxTools in Python introduces accessing external geospatial software from Python and uses the whitebox library to run WhiteboxTools for terrain analysis, vector geoprocessing, and lidar processing. 13 Spatial Statistics explores point pattern analysis, spatial autocorrelation, semivariograms, and hot spot analysis using libpysal and esda.

Geospatial Machine Learning focuses on supervised learning. 14 Accuracy Assessment introduces the metrics used to assess regression and classification models, including the confusion matrix, overall accuracy, precision, recall, F1-score, and ROC and precision-recall curves, using scikit-learn. 15 Linear Regression uses Statsmodels and scikit-learn to fit, interpret, diagnose, and regularize linear regression models for predicting burn severity from WorldView-3 imagery and applies a model to raster data. 16 Random Forest uses the random forest algorithm implemented in scikit-learn to train, assess, and compare models for predicting wetland occurrence from topographic variables, compares random forest to logistic regression and to a support vector machine with hyperparameters tuned using cross validation, and generates a spatial prediction of wetland probability, while 17 Interpretable Machine Learning with Explainable Boosting Machine introduces interpretable machine learning using the explainable boosting machine (EBM) method implemented in InterpretML.

Data and Source Files

This book was written using Quarto. To learn more about Quarto, we recommend Quarto for Scientists by Nicholas Tierney, which was also written using Quarto and has been made available free-of-charge.

All of the data needed to execute the code in the chapters and complete the exercises have been provided. All of the Quarto (.qmd) files that constitute this book, along with the data, can be downloaded as a single compressed archive using the download option in the sidebar or using this link: pyBookFiles.zip. You will need to uncompress the archive before use. The uncompressed pyBook folder contains:

The Quarto files for each chapter (e.g., 03_numpy.qmd) and the project files needed to render the book (_quarto.yml, _setup.qmd, and the style files)
The exercises folder, which contains the exercise files that are included at the end of the chapters
The datasets folder, which contains all of the data used in the chapters and exercises; the geospatial data are stored in the datasets/gisData subfolder, which contains a separate folder for each geospatial chapter (e.g., mapping, vector, raster, whitebox, spatial_stats, accuracy, regression, and spatial_ml)
The scripts folder, which contains the example Python scripts that are run from the command line in 7 Running Python Scripts from the Command Line
An initially empty output folder, to which files generated by the code are written
The environment.yml file, which is used to create the pybook Python environment, as described below

If you open a Quarto file from the uncompressed pyBook folder, the relative file paths used in the code (e.g., datasets/matts_movies.csv) should work so that the paths do not need to be updated. If you copy the code into your own scripts or notebooks, make sure the working directory is set to the pyBook folder or update the paths accordingly.

Setting Up Python

Why Use Conda?

Python itself is only the starting point. Almost all data science and geospatial work in Python relies on additional packages, such as NumPy, Pandas, and scikit-learn, and many of these packages depend on specific versions of each other and on compiled, non-Python libraries (for example, the linear algebra libraries used by NumPy or the GDAL library used by many geospatial packages). Installing everything into a single, system-wide copy of Python quickly becomes difficult to manage.

For this reason, we recommend using conda to install Python and manage packages. Conda allows you to create environments, which are isolated installations of Python and a specific set of packages. You can have several environments on the same computer, each with different packages and package versions, without them interfering with each other. All of the code in this book runs in a conda environment called pybook.

Install Python with Miniconda

Miniconda is a minimal installer that provides conda, Python, and a small number of supporting packages. It is a good choice since you will install the other packages you need into a separate environment. You do not need to install Python separately from python.org; Miniconda includes it.

Download the Miniconda installer for your operating system (Windows, macOS, or Linux) from the Miniconda download page.
Run the installer and accept the default options. On Windows, it is generally best to install Miniconda for “Just Me” and not add it to your system PATH. You will instead use the Anaconda Prompt that the installer adds to the Start Menu.
Open a terminal (on Windows, the Anaconda Prompt; on macOS or Linux, the standard Terminal) and confirm that conda is available:
```
conda --version
```
We recommend configuring conda to use the community-maintained conda-forge channel by default since it provides up-to-date builds of nearly all of the scientific and geospatial packages used in this text:
```
conda config --add channels conda-forge
conda config --set channel_priority strict
```

Create the pybook Environment

The environment.yml file, included in the book download, lists the packages and versions the code was tested with. Using this file is the easiest way to recreate the environment used to build this text.

Open a terminal (on Windows, the Anaconda Prompt) and navigate to the uncompressed pyBook folder, which contains environment.yml, using the cd command. For example:
```
cd C:/Users/yourname/pyBook
```
Create the environment from the file:
```
conda env create -f environment.yml
```
Conda will resolve, download, and install all of the listed packages and their dependencies. This may take several minutes.

If you would prefer to build the environment yourself as opposed to using the provided file, you can create an environment and list the required packages directly. Without version numbers, conda will install the most recent compatible versions, which may differ from those used to build this text.

conda create -n pybook -c conda-forge python=3.11 numpy pandas xarray polars pyarrow rasterio geopandas contextily matplotlib seaborn scipy statsmodels scikit-learn opencv interpret plotly jupyterlab ipykernel

Install the Environment into a Project Directory

By default, conda stores environments in a central location (for example, C:/Users/yourname/miniconda3/envs/pybook). As an alternative, you can install the provided environment into a folder within the book’s project directory using the --prefix (or -p) argument. This keeps the environment alongside the code and data that use it and makes it clear which environment belongs to which project.

From the pyBook folder, run:

conda env create -f environment.yml --prefix ./envs/pybook

An environment created this way does not have a name. Instead, it is referenced by its path. So, it must be activated using the path as opposed to a name:

conda activate ./envs/pybook

A few notes about this option:

The environment folder can be large (often more than 1 GB) and contains many thousands of files. If the project directory is synced with a cloud service, such as Dropbox, OneDrive, or Google Drive, or tracked with Git, we recommend excluding the envs folder from syncing and adding it to your .gitignore file.
By default, conda will show the full path of the environment in your terminal prompt. You can shorten this by running conda config --set env_prompt '({name}) '.
Throughout the rest of the text, we refer to the environment by its name, pybook. If you installed it into the project directory, use the path (for example, ./envs/pybook) wherever the name is used.

Activate the Environment

Before working through the book, you must activate the environment so that your terminal, editor, or notebook uses its copy of Python and its packages:

conda activate pybook

The name of the active environment will appear in parentheses at the start of your terminal prompt. To confirm that the required packages are available, run:

python -c "import numpy, pandas, xarray, polars, rasterio, geopandas, sklearn; print('pybook is ready')"

You can then run the examples in JupyterLab (jupyter lab), VS Code, or any other editor that uses this environment. In VS Code, select the pybook interpreter using the Python: Select Interpreter command. To make the environment available as a kernel in an existing installation of Jupyter, run:

python -m ipykernel install --user --name pybook --display-name "Python (pybook)"

When you are finished, you can deactivate the environment with conda deactivate.

Update or Remove the Environment

If you already created the environment and environment.yml changes, update the environment with:

conda env update -f environment.yml --prune

The --prune argument removes any packages that are no longer listed in the file. If you need to start over, you can delete the environment and then recreate it:

conda env remove -n pybook

Using Python in RStudio with reticulate

If you are already an R user, you may prefer to work in RStudio by Posit, which is freely available. The reticulate R package allows you to run Python code from R, R Markdown, and Quarto documents and to pass data between the two languages. In fact, this book was written in RStudio, and the Python code in each chapter was executed using reticulate.

Install reticulate and Connect to pybook

First, install reticulate from CRAN within R:

install.packages("reticulate")

Next, tell reticulate which Python environment to use. This must be done before any Python code is run in the R session since reticulate cannot switch to a different Python installation once one has been loaded. If you need to change environments, restart R first (Session → Restart R).

library(reticulate)

# Use an environment stored in conda's default location
use_condaenv("pybook", required = TRUE)

# Or, use an environment installed into the project directory
use_condaenv("C:/Users/yourname/pyBook/envs/pybook", required = TRUE)

You can confirm which version of Python and which environment reticulate is using with:

py_config()

There are two other common ways to set the environment so that you do not need to call use_condaenv() in every script:

In RStudio, go to Tools → Global Options → Python (or Tools → Project Options → Python for a single project), click Select…, and choose the pybook environment under the Conda Environments tab.
Set the RETICULATE_PYTHON environment variable to the Python executable in the environment by adding a line to an .Renviron file in your project folder. On Windows, the executable is python.exe in the top level of the environment folder; on macOS and Linux, it is bin/python:

RETICULATE_PYTHON="C:/Users/yourname/miniconda3/envs/pybook/python.exe"

Running Python Code from R

Once reticulate is connected to pybook, there are several ways to run Python code:

Quarto or R Markdown documents: add Python code chunks (```{python}) to your document. When the document is rendered with the knitr engine, reticulate executes the Python chunks. All Python chunks in a document share the same Python session, so variables defined in one chunk are available in later chunks.
Python scripts: create a new Python script in RStudio (File → New File → Python Script) and run lines or selections with Ctrl+Enter (Cmd+Enter on macOS). RStudio will start an interactive Python session in the console using reticulate.
Interactive console: run reticulate::repl_python() in the R console to start a Python prompt. Type exit to return to R.
Source a script: run an entire Python script with reticulate::source_python("my_script.py").

A useful feature of reticulate is the ability to pass objects between R and Python. Within Python, R objects are accessed using the r object. Within R, Python objects are accessed using the py object. Common data types are converted automatically; for example, R data frames are converted to Pandas DataFrames, and NumPy arrays are converted to R matrices or arrays.

# In an R chunk: create a data frame
elev <- data.frame(site = c("A", "B", "C"), elev_m = c(312, 455, 980))

# In a Python chunk: access the R data frame as a Pandas DataFrame
elev_py = r.elev
elev_py["elev_ft"] = elev_py["elev_m"] * 3.28084

# Back in an R chunk: access the Python result
py$elev_py

You can also import Python modules and call them using R syntax:

np <- import("numpy")
np$mean(c(1, 2, 3, 4))

In this book, every chapter begins by connecting reticulate to the pybook environment in a hidden code chunk stored in _setup.qmd. If you render the book yourself and installed the environment into the project directory, edit _setup.qmd to provide the environment path as opposed to its name.

Thanks

This online text was partially funded by AmericaView. AmericaView is a nationwide, university-based, and state-implemented network that advances Earth observation education through remote sensing science, applied research, workforce development, technology transfer, and community outreach. AmericaView is supported by the United States Geological Survey (USGS) under Grant/Cooperative Agreement No. G23AP00683. The views and conclusions contained in this text are those of the authors and should not be interpreted as representing the opinions or policies of the U.S. Geological Survey. Mention of trade names or commercial products does not constitute their endorsement by the U.S. Geological Survey.

Partial funding was also provided by the National Science Foundation (NSF) (Federal Award ID No. 2046059: “CAREER: Mapping Anthropocene Geomorphology with Deep Learning, Big Data Spatial Analytics, and LiDAR”). Any opinions, ﬁndings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reﬂect the views of the National Science Foundation.

Nomenclature

We use the following type standards throughout the text:

Bold text is used to highlight key or important terms at first use in each chapter (e.g., DataFrame).
Underlined text is used for Python library, package, or module names (e.g., NumPy).
Italic text is used for file names, folder paths/directories, and book or journal titles (e.g., matts_movies.csv).
Table or DataFrame column names are written in “quotes” and italicized (e.g., “Genre”).
“Quotes” are placed around names of journal articles.
In-text code snippets, function and method names, and variable names are written as fixed-width text (e.g., np.mean()).
Callout blocks are used to highlight key information, offer practical advice, or relate concepts across chapters.

This is an example callout block.

Concluding Remarks

We hope you are excited to start learning to use Python to work with and analyze data. In the next chapter, we begin by exploring the basics of the Python language.

Appendix: Package List

Table 1 lists the key libraries used in this text with a brief description of their use and links to their documentation.

Table 1. Key Python libraries used in this text.

Use	Library	Description	Link
Arrays	NumPy	Create and work with multidimensional arrays	site
Arrays	Xarray	Labeled, multidimensional arrays and datasets	site
Tabulated data	Pandas	Read, query, manipulate, and summarize data tables	site
Tabulated data	Polars	Fast DataFrame library with lazy evaluation	site
Tabulated data	pyarrow	Apache Arrow memory format; converts between Pandas and Polars	site
Visualization	matplotlib	Build and refine graphs and plot images	site
Visualization	Seaborn	Statistical graphics built on matplotlib	site
Visualization	plotly	Interactive graphics (used by InterpretML)	site
Images	OpenCV	Read and process images	site
Statistics	SciPy	Scientific computing and statistical tests	site
Statistics	Statsmodels	Statistical models and tests	site
Geospatial	Rasterio	Read, write, and analyze raster data	site
Geospatial	GeoPandas	Read, write, map, and analyze vector data	site
Geospatial	contextily	Add web map tiles as basemaps	site
Geospatial	mapclassify	Classify data for choropleth maps; color neighboring polygons	site
Geospatial	matplotlib-scalebar	Add scale bars to maps	site
Geospatial	folium	Interactive web maps (used by the GeoPandas `explore()` method)	site
Geospatial	pystac-client	Search SpatioTemporal Asset Catalog (STAC) APIs	site
Geospatial	planetary-computer	Sign Microsoft Planetary Computer asset URLs	site
Geospatial	whitebox	Python interface to WhiteboxTools for terrain, vector, and lidar processing	site
Spatial statistics	libpysal	Spatial weights	site
Spatial statistics	esda	Spatial autocorrelation and hot spot statistics	site
Machine learning	scikit-learn	Data preprocessing, machine learning, and model assessment	site
Machine learning	InterpretML	Interpretable machine learning and explainable boosting machines	site