.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "tutorials/declarative_tutorial.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code .. rst-class:: sphx-glr-example-title .. _sphx_glr_tutorials_declarative_tutorial.py: ================================= 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. .. GENERATED FROM PYTHON SOURCE LINES 16-22 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. .. GENERATED FROM PYTHON SOURCE LINES 22-33 .. code-block:: default 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 .. GENERATED FROM PYTHON SOURCE LINES 34-41 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. .. GENERATED FROM PYTHON SOURCE LINES 41-48 .. code-block:: default # 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) .. rst-class:: sphx-glr-script-out .. code-block:: none Dimensions: (time: 1, isobaric3: 26, lat: 46, lon: 101, height_above_ground1: 1, isobaric5: 25, height_above_ground: 1) Coordinates: * time (time) datetime64[ns] 2010-10-26... * isobaric3 (isobaric3) float32 1e+03 ... 1e+05 * lat (lat) float32 65.0 64.0 ... 20.0 * lon (lon) float32 210.0 211.0 ... 310.0 metpy_crs object Projection: latitude_long... * height_above_ground1 (height_above_ground1) float32 10.0 * isobaric5 (isobaric5) float32 1e+03 ... 1e+05 * height_above_ground (height_above_ground) float32 2.0 Data variables: u-component_of_wind_isobaric (time, isobaric3, lat, lon) float32 ... v-component_of_wind_height_above_ground (time, height_above_ground1, lat, lon) float32 ... v-component_of_wind_isobaric (time, isobaric3, lat, lon) float32 ... Relative_humidity_isobaric (time, isobaric5, lat, lon) float32 ... Temperature_isobaric (time, isobaric3, lat, lon) float32 ... u-component_of_wind_height_above_ground (time, height_above_ground1, lat, lon) float32 ... Temperature_height_above_ground (time, height_above_ground, lat, lon) float32 ... Geopotential_height_isobaric (time, isobaric3, lat, lon) float32 ... Pressure_reduced_to_MSL_msl (time, lat, lon) float32 ... LatLon_Projection int64 ... .. GENERATED FROM PYTHON SOURCE LINES 49-53 Set Datetime ------------ Set the date/time of that you desire to plot .. GENERATED FROM PYTHON SOURCE LINES 53-55 .. code-block:: default plot_time = datetime(2010, 10, 26, 12) .. GENERATED FROM PYTHON SOURCE LINES 56-63 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 .. GENERATED FROM PYTHON SOURCE LINES 63-65 .. code-block:: default ds = data.metpy.sel(lat=slice(70, 10), lon=slice(360 - 150, 360 - 55)) .. GENERATED FROM PYTHON SOURCE LINES 66-68 For full details on xarray indexing/selection, see `xarray's documentation `_. .. GENERATED FROM PYTHON SOURCE LINES 70-78 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. .. GENERATED FROM PYTHON SOURCE LINES 78-81 .. code-block:: default ds['wind_speed'] = mpcalc.wind_speed(ds['u-component_of_wind_isobaric'], ds['v-component_of_wind_isobaric']) .. GENERATED FROM PYTHON SOURCE LINES 82-113 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 1. Set contour attributes 2. Set map characteristics and collect contours 3. Collect panels and plot 4. 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. .. GENERATED FROM PYTHON SOURCE LINES 115-118 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. .. GENERATED FROM PYTHON SOURCE LINES 118-130 .. code-block:: default # 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 .. GENERATED FROM PYTHON SOURCE LINES 131-136 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. .. GENERATED FROM PYTHON SOURCE LINES 136-148 .. code-block:: default # 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' .. GENERATED FROM PYTHON SOURCE LINES 149-154 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. .. GENERATED FROM PYTHON SOURCE LINES 154-163 .. code-block:: default # 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] .. GENERATED FROM PYTHON SOURCE LINES 164-166 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. .. GENERATED FROM PYTHON SOURCE LINES 166-172 .. code-block:: default # Set the attributes for the panel and put the panel in the figure pc = PanelContainer() pc.size = (15, 15) pc.panels = [panel] .. GENERATED FROM PYTHON SOURCE LINES 173-174 All of our setting now produce the following map! .. GENERATED FROM PYTHON SOURCE LINES 174-178 .. code-block:: default # Show the image pc.show() .. image-sg:: /tutorials/images/sphx_glr_declarative_tutorial_001.png :alt: 300-hPa Heights and Wind Speed at 2010-10-26 12:00:00 :srcset: /tutorials/images/sphx_glr_declarative_tutorial_001.png :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 179-180 That's it! What a nice looking map, with relatively simple set of code. .. GENERATED FROM PYTHON SOURCE LINES 183-189 Adding Wind Barbs ----------------- We can easily add wind barbs to the plot we generated above by adding another plot type and adding it to the panel. The plot type for wind barbs is ``BarbPlot()`` and has its own set of attributes to control plotting a vector quantity. .. GENERATED FROM PYTHON SOURCE LINES 191-193 We start with setting the attributes that we had before for our 300 hPa plot including, Geopotential Height contours, and color-filled wind speed. .. GENERATED FROM PYTHON SOURCE LINES 193-216 .. code-block:: default # 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 # 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' .. GENERATED FROM PYTHON SOURCE LINES 217-220 Now we'll set the attributes for plotting wind barbs, with the required attributes of data, time, field, and level. The skip attribute is particularly useful for thinning the number of wind barbs that are plotted on the map. Again we convert to units of knots. .. GENERATED FROM PYTHON SOURCE LINES 220-230 .. code-block:: default # Set attributes for plotting wind barbs barbs = BarbPlot() barbs.data = ds barbs.time = plot_time barbs.field = ['u-component_of_wind_isobaric', 'v-component_of_wind_isobaric'] barbs.level = 300 * units.hPa barbs.skip = (3, 3) barbs.plot_units = 'knot' .. GENERATED FROM PYTHON SOURCE LINES 231-233 Add all of our plot types to the panel, don't forget to add in the new wind barbs to our plot list! .. GENERATED FROM PYTHON SOURCE LINES 233-251 .. code-block:: default # 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, barbs] # Set the attributes for the panel and put the panel in the figure pc = PanelContainer() pc.size = (15, 15) pc.panels = [panel] # Show the figure pc.show() .. image-sg:: /tutorials/images/sphx_glr_declarative_tutorial_002.png :alt: 300-hPa Heights and Wind Speed at 2010-10-26 12:00:00 :srcset: /tutorials/images/sphx_glr_declarative_tutorial_002.png :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 252-259 Plot Surface Obs ---------------- We can also plot surface (or upper-air) observations at point locations using the simplified syntax. Whether it is surface or upper-air data, the ``PlotObs()`` class is what you would want to use. Then you would add those observations to a map panel and then collect the panels to plot the figure; similar to what you would do for a gridded plot. .. GENERATED FROM PYTHON SOURCE LINES 259-268 .. code-block:: default df = metar.parse_metar_file(get_test_data('metar_20190701_1200.txt', False), year=2019, month=7) # Let's take a look at the variables that we could plot coming from our METAR observations. print(df.keys()) # Set the observation time obs_time = datetime(2019, 7, 1, 12) .. rst-class:: sphx-glr-script-out .. code-block:: none Index(['station_id', 'latitude', 'longitude', 'elevation', 'date_time', 'wind_direction', 'wind_speed', 'wind_gust', 'visibility', 'current_wx1', 'current_wx2', 'current_wx3', 'low_cloud_type', 'low_cloud_level', 'medium_cloud_type', 'medium_cloud_level', 'high_cloud_type', 'high_cloud_level', 'highest_cloud_type', 'highest_cloud_level', 'cloud_coverage', 'air_temperature', 'dew_point_temperature', 'altimeter', 'current_wx1_symbol', 'current_wx2_symbol', 'current_wx3_symbol', 'remarks', 'air_pressure_at_sea_level', 'eastward_wind', 'northward_wind'], dtype='object') .. GENERATED FROM PYTHON SOURCE LINES 269-281 Setting of our attributes for plotting observations is pretty straightforward and just needs to be lists for the variables, and a comparable number of items for plot characteristics that are specific to the individual fields. For example, the locations around a station plot, the plot units, and any plotting formats would all need to have the same number of items as the fields attribute. Plotting wind bards is done through the vector_field attribute. You can reduce the number of points plotted (especially important for surface observations) with the ``reduce_points`` attribute. For a very basic plot of one field, the minimum required attributes are the data, time, fields, and location attributes. .. GENERATED FROM PYTHON SOURCE LINES 281-297 .. code-block:: default # Plot desired data obs = PlotObs() obs.data = df obs.time = obs_time obs.time_window = timedelta(minutes=15) obs.level = None obs.fields = ['cloud_coverage', 'air_temperature', 'dew_point_temperature', 'air_pressure_at_sea_level', 'current_wx1_symbol'] obs.plot_units = [None, 'degF', 'degF', None, None] obs.locations = ['C', 'NW', 'SW', 'NE', 'W'] obs.formats = ['sky_cover', None, None, lambda v: format(v * 10, '.0f')[-3:], 'current_weather'] obs.reduce_points = 0.75 obs.vector_field = ['eastward_wind', 'northward_wind'] .. GENERATED FROM PYTHON SOURCE LINES 298-300 We use the same Classes for plotting our data on a map panel and collecting all the panels on the figure. In this case we'll focus in on the state of Indiana for plotting. .. GENERATED FROM PYTHON SOURCE LINES 300-317 .. code-block:: default # Panel for plot with Map features panel = MapPanel() panel.layout = (1, 1, 1) panel.projection = 'lcc' panel.area = 'in' panel.layers = ['states'] panel.title = f'Surface plot for {obs_time}' panel.plots = [obs] # Bringing it all together pc = PanelContainer() pc.size = (10, 10) pc.panels = [panel] pc.show() .. image-sg:: /tutorials/images/sphx_glr_declarative_tutorial_003.png :alt: Surface plot for 2019-07-01 12:00:00 :srcset: /tutorials/images/sphx_glr_declarative_tutorial_003.png :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 318-323 Detailed Attribute Descriptions ------------------------------- This final section contains verbose descriptions of the attributes that can be set by the plot types used in this tutorial. .. GENERATED FROM PYTHON SOURCE LINES 325-400 ContourPlot() ------------- This class is designed to plot contours of gridded data, most commonly model output from the GFS, NAM, RAP, or other gridded dataset (e.g., NARR). Attributes: ``data`` This attribute must be set with the variable name that contains the xarray dataset. (Typically this is the variable ds) ``field`` This attribute must be set with the name of the variable that you want to contour. For example, to plot the heights of pressure surfaces from the GFS you would use the name ``‘Geopotential_height_isobaric’`` ``level`` This attribute sets the level of the data you wish to plot. If it is a pressure level, then it must be set to a unit bearing value (e.g., 500*units.hPa). If the variable does not have any vertical levels (e.g., mean sea-level pressure), then the level attribute must be set to None. ``time`` This attribute must be set with a datetime object, just as with the ``PlotObs()`` class. To get a forecast hour, you can use the timedelta function from datetime to add the number of hours into the future you wish to plot. For example, if you wanted the six hour forecast from the 00 UTC 2 February 2020 model run, then you would set the attribute with: ``datetime(2020, 2, 2, 0) + timedelta(hours=6)`` ``contours`` This attribute sets the contour values to be plotted with a list. This can be set manually with a list of integers in square brackets (e.g., ``[5400, 5460, 5520, 5580, 5640, 5700]``) or programmatically (e.g., ``list(range(0, 10000, 60))``). The second method is a way to easily set a contour interval (in this case 60). ``clabel`` This attribute can be set to ``True`` if you desire to have your contours labeled. ``linestyle`` This attribute can be set to make the contours ``‘solid’``, ``‘dashed’``, ``‘dotted’``, or ``‘dashdot’``. Other linestyles are can be used and are found at: https://matplotlib.org/3.1.0/gallery/lines_bars_and_markers/linestyles.html Default is ``‘solid’``. ``linewidth`` This attribute alters the width of the contours (defaults to 1). Setting the value greater than 1 will yield a thicker contour line. ``linecolor`` This attribute sets the color of the contour lines. Default is ``‘black’``. All colors from matplotlib are valid: https://matplotlib.org/3.1.0/_images/sphx_glr_named_colors_003.png ``plot_units`` If you want to change the units for plotting purposes, add the string value of the units desired. For example, if you want to plot temperature in Celsius, then set this attribute to ``‘degC’``. ``scale`` This attribute will scale the field by multiplying by the scale. For example, to scale vorticity to be whole values for contouring you could set the scale to 1e5, such that the data values will be multiplied by 10^5. .. GENERATED FROM PYTHON SOURCE LINES 403-429 FilledContourPlot() ------------------- Works very similarly to ``ContourPlot()``, except that contours are filled using a colormap between contour values. All attributes for ``ContourPlot()`` work for color-filled plots, except for linestyle, linecolor, and linewidth. Additionally, there are the following attributes that work for color-filling: Attributes: ``colormap`` This attribute is used to set a valid colormap from either Matplotlib or MetPy: Matplotlib Colormaps: https://matplotlib.org/3.1.1/gallery/color/colormap_reference.html MetPy Colormaps: https://unidata.github.io/MetPy/v1.0/api/generated/metpy.plots.ctables.html ``colorbar`` This attribute can be set to ``‘vertical’`` or ``‘horizontal’``, which is the location the colorbar will be plotted on the panel. ``image_range`` A set of values indicating the minimum and maximum for the data being plotted. This attribute should be set as ``(min_value, max_value)``, where min_value and max_value are numeric values. .. GENERATED FROM PYTHON SOURCE LINES 431-451 PanelContainer() ---------------- Attributes: ``size`` The size of the figure in inches (e.g., (10, 8)) ``panels`` A list collecting the panels to be plotted in the figure. ``show`` Show the plot ``save`` Save the figure using the Matplotlib arguments/keyword arguments .. GENERATED FROM PYTHON SOURCE LINES 453-490 MapPanel() ---------- Attributes: ``layout`` The Matplotlib layout of the figure. For a single panel figure the setting should be ``(1, 1, 1)`` ``projection`` The projection can be set with the name of a default projection (``‘lcc’``, ``‘mer’``, or ``‘ps’``) or it can be set to a Cartopy projection. ``layers`` This attribute will add map layers to identify boundaries or features to plot on the map. Valid layers are ``'borders'``, ``'coastline'``, ``'states'``, ``'lakes'``, ``'land'``, ``'ocean'``, ``'rivers'``, ``'counties'``. ``area`` This attribute sets the geographical area of the panel. This can be set with a predefined name of an area including all US state postal abbreviations (e.g., ``‘us’``, ``‘natl’``, ``‘in’``, ``‘il’``, ``‘wi’``, ``‘mi’``, etc.) or a tuple value that corresponds to longitude/latitude box based on the projection of the map with the format ``(west-most longitude, east-most longitude, south-most latitude, north-most latitude)``. This tuple defines a box from the lower-left to the upper-right corner. ``title`` This attribute sets a title for the panel. ``plots`` A list collecting the observations to be plotted in the panel. .. GENERATED FROM PYTHON SOURCE LINES 492-532 BarbPlot() ---------- This plot class is used to add wind barbs to the plot with the following Attributes: ``data`` This attribute must be set to the variable that contains the vector components to be plotted. ``field`` This attribute is a list of the vector components to be plotted. For the typical meteorological case it would be the ``[‘u-component’, ‘v-component’]``. ``time`` This attribute should be set to a datetime object, the same as for all other declarative classes. ``barblength`` This attribute sets the length of the wind barbs. The default value is based on the font size. ``color`` This attribute sets the color of the wind barbs, which can be any Matplotlib color. Default color is ``‘black’``. ``earth_relative`` This attribute can be set to False if the vector components are grid relative (e.g., for NAM or NARR output) ``pivot`` This attribute can be set to a string value about where the wind barb will pivot relative to the grid point. Possible values include ``‘tip’`` or ``‘middle’``. Default is ``‘middle’``. .. GENERATED FROM PYTHON SOURCE LINES 534-603 PlotObs() --------- This class is used to plot point observations from the surface or upper-air. Attributes: ``data`` This attribute needs to be set to the DataFrame variable containing the fields that you desire to plot. ``fields`` This attribute is a list of variable names from your DataFrame that you desire to plot at the given locations around the station model. ``level`` For a surface plot this needs to be set to None. ``time`` This attribute needs to be set to subset your data attribute for the time of the observations to be plotted. This needs to be a datetime object. ``locations`` This attribute sets the location of the fields to be plotted around the surface station model. The default location is center ``(‘C’)`` ``time_window`` This attribute allows you to define a window for valid observations (e.g., 15 minutes on either side of the datetime object setting. This is important for surface data since actual observed times are not all exactly on the hour. If multiple observations exist in the defined window, the most recent observations is retained for plotting purposes. ``formats`` This attribute sets a formatter for text or plotting symbols around the station model. For example, plotting mean sea-level pressure is done in a three-digit code and a formatter can be used to achieve that on the station plot. MSLP Formatter: ``lambda v: format(10 * v, '.0f')[-3:]`` For plotting symbols use the available MetPy options through their name. Valid symbol formats are ``'current_weather'``, ``'sky_cover'``, ``'low_clouds'``, ``'mid_clouds'``, ``'high_clouds'``, and ``'pressure_tendency'``. ``colors`` This attribute can change the color of the plotted observation. Default is ``‘black’``. Acceptable colors are those available through Matplotlib: https://matplotlib.org/3.1.1/_images/sphx_glr_named_colors_003.png ``vector_field`` This attribute can be set to a list of wind component values for plotting (e.g., ``[‘uwind’, ‘vwind’]``) ``vector_field_color`` Same as colors except only controls the color of the wind barbs. Default is ``‘black’``. ``reduce_points`` This attribute can be set to a real number to reduce the number of stations that are plotted. Default value is zero (e.g., no points are removed from the plot). .. rst-class:: sphx-glr-timing **Total running time of the script:** ( 0 minutes 23.592 seconds) .. _sphx_glr_download_tutorials_declarative_tutorial.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: declarative_tutorial.py ` .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: declarative_tutorial.ipynb ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_