0
# Meteorological Plotting
1

2
MetPy provides a comprehensive plotting system designed specifically for atmospheric science visualization. It includes specialized meteorological diagrams like Skew-T log-P plots and hodographs, station model plotting, and a declarative plotting framework for creating publication-quality meteorological visualizations.
3

4
## Capabilities
5

6
### Specialized Meteorological Diagrams
7

8
Professional-quality atmospheric soundings and analysis diagrams used in operational meteorology and research.
9

10
```python { .api }
11
class SkewT:
12
    """
13
    Create Skew-T log-P diagrams for atmospheric sounding analysis.
14
    
15
    The Skew-T log-P diagram is the standard tool for analyzing atmospheric
16
    vertical structure, stability, and thermodynamic processes.
17
    """
18
    
19
    def __init__(self, fig=None, rotation=30, aspect=75):
20
        """
21
        Initialize a Skew-T log-P diagram.
22
        
23
        Parameters:
24
        - fig: matplotlib Figure object (optional)
25
        - rotation: skew angle in degrees
26
        - aspect: aspect ratio
27
        """
28
    
29
    def plot(self, pressure, temperature, *args, **kwargs):
30
        """
31
        Plot temperature profile.
32
        
33
        Parameters:
34
        - pressure: pressure levels
35
        - temperature: temperature values
36
        - args, kwargs: additional plot arguments
37
        
38
        Returns:
39
        Matplotlib line objects
40
        """
41
    
42
    def plot_dry_adiabats(self, t0=None, pressure=None, **kwargs):
43
        """
44
        Plot dry adiabatic lines.
45
        
46
        Parameters:
47
        - t0: starting temperatures
48
        - pressure: pressure range
49
        - kwargs: plot styling options
50
        """
51
    
52
    def plot_moist_adiabats(self, t0=None, pressure=None, **kwargs):
53
        """
54
        Plot moist adiabatic lines.
55
        
56
        Parameters:
57
        - t0: starting temperatures  
58
        - pressure: pressure range
59
        - kwargs: plot styling options
60
        """
61
    
62
    def plot_mixing_lines(self, mixing_ratio=None, pressure=None, **kwargs):
63
        """
64
        Plot constant mixing ratio lines.
65
        
66
        Parameters:
67
        - mixing_ratio: mixing ratio values
68
        - pressure: pressure range
69
        - kwargs: plot styling options
70
        """
71
    
72
    def shade_area(self, pressure, temperature1, temperature2=None, **kwargs):
73
        """
74
        Shade area between temperature profiles.
75
        
76
        Parameters:
77
        - pressure: pressure levels
78
        - temperature1: first temperature profile
79
        - temperature2: second temperature profile (optional)
80
        - kwargs: shading options
81
        """
82
    
83
    def shade_cape(self, pressure, temperature, dewpoint, parcel_path=None, **kwargs):
84
        """
85
        Shade CAPE (Convective Available Potential Energy) area.
86
        
87
        Parameters:
88
        - pressure: pressure profile
89
        - temperature: environmental temperature
90
        - dewpoint: dewpoint temperature
91
        - parcel_path: parcel temperature profile
92
        - kwargs: shading options
93
        """
94
    
95
    def shade_cin(self, pressure, temperature, dewpoint, parcel_path=None, **kwargs):
96
        """
97
        Shade CIN (Convective Inhibition) area.
98
        
99
        Parameters:
100
        - pressure: pressure profile
101
        - temperature: environmental temperature
102
        - dewpoint: dewpoint temperature
103
        - parcel_path: parcel temperature profile
104
        - kwargs: shading options
105
        """
106

107
class Hodograph:
108
    """
109
    Create hodograph diagrams for wind shear analysis.
110
    
111
    Hodographs display wind vector changes with height and are essential
112
    for analyzing wind shear and storm motion.
113
    """
114
    
115
    def __init__(self, ax=None, component_range=80):
116
        """
117
        Initialize hodograph plot.
118
        
119
        Parameters:
120
        - ax: matplotlib Axes object (optional)
121
        - component_range: range for u and v components
122
        """
123
    
124
    def add_grid(self, increment=10, **kwargs):
125
        """
126
        Add range rings and radial lines to hodograph.
127
        
128
        Parameters:
129
        - increment: spacing between range rings
130
        - kwargs: grid styling options
131
        """
132
    
133
    def plot(self, u, v, **kwargs):
134
        """
135
        Plot wind hodograph.
136
        
137
        Parameters:
138
        - u: u-component of wind
139
        - v: v-component of wind
140
        - kwargs: plot styling options
141
        
142
        Returns:
143
        Matplotlib line objects
144
        """
145
    
146
    def plot_colormapped(self, u, v, colors, **kwargs):
147
        """
148
        Plot hodograph with color mapping.
149
        
150
        Parameters:
151
        - u: u-component of wind
152
        - v: v-component of wind  
153
        - colors: color values for each point
154
        - kwargs: plot and colormap options
155
        """
156
    
157
    def wind_vectors(self, u, v, **kwargs):
158
        """
159
        Plot wind vectors on hodograph.
160
        
161
        Parameters:
162
        - u: u-component of wind
163
        - v: v-component of wind
164
        - kwargs: vector plot options
165
        """
166

167
class StationPlot:
168
    """
169
    Create station model plots for surface observations.
170
    
171
    Station plots display multiple meteorological parameters at observation
172
    locations using standard WMO symbology and layout conventions.
173
    """
174
    
175
    def __init__(self, ax, x, y, fontsize=10, spacing=None, transform=None):
176
        """
177
        Initialize station plot.
178
        
179
        Parameters:
180
        - ax: matplotlib Axes object
181
        - x: x-coordinates of stations
182
        - y: y-coordinates of stations
183
        - fontsize: text font size
184
        - spacing: minimum spacing between stations
185
        - transform: coordinate transformation
186
        """
187
    
188
    def plot_parameter(self, location, parameter, **kwargs):
189
        """
190
        Plot parameter at specified location around station.
191
        
192
        Parameters:
193
        - location: location code ('NW', 'N', 'NE', 'W', 'C', 'E', 'SW', 'S', 'SE')
194
        - parameter: parameter values to plot
195
        - kwargs: text formatting options
196
        """
197
    
198
    def plot_symbol(self, location, codes, symbol_mapper, **kwargs):
199
        """
200
        Plot symbols using code mapping.
201
        
202
        Parameters:
203
        - location: location around station
204
        - codes: symbol codes
205
        - symbol_mapper: code to symbol mapping
206
        - kwargs: symbol formatting options
207
        """
208
    
209
    def plot_barb(self, u, v, **kwargs):
210
        """
211
        Plot wind barbs at station locations.
212
        
213
        Parameters:
214
        - u: u-component of wind
215
        - v: v-component of wind
216
        - kwargs: barb formatting options
217
        """
218
    
219
    def plot_text(self, location, text, **kwargs):
220
        """
221
        Plot text at station locations.
222
        
223
        Parameters:
224
        - location: text location around station
225
        - text: text values
226
        - kwargs: text formatting options
227
        """
228
```
229

230
### Declarative Plotting Framework
231

232
High-level plotting system for creating complex meteorological visualizations with minimal code.
233

234
```python { .api }
235
class MapPanel:
236
    """
237
    Configure map panel for meteorological plotting.
238
    
239
    Provides map projection, geographic boundaries, and cartographic
240
    features for meteorological data visualization.
241
    """
242
    
243
    def __init__(self, **kwargs):
244
        """
245
        Initialize map panel.
246
        
247
        Parameters:
248
        - projection: map projection ('lcc', 'merc', 'stere', etc.)
249
        - area: geographic area ('us', 'conus', custom bounds)
250
        - layers: cartographic layers to include
251
        - title: panel title
252
        """
253

254
class ImagePlot:
255
    """
256
    Plot raster/image data on maps.
257
    
258
    For displaying satellite imagery, radar data, and gridded
259
    meteorological fields as continuous images.
260
    """
261
    
262
    def __init__(self, **kwargs):
263
        """
264
        Initialize image plot.
265
        
266
        Parameters:
267
        - field: data field to plot
268
        - colormap: colormap name or object
269
        - image_range: data range for color scaling
270
        - colorbar: colorbar configuration
271
        """
272

273
class ContourPlot:
274
    """
275
    Create contour plots of meteorological fields.
276
    
277
    For plotting isopleths of pressure, temperature, geopotential
278
    height, and other continuous meteorological variables.
279
    """
280
    
281
    def __init__(self, **kwargs):
282
        """
283
        Initialize contour plot.
284
        
285
        Parameters:
286
        - field: data field to contour
287
        - level: vertical level or pressure
288
        - contours: contour levels or interval
289
        - clabels: contour label configuration
290
        - linecolor: contour line color
291
        - linestyle: contour line style
292
        """
293

294
class FilledContourPlot:
295
    """
296
    Create filled contour plots.
297
    
298
    For displaying continuous meteorological fields with
299
    color-filled regions between contour levels.
300
    """
301
    
302
    def __init__(self, **kwargs):
303
        """
304
        Initialize filled contour plot.
305
        
306
        Parameters:
307
        - field: data field to plot
308
        - level: vertical level
309
        - contours: contour levels
310
        - colormap: colormap for filling
311
        - colorbar: colorbar configuration
312
        """
313

314
class BarbPlot:
315
    """
316
    Plot wind barbs on meteorological maps.
317
    
318
    Standard meteorological wind barbs showing wind speed
319
    and direction using conventional symbology.
320
    """
321
    
322
    def __init__(self, **kwargs):
323
        """
324
        Initialize wind barb plot.
325
        
326
        Parameters:
327
        - field: wind field (u, v components or speed/direction)
328
        - level: vertical level
329
        - skip: barb spacing/thinning
330
        - scale: barb size scaling
331
        - earth_relative: wind reference frame
332
        """
333

334
class ArrowPlot:
335
    """
336
    Plot vector arrows for wind or other vector fields.
337
    
338
    Vector arrows for displaying wind, storm motion,
339
    or other meteorological vector quantities.
340
    """
341
    
342
    def __init__(self, **kwargs):
343
        """
344
        Initialize arrow plot.
345
        
346
        Parameters:
347
        - field: vector field data
348
        - level: vertical level
349
        - skip: arrow spacing
350
        - scale: arrow size scaling
351
        - pivot: arrow pivot point
352
        """
353

354
class PlotObs:
355
    """
356
    Plot point observations on maps.
357
    
358
    For displaying surface observations, upper-air data,
359
    and other point-based meteorological measurements.
360
    """
361
    
362
    def __init__(self, **kwargs):
363
        """
364
        Initialize observation plot.
365
        
366
        Parameters:
367
        - data: observation data
368
        - fields: fields to plot
369
        - locations: parameter locations on station model
370
        - time: observation time
371
        - level: vertical level (for upper-air)
372
        """
373

374
class PanelContainer:
375
    """
376
    Container for organizing multiple map panels.
377
    
378
    Manages layout and arrangement of multiple meteorological
379
    plots in publication-quality figure layouts.
380
    """
381
    
382
    def __init__(self, **kwargs):
383
        """
384
        Initialize panel container.
385
        
386
        Parameters:
387
        - panel_size: size of individual panels
388
        - ncols: number of columns
389
        - hspace: horizontal spacing
390
        - vspace: vertical spacing
391
        """
392
    
393
    def add_panel(self, panel, **kwargs):
394
        """
395
        Add panel to container.
396
        
397
        Parameters:
398
        - panel: MapPanel object to add
399
        - kwargs: panel-specific options
400
        """
401
    
402
    def add_plot(self, panel_num, plot, **kwargs):
403
        """
404
        Add plot to specific panel.
405
        
406
        Parameters:
407
        - panel_num: panel number (0-indexed)
408
        - plot: plot object to add
409
        - kwargs: plot-specific options
410
        """
411
    
412
    def show(self, **kwargs):
413
        """
414
        Display the complete figure.
415
        
416
        Parameters:
417
        - kwargs: figure display options
418
        """
419
    
420
    def save(self, filename, **kwargs):
421
        """
422
        Save figure to file.
423
        
424
        Parameters:
425
        - filename: output filename
426
        - kwargs: save options (dpi, format, etc.)
427
        """
428
```
429

430
### Colormaps and Styling
431

432
Meteorological color tables and styling utilities.
433

434
```python { .api }
435
def colortables():
436
    """
437
    Access meteorological colormaps and color tables.
438
    
439
    Returns:
440
    Dictionary of available color tables for meteorological parameters
441
    """
442

443
# Available meteorological colormaps
444
meteorological_colormaps = {
445
    'precipitation': 'precipitation colormap for rainfall/snowfall',
446
    'temperature': 'temperature colormap for thermal fields', 
447
    'reflectivity': 'radar reflectivity colormap',
448
    'velocity': 'doppler velocity colormap',
449
    'ir_enhanced': 'enhanced infrared satellite colormap'
450
}
451
```
452

453
## Usage Examples
454

455
### Creating a Skew-T Diagram
456

457
```python
458
from metpy.plots import SkewT
459
from metpy.units import units
460
import matplotlib.pyplot as plt
461
import numpy as np
462

463
# Sample sounding data
464
pressure = np.array([1000, 925, 850, 700, 500, 400, 300, 250, 200]) * units.hPa
465
temperature = np.array([20, 15, 10, 0, -15, -25, -35, -45, -55]) * units.celsius
466
dewpoint = np.array([15, 10, 5, -5, -20, -30, -40, -50, -60]) * units.celsius
467

468
# Create Skew-T plot
469
fig = plt.figure(figsize=(10, 8))
470
skew = SkewT(fig=fig)
471

472
# Plot temperature and dewpoint profiles
473
skew.plot(pressure, temperature, 'r-', linewidth=2, label='Temperature')
474
skew.plot(pressure, dewpoint, 'g-', linewidth=2, label='Dewpoint')
475

476
# Add atmospheric lines
477
skew.plot_dry_adiabats(color='gray', alpha=0.5)
478
skew.plot_moist_adiabats(color='blue', alpha=0.5)
479
skew.plot_mixing_lines(color='green', alpha=0.5)
480

481
# Calculate and plot parcel profile
482
parcel_prof = mpcalc.parcel_profile(pressure, temperature[0], dewpoint[0])
483
skew.plot(pressure, parcel_prof, 'k--', label='Parcel Path')
484

485
# Shade CAPE and CIN areas
486
skew.shade_cape(pressure, temperature, dewpoint)
487
skew.shade_cin(pressure, temperature, dewpoint)
488

489
plt.legend()
490
plt.title('Atmospheric Sounding Analysis')
491
plt.show()
492
```
493

494
### Creating a Hodograph
495

496
```python
497
from metpy.plots import Hodograph
498
import matplotlib.pyplot as plt
499

500
# Sample wind data
501
heights = np.array([0, 1, 2, 3, 6, 9, 12]) * units.km
502
u_wind = np.array([5, 10, 15, 20, 25, 15, 10]) * units('m/s')
503
v_wind = np.array([0, 5, 10, 15, 20, 25, 20]) * units('m/s')
504

505
# Create hodograph
506
fig, ax = plt.subplots(figsize=(8, 8))
507
hodo = Hodograph(ax=ax, component_range=60)
508

509
# Add grid
510
hodo.add_grid(increment=10)
511

512
# Plot wind hodograph with height coloring
513
l = hodo.plot_colormapped(u_wind, v_wind, heights.m, cmap='viridis')
514
plt.colorbar(l, label='Height (km)')
515

516
# Add wind speed rings
517
for speed in [10, 20, 30, 40]:
518
    circle = plt.Circle((0, 0), speed, fill=False, linestyle='--', alpha=0.5)
519
    ax.add_patch(circle)
520

521
plt.title('Wind Hodograph')
522
plt.show()
523
```
524

525
### Declarative Surface Analysis
526

527
```python
528
from metpy.plots import MapPanel, ContourPlot, BarbPlot, PanelContainer
529
from metpy.io import parse_metar_to_dataframe
530

531
# Load surface observations
532
df = parse_metar_to_dataframe('surface_obs.txt')
533

534
# Create map panel
535
panel = MapPanel(projection='lcc', area='us', 
536
                layers=['coastline', 'borders', 'states'])
537

538
# Add pressure contours
539
contour = ContourPlot(field='sea_level_pressure', 
540
                     contours=range(980, 1040, 4),
541
                     clabels=True)
542

543
# Add wind barbs
544
barbs = BarbPlot(field=['u_wind', 'v_wind'], 
545
                skip=2, scale=0.8)
546

547
# Create figure
548
pc = PanelContainer(panel_size=(12, 8))
549
pc.add_panel(panel)
550
pc.add_plot(0, contour)
551
pc.add_plot(0, barbs)
552
pc.show()
553
```
554

555
### Station Plot Example
556

557
```python
558
from metpy.plots import StationPlot
559
import matplotlib.pyplot as plt
560

561
# Sample station data
562
x = [-100, -95, -90, -85]  # Longitude
563
y = [35, 40, 45, 50]       # Latitude
564
temp = [75, 68, 62, 55]    # Temperature (F)
565
pressure = [1013, 1015, 1018, 1020]  # Pressure (hPa)
566

567
# Create map
568
fig, ax = plt.subplots(figsize=(10, 8), subplot_kw=dict(projection=ccrs.PlateCarree()))
569
ax.add_feature(cfeature.COASTLINE)
570
ax.add_feature(cfeature.BORDERS)
571
ax.add_feature(cfeature.STATES)
572

573
# Create station plot
574
stationplot = StationPlot(ax, x, y, fontsize=12, transform=ccrs.PlateCarree())
575

576
# Plot temperature in upper-left position
577
stationplot.plot_parameter('NW', temp, color='red')
578

579
# Plot pressure in upper-right position  
580
stationplot.plot_parameter('NE', pressure, color='blue')
581

582
# Add wind barbs
583
u_wind = [5, -3, 8, -10]
584
v_wind = [10, 15, -5, 12]
585
stationplot.plot_barb(u_wind, v_wind)
586

587
plt.title('Surface Station Plot')
588
plt.show()
589
```
590

591
## Integration with MetPy Ecosystem
592

593
### Data Integration
594

595
Plotting tools integrate seamlessly with MetPy's I/O and calculation functions.
596

597
```python
598
from metpy.io import GempakSurface
599
from metpy.plots import SkewT
600
import metpy.calc as mpcalc
601

602
# Read sounding data
603
sf = GempakSurface('upper_air.gem')
604
sounding = sf.gdxarray(station_id='KDEN')
605

606
# Extract profiles
607
pressure = sounding['PRES']
608
temperature = sounding['TEMP']  
609
dewpoint = sounding['DWPT']
610

611
# Calculate derived quantities
612
parcel_profile = mpcalc.parcel_profile(pressure, temperature[0], dewpoint[0])
613
cape, cin = mpcalc.cape_cin(pressure, temperature, dewpoint, parcel_profile)
614

615
# Create comprehensive Skew-T plot
616
skew = SkewT()
617
skew.plot(pressure, temperature, 'r-', label='Temperature')
618
skew.plot(pressure, dewpoint, 'g-', label='Dewpoint')  
619
skew.plot(pressure, parcel_profile, 'k--', label='Parcel')
620
skew.shade_cape(pressure, temperature, dewpoint)
621
skew.shade_cin(pressure, temperature, dewpoint)
622

623
plt.title(f'CAPE: {cape:.0f} J/kg, CIN: {cin:.0f} J/kg')
624
```
625

626
## Types
627

628
```python { .api }
629
from typing import Optional, Union, Sequence, Dict, Any
630
import matplotlib.pyplot as plt
631
import matplotlib.axes as axes
632
import numpy as np
633
from pint import Quantity
634

635
# Plot object types
636
SkewTPlot = SkewT
637
HodographPlot = Hodograph  
638
StationModelPlot = StationPlot
639

640
# Data types for plotting
641
PlotData = Union[np.ndarray, Quantity, Sequence]
642
ColorMap = Union[str, plt.cm.ColorMap]
643
PlotAxes = Union[axes.Axes, axes.GeoAxes]
644

645
# Configuration types
646
PlotConfig = Dict[str, Any]
647
PanelConfig = Dict[str, Any]
648
```