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.

F_plot_map is the primary visualisation utility in the ARSET PM2.5 workflow. It can render gridded satellite or model data (passed as an xarray object), point observations from ground monitors (passed as a pandas DataFrame), or both simultaneously on a single geographic map. The function wraps cartopy and matplotlib to draw coastlines, lakes, political borders, state boundaries, and latitude/longitude gridlines automatically, so you can produce publication-ready maps with a single call. Use F_plot_map after loading data with F_subset_and_combine or F_get_OpenAQ_from_API to inspect spatial patterns, identify outliers, or overlay satellite estimates on top of ground-monitor observations. Multiple calls sharing the same o_figure, o_axis, and o_plot objects can build up layered maps incrementally.

​
Parameters

​
a_data_plot
xarray.DataArray | None
default:"None"
Gridded data to render as a filled colour mesh (pcolormesh). Typically one time-slice of the xarray.Dataset returned by F_subset_and_combine, e.g. a_data['SatPM'].sel(time='2023-06'). Pass None to skip the gridded layer.
​
a_data_plot_point
pandas.DataFrame | None
default:"None"
Point data to render as coloured scatter markers. The DataFrame must have a MultiIndex whose first two levels are lat and lon. Typically the output of F_get_OpenAQ_from_API or F_get_SINCA_from_web, aggregated to a single value per location. Pass None to skip the point layer.
​
n_lat_min
float
default:"-90"
Southern boundary of the map extent, in decimal degrees.
​
n_lat_max
float
default:"90"
Northern boundary of the map extent, in decimal degrees.
​
n_lon_min
float
default:"-180"
Western boundary of the map extent, in decimal degrees.
​
n_lon_max
float
default:"180"
Eastern boundary of the map extent, in decimal degrees.
​
my_cmap
matplotlib.colors.Colormap
default:"plt.get_cmap('Oranges')"
Matplotlib colormap used for both the gridded mesh and the scatter markers. Any named Matplotlib colormap is accepted:
import matplotlib.pyplot as plt

# Sequential (recommended for concentrations)
my_cmap = plt.get_cmap('YlOrRd')

# Diverging (recommended for bias maps)
my_cmap = plt.get_cmap('RdBu_r')
​
Colorbar_Label
str | None
default:"None"
Label text placed beside the colour bar. Typically the variable name and units, e.g. 'PM₂.₅ (µg/m³)'.
​
Plot_Title
str | None
default:"None"
Title string displayed above the map axes.
​
Colorbar_Limits
list[float]
default:"[0, 1]"
Two-element list [vmin, vmax] controlling the range of the colour scale. Data values below vmin or above vmax are clipped to the colour bar extremes. For PM2.5 in µg/m³, typical values are [0, 50] for annual mean maps and [0, 150] for daily or event maps.
​
n_pointsize
int | float
default:"20"
Marker size (in Matplotlib s units, i.e., points²) for the scatter plot drawn from a_data_plot_point. Increase for sparse monitor networks; decrease for dense urban networks where markers overlap.
​
n_latlon_gridspacing
float
default:"1"
Angular spacing (in degrees) between the latitude and longitude gridlines drawn on the map. Use 0.5 for city-scale maps and 5 or 10 for continental or global views.
​
o_figure
matplotlib.figure.Figure | None
default:"None"
An existing Matplotlib Figure object to draw into. If None, a new figure is created internally. Pass the object returned by a previous call to build multi-panel figures.
​
o_axis
cartopy.mpl.geoaxes.GeoAxes | None
default:"None"
An existing Cartopy GeoAxes object to draw into. If None, a new axis is created. Must be paired with a matching o_figure.
​
o_plot
matplotlib.artist.Artist | None
default:"None"
The plot artist returned by a previous call, used for consistent colour scale when layering multiple calls. Pass None on the first call.
​
SHOW
bool
default:"True"
If True, plt.show() is called at the end of the function, rendering the figure inline in a Jupyter notebook. Set to False when combining multiple layers or saving to file programmatically.
​
b_shapefiles
bool
default:"True"
If True, the following Natural Earth features are overlaid on the map using cartopy.feature: coastlines, lakes, country borders, and state/province boundaries. Set to False for a plain data-only plot or when working offline without the Natural Earth data files.

