Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/NASAARSET/PM2.5_AQ_Online_2026/llms.txt

Use this file to discover all available pages before exploring further.

The fastest path to running these notebooks is Google Colab — no local Python installation required. All you need is a Google account, a NASA Earthdata login, and an OpenAQ API key. This guide walks you through opening the Case Study (English) notebook, completing the setup cell, and producing your first satellite PM2.5 map of south-central Chile.

​
Prerequisites

Before opening any notebook, make sure you have the following accounts set up. Both are free.

NASA Earthdata Account

Required to authenticate with earthaccess.login() and download MERRA-2 CNN data. Register at urs.earthdata.nasa.gov — approval is instant.

OpenAQ API Key

Required to query the OpenAQ v3 API for ground-based PM2.5 monitor data. Obtain a free key at docs.openaq.org/using-the-api/api-key.
You also need a Google account for Google Colab and Google Drive. If you already use Gmail, you’re set.

​
Step-by-Step: Running the Case Study Notebook

1

Open the notebook in Google Colab

Click the badge below to open the Case Study (English) exercise notebook directly in Google Colab. The notebook will open in your browser without signing in to GitHub.Open In Colab
Do not run cells directly from GitHub’s read-only view. Colab runs your own copy in the cloud — nothing you do affects the original repository.
2

Save a copy to your Google Drive

In Colab, select File → Save a copy in Drive. Colab will open a new tab with your personal copy.The notebooks suggest placing your copy at a path like:
/content/drive/MyDrive/Colab Notebooks/ARSET/PM25_Training_2026/
You can use any path you prefer, but keeping it organized will make it easier to manage the data folders created in the next steps.
3

Create data folders in Google Drive

Before running the setup cell, create two sub-folders inside your PM25_Training_2026 folder:
Folder namePurpose
SatPM_DataSatPM V6.GL.03 monthly NetCDF files
MERRA2_CNN_DataMERRA-2 CNN hourly NetCDF files
You can create these from drive.google.com or from within Colab using the file browser in the left sidebar.
4

Run the setup cell

The first code cell installs cartopy and earthaccess (which are not pre-installed in Colab), imports all other required packages, mounts your Google Drive, and prompts for credentials. Select the cell and press Shift+Enter (or click the ▶ button).
# Install & Import the required packages:
!pip install --quiet cartopy earthaccess

# basic packages:
import os
import getpass
from google.colab import drive
import warnings
warnings.filterwarnings('ignore')

# data analysis packages:
import numpy as np
import pandas as pd
import xarray as xr

# data access packages:
import earthaccess
import requests
import urllib
import re
import time
from urllib.parse import urljoin
from bs4 import BeautifulSoup

# plotting packages:
import matplotlib.pyplot as plt
import cartopy
import seaborn as sns

# Connect to Google Drive:
drive.mount('/content/drive')

# Store login information:
earthaccess.login()
s_key_openAQ = getpass.getpass('Enter OpenAQ API key:')
The pip install step takes roughly 60–90 seconds on a fresh Colab runtime. Subsequent runs on the same runtime are faster because packages are already installed.
5

Authenticate with NASA Earthdata

When earthaccess.login() runs, it will prompt you for your NASA Earthdata username and password interactively in the cell output. Type your credentials and press Enter. earthaccess stores the session token in memory for the duration of the runtime — you will not need to re-enter credentials while the runtime stays active.
6

Enter your OpenAQ API key

After Earthdata login completes, getpass.getpass('Enter OpenAQ API key:') will display a masked password prompt. Paste your OpenAQ key and press Enter. The key is stored in the variable s_key_openAQ and passed automatically to the F_get_OpenAQ_from_API function throughout the notebook.
7

Plot your first map

Scroll to the Define your domain of interest section. The Case Study notebook pre-fills the Chile bounding box for you:
# Define the bounding box:
n_lat_min = -38
n_lat_max = -32
n_lon_min = -73.75
n_lon_max = -69.75

# Define the start and end time:
t_start = np.datetime64('2022-12-01 00:00:00')
t_end   = np.datetime64('2023-03-31 23:59:59')

# Specify the local time zone:
s_timezome = 'America/Santiago'

# Preview the region:
F_plot_map(n_lat_min=n_lat_min,
           n_lat_max=n_lat_max,
           n_lon_min=n_lon_min,
           n_lon_max=n_lon_max);
Running this cell calls the built-in F_plot_map function and renders a cartopy map with coastlines, borders, and gridlines showing your selected region. This is a fast sanity check before any data is downloaded.

​
All Notebooks at a Glance

NotebookLanguageExerciseCompleted (with solutions)
Case StudyEnglishOpen In ColabOpen In Colab
Case StudyEspañolOpen In ColabOpen In Colab
The Case Study focuses on the Chile megafires of February 2023 (bounding box pre-filled). It includes a comparison between OpenAQ and the Chilean SINCA monitoring network to illustrate how data source selection affects analysis of extreme pollution events.

​
Exercise vs. Completed Notebooks

Exercise Notebooks

Contain ???? placeholders in code cells that participants fill in. These are the notebooks to use when following the training — filling in the blanks is part of the learning process. The Case Study exercise has the bounding box pre-filled; the Homework does not.

Completed Notebooks

Contain fully working code with all blanks filled in and representative output. Use these as a reference if you get stuck, or to verify your results. Completed versions are available for both the Case Study and the Homework (_Complete notebooks).
If your Colab runtime disconnects or times out, you will need to re-run the setup cell to re-install packages and re-authenticate. Downloaded data files saved to Google Drive are preserved — you can re-load them using the xr.open_dataset and pd.read_csv cells in the Analysis section without re-downloading from NASA servers.

​
Next Steps

Once you have your first map rendered, continue through the notebook to:
  1. Download SatPM data — monthly NetCDF files are fetched directly from the SatPM S3 bucket and cached to SatPM_Data/ in your Drive
  2. Download MERRA-2 CNN data — hourly files are searched and downloaded via earthaccess
  3. Retrieve monitor data — OpenAQ API returns ground-based PM2.5 hourly measurements for your bounding box
  4. Compare and evaluate — overlay maps, scatter plots, monthly time series, and computed metrics (bias, RMSE, R²)
For a deeper explanation of the folder structure, package roles, and credential setup, see the Environment Setup guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us