MetPy Declarative Syntax Tutorial#

The declarative syntax that is a part of the MetPy packaged is designed to aid in simple data exploration and analysis needs by simplifying the plotting context from typical verbose Python code. The complexity of data wrangling and plotting are hidden behind the simplified syntax to allow a lower barrier to investigating your data.

Imports#

You’ll note that the number of imports is smaller due to using the declarative syntax. There is no need to import Matplotlib or Cartopy to your code as all of that is done behind the scenes.

from datetime import datetime, timedelta

import xarray as xr

import metpy.calc as mpcalc
from metpy.cbook import get_test_data
from metpy.io import metar
from metpy.plots.declarative import (BarbPlot, ContourPlot, FilledContourPlot, MapPanel,
                                     PanelContainer, PlotObs)
from metpy.units import units

Getting Data#

Depending on what kind of data you are wanting to plot you’ll use either Xarray (for gridded data), Pandas (for CSV data), or the MetPy METAR parser (for METAR data).

We’ll start this tutorial by reading in a gridded dataset using Xarray.

# Open the netCDF file as a xarray Dataset and parse the full dataset
data = xr.open_dataset(get_test_data('GFS_test.nc', False)).metpy.parse_cf()

# View a summary of the Dataset
print(data)

<xarray.Dataset> Size: 2MB
Dimensions:                                  (time: 1, isobaric3: 26, lat: 46,
                                              lon: 101,
                                              height_above_ground1: 1,
                                              isobaric5: 25,
                                              height_above_ground: 1)
Coordinates:
  * time                                     (time) datetime64[ns] 8B 2010-10...
  * isobaric3                                (isobaric3) float32 104B 1e+03 ....
  * lat                                      (lat) float32 184B 65.0 ... 20.0
  * lon                                      (lon) float32 404B 210.0 ... 310.0
    metpy_crs                                object 8B Projection: latitude_l...
  * height_above_ground1                     (height_above_ground1) float32 4B ...
  * isobaric5                                (isobaric5) float32 100B 1e+03 ....
  * height_above_ground                      (height_above_ground) float32 4B ...
Data variables:
    u-component_of_wind_isobaric             (time, isobaric3, lat, lon) float32 483kB ...
    v-component_of_wind_height_above_ground  (time, height_above_ground1, lat, lon) float32 19kB ...
    v-component_of_wind_isobaric             (time, isobaric3, lat, lon) float32 483kB ...
    Relative_humidity_isobaric               (time, isobaric5, lat, lon) float32 465kB ...
    Temperature_isobaric                     (time, isobaric3, lat, lon) float32 483kB ...
    u-component_of_wind_height_above_ground  (time, height_above_ground1, lat, lon) float32 19kB ...
    Temperature_height_above_ground          (time, height_above_ground, lat, lon) float32 19kB ...
    Geopotential_height_isobaric             (time, isobaric3, lat, lon) float32 483kB ...
    Pressure_reduced_to_MSL_msl              (time, lat, lon) float32 19kB ...
    LatLon_Projection                        int64 8B ...

Set Datetime#

Set the date/time of that you desire to plot

plot_time = datetime(2010, 10, 26, 12)

Subsetting Data#

MetPy provides wrappers for the usual xarray indexing and selection routines that can handle quantities with units. For DataArrays, MetPy also allows using the coordinate axis types mentioned above as aliases for the coordinates. And so, if we wanted data to be just over the U.S. for plotting purposes

ds = data.metpy.sel(lat=slice(70, 10), lon=slice(360 - 150, 360 - 55))

For full details on xarray indexing/selection, see xarray’s documentation.

Calculations#

In MetPy 1.0 and later, calculation functions accept Xarray DataArray’s as input and the output a DataArray that can be easily added to an existing Dataset.

As an example, we calculate wind speed from the wind components and add it as a new variable to our Dataset.

ds['wind_speed'] = mpcalc.wind_speed(ds['u-component_of_wind_isobaric'],
                                     ds['v-component_of_wind_isobaric'])

Plotting#

With that minimal preparation, we are now ready to use the simplified plotting syntax to be able to plot our data and analyze the meteorological situation.

General Structure

Set contour attributes
Set map characteristics and collect contours
Collect panels and plot
Show (or save) the results

Valid Plotting Types for Gridded Data:

ContourPlot()
FilledContourPlot()
ImagePlot()
BarbPlot()

More complete descriptions of these and other plotting types, as well as the map panel and panel container classes are at the end of this tutorial.

Let’s plot a 300-hPa map with color-filled wind speed, which we calculated and added to our Dataset above, and geopotential heights over the CONUS.

We’ll start by setting attributes for contours of Geopotential Heights at 300 hPa. We need to set at least the data, field, level, and time attributes. We’ll set a few others to have greater control over hour the data is plotted.

# Set attributes for contours of Geopotential Heights at 300 hPa
cntr2 = ContourPlot()
cntr2.data = ds
cntr2.field = 'Geopotential_height_isobaric'
cntr2.level = 300 * units.hPa
cntr2.time = plot_time
cntr2.contours = list(range(0, 10000, 120))
cntr2.linecolor = 'black'
cntr2.linestyle = 'solid'
cntr2.clabels = True

Now we’ll set the attributes for plotting color-filled contours of wind speed at 300 hPa. Again, the attributes that must be set include data, field, level, and time. We’ll also set a colormap and colorbar to be purposeful for wind speed. Additionally, we’ll set the attribute to change the units from m/s to knots, which is the common plotting units for wind speed.

# Set attributes for plotting color-filled contours of wind speed at 300 hPa
cfill = FilledContourPlot()
cfill.data = ds
cfill.field = 'wind_speed'
cfill.level = 300 * units.hPa
cfill.time = plot_time
cfill.contours = list(range(10, 201, 20))
cfill.colormap = 'BuPu'
cfill.colorbar = 'horizontal'
cfill.plot_units = 'knot'

Once we have our contours (and any colorfill plots) set up, we will want to define the map panel that we’ll plot the data on. This is the place where we can set the view extent, projection of our plot, add map lines like coastlines and states, set a plot title. One of the key elements is to add the data to the map panel as a list with the plots attribute.

# Set the attributes for the map and add our data to the map
panel = MapPanel()
panel.area = [-125, -74, 20, 55]
panel.projection = 'lcc'
panel.layers = ['states', 'coastline', 'borders']
panel.title = f'{cfill.level.m}-hPa Heights and Wind Speed at {plot_time}'
panel.plots = [cfill, cntr2]

Finally we’ll collect all the panels to plot on the figure, set the size of the figure, and ultimately show or save the figure.

# Set the attributes for the panel and put the panel in the figure
pc = PanelContainer()
pc.size = (15, 15)
pc.panels = [panel]

All of our setting now produce the following map!

# Show the image
pc.show()