​
Return Values

​
o_figure
matplotlib.figure.Figure
The Matplotlib Figure object used for the plot. Pass back into subsequent calls to overlay additional layers on the same canvas.
​
o_axis
cartopy.mpl.geoaxes.GeoAxes
The Cartopy GeoAxes object used for the plot. Pass back into subsequent calls to reuse the same map projection and extent.
​
o_plot
matplotlib.artist.Artist
The plot artist (e.g., QuadMesh for gridded data or PathCollection for scatter). Useful for constructing a shared colour bar when layering plots.

​
Usage Examples

​
Plot gridded satellite PM2.5

import matplotlib.pyplot as plt

# Select a single monthly mean slice from the SatPM dataset
a_data_SatPM_slice = a_data_SatPM['PM25_filtered'].sel(time='2023-06', method='nearest')

fig, ax, pc = F_plot_map(
    a_data_plot      = a_data_SatPM_slice,
    n_lat_min        = -39.0,
    n_lat_max        = -36.0,
    n_lon_min        = -74.0,
    n_lon_max        = -71.0,
    Colorbar_Label   = 'PM₂.₅ (µg/m³)',
    Plot_Title       = 'SatPM2.5 — Biobío, June 2023',
    Colorbar_Limits  = [0, 40],
    n_latlon_gridspacing = 0.5,
    SHOW             = True,
)

​
Overlay ground monitor observations on gridded data

# First layer: gridded satellite data (suppress show)
fig, ax, pc = F_plot_map(
    a_data_plot      = a_data_SatPM['PM25_filtered'],
    n_lat_min        = -39.0,
    n_lat_max        = -36.0,
    n_lon_min        = -74.0,
    n_lon_max        = -71.0,
    Colorbar_Label   = 'PM₂.₅ (µg/m³)',
    Colorbar_Limits  = [0, 50],
    SHOW             = False,
)

# Second layer: overlay ground monitor points on the same figure/axis
fig, ax, pc = F_plot_map(
    a_data_plot_point  = f_data_monitors['PM25_filtered'],
    n_lat_min          = -39.0,
    n_lat_max          = -36.0,
    n_lon_min          = -74.0,
    n_lon_max          = -71.0,
    Colorbar_Limits    = [0, 50],
    n_pointsize        = 60,
    o_figure           = fig,
    o_axis             = ax,
    o_plot             = pc,
    Plot_Title         = 'Satellite vs. Monitors — Biobío, June 2023',
    SHOW               = True,
)

​
Save to file without displaying

fig, ax, pc = F_plot_map(
    a_data_plot     = a_data_SatPM['PM25_filtered'],
    Colorbar_Limits = [0, 50],
    SHOW            = False,
)
fig.savefig('biobio_pm25_june2023.png', dpi=150, bbox_inches='tight')
Both a_data_plot and a_data_plot_point can be passed together to render gridded and point data simultaneously in a single call. The same colour scale (Colorbar_Limits and my_cmap) is applied to both layers, so make sure the data ranges are comparable.
When building multi-layer figures by making successive calls, always set SHOW=False on all but the final call and pass o_figure, o_axis, and o_plot from one call to the next. Calling plt.show() mid-sequence will flush the figure buffer and subsequent layers will appear on a new blank canvas.
b_shapefiles=True (the default) requires the cartopy package and its Natural Earth data to be installed. In restricted compute environments without internet access, pre-download the Natural Earth shapefiles or set b_shapefiles=False to skip coastline, lake, border, and state boundary rendering.

Build docs developers (and LLMs) love

Get started for freeTalk to us