Mapping Explained

The PseudoNetCDF.plot function makes maps when plottype is longitude-latitude, which is the default (in new versions, the default is the last two dimensions; often COL-ROW, lon-lat, x-y). When plot triggers a map, it can be thought of in four parts:

  1. Get a map

  2. Draw features

  3. Add a pseudocolor (aka tile) feature from the variables

  4. Add a colorbar

To illustrate, how it works the three following code segments perform the same task using successively less code. In all three examples, the ACONC.nc file is an IOAPI output from CMAQ that contains the NO2 variable.

Mapping with pycno

This is the recommended method for creating a map for most air quality models, because it has the fewest dependencies. This example assumes a CMAQ or CAMx formatted NetCDF file. It requires matplotlib, pyproj, and pycno – all of which can be installed on most systems with the simple command pip install pyproj pseudonetcdf pycno.

import matplotlib.pyplot as plt
import matplotlib.colors as mc
import PseudoNetCDF as pnc
import pycno

path = 'ACONC.nc'
inputf = pnc.pncopen(path, format='uamiv')
# Create a Computer Network Overlay map drawing object
cno = pycno.cno(proj=inputf.getproj(withgrid=True))

# Get the variable to plot
plotvar = inputf.variables['NO2']
# take the first layer (0-based index), and then average time (the 0th dimension)
plotvals = plotvar[:, 0].mean(0)

# Create a tile plot
p = plt.pcolormesh(plotvals, norm=mc.LogNorm())
# Add the map
cno.draw()
# Add a colorbar
plt.colorbar(p, label=f'{plotvar.long_name.strip()} ({plotvar.units.strip()})')
# Save the figure
plt.savefig('example.png')

Mapping with Basemap

The first segment uses netCDF4 to open the file, numpy to construct coordinates, basemap to create a map, and matplotlib to do the plotting.

import matplotlib.pyplot as plt
import numpy as np
import matplotlib.colors as mc
from mpl_toolkits.basemap import Basemap
from netCDF4 import Dataset

path = 'ACONC.nc'
f = Dataset(path)
var = f.variables['NO2']

bmap = Basemap(
    projection='lcc',
    lon_0=f.P_GAM, lat_0=f.YCENT, lat_1=f.P_ALP, lat_2=f.P_BET,
    llcrnrx=f.XORIG, llcrnry=f.YORIG,
    urcrnrx=f.XORIG + f.NCOLS * f.XCELL,
    urcrnry=f.YORIG + f.NROWS * f.YCELL
)

x = np.arange(f.NCOLS + 1) * f.XCELL
y = np.arange(f.NROWS + 1) * f.YCELL

fig, ax = plt.subplots(1, 1)
bmap.drawcoastlines(ax=ax)
bmap.drawcountries(ax=ax)
lay1avgtime = var[:, 0].mean(0)

plt.pcolormesh(x, y, lay1avgtime, norm=mc.LogNorm())
plt.colorbar(label=varkey + ' ' + var.units.strip())
plt.savefig('example.png')

Mapping Partial PseudoNetCDF

The second code segment uses PseudoNetCDF to open and get the map, but is otherwise similar to the first.

import matplotlib.pyplot as plt
import numpy as np
import matplotlib.colors as mc
import PseudoNetCDF as pnc

path = 'ACONC.nc'
f = pnc.pncopen(path, format='ioapi')
var = f.variables['NO2']

bmap = f.getMap()

x = np.arange(f.NCOLS + 1) * f.XCELL
y = np.arange(f.NROWS + 1) * f.YCELL

fig, ax = plt.subplots(1, 1)
bmap.drawcoastlines(ax=ax)
bmap.drawcountries(ax=ax)
lay1avgtime = var[:, 0].mean(0)

plt.pcolormesh(x, y, lay1avgtime, norm=mc.LogNorm())
plt.colorbar(label=varkey + ' ' + var.units.strip())
plt.savefig('example.png')

Mapping with PseudoNetCDF Only

This third version relies on PseudoNetCDF to perform all steps.

import matplotlib.colors as mc
import PseudoNetCDF as pnc

path = 'ACONC.nc'
f = pnc.pncopen(path, format='ioapi')
ax = f.plot('NO2', plot_kw=dict(norm=mc.LogNorm()))
plt.savefig('example.png')

Additional Options for PseudoNetCDF.plot

The PseudoNetCDF.plot function takes map_kw, plot_kw, and cbar_kw options that let you further configure the plot.

  • map_kw takes a dictionary that is mostly passed through to the PseudoNetCDF.getMap function. In addition, it takes a boolean for for each of the following coastlines, countries, states, and counties. Setting these to True will add that feature to the map. At this time counties is automatically set to a low z-order and may not be visible.

  • plot_kw takes a dictionary that is passed through as keywords to the matplotlib.Axes.pcolormesh method.

  • cbar_kw takes a dictionary that passed through as keywords to the matplotlib.Figure.colorbar method.