0
# MetPy
1
2
MetPy is a comprehensive Python library designed for meteorological data analysis and weather visualization. It provides tools for reading, processing, and performing calculations with weather data, offering functionality equivalent to GEMPAK for reading meteorological data from various formats, calculating derived fields, and creating weather maps and atmospheric soundings including Skew-T log-P diagrams.
3
4
The library integrates seamlessly with the scientific Python ecosystem (NumPy, SciPy, Matplotlib, Pandas, Xarray) and supports multiple data sources including NEXRAD radar data, surface observations, and upper-air soundings. MetPy is designed for researchers, educators, and anyone needing to script weather analysis, providing a well-documented and well-tested foundation for meteorological applications with features like unit handling through Pint, geographic projections via PyProj, and extensive calculation functions for atmospheric science applications.
5
6
## Package Information
7
8
- **Package Name**: MetPy
9
- **Package Type**: Library
10
- **Language**: Python
11
- **Installation**: `pip install metpy`
12
13
## Core Imports
14
15
```python
16
import metpy
17
import metpy.calc as mpcalc
18
from metpy.units import units
19
import metpy.constants as constants
20
```
21
22
For xarray integration:
23
24
```python
25
import xarray as xr
26
import metpy.xarray # Enables .metpy accessor
27
```
28
29
For plotting:
30
31
```python
32
from metpy.plots import SkewT, Hodograph, StationPlot
33
import metpy.plots as plots
34
```
35
36
## Basic Usage
37
38
```python
39
import metpy.calc as mpcalc
40
from metpy.units import units
41
import numpy as np
42
43
# Basic thermodynamic calculations with proper units
44
temperature = 25 * units.celsius
45
pressure = 1013 * units.hPa
46
dewpoint = 15 * units.celsius
47
48
# Calculate relative humidity
49
rh = mpcalc.relative_humidity_from_dewpoint(temperature, dewpoint)
50
print(f"Relative Humidity: {rh}")
51
52
# Calculate potential temperature
53
theta = mpcalc.potential_temperature(pressure, temperature)
54
print(f"Potential Temperature: {theta}")
55
56
# Work with arrays and units
57
temps = np.array([20, 25, 30]) * units.celsius
58
pressures = np.array([1000, 850, 700]) * units.hPa
59
60
# Calculate multiple values at once
61
potential_temps = mpcalc.potential_temperature(pressures, temps)
62
print(f"Potential Temperatures: {potential_temps}")
63
```
64
65
## Architecture
66
67
MetPy is organized around several key components that work together:
68
69
- **Units System**: Built on Pint, provides dimensional analysis and unit conversion for all meteorological quantities
70
- **Calculation Functions**: Over 150 functions covering thermodynamics, dynamics, and kinematics for atmospheric science
71
- **XArray Integration**: Seamless integration with xarray for coordinate-aware meteorological data analysis
72
- **I/O System**: Readers for major meteorological file formats (GEMPAK, NEXRAD, GINI, METAR)
73
- **Plotting Tools**: Specialized meteorological plots including Skew-T diagrams and hodographs
74
- **Constants Library**: Complete set of physical constants for atmospheric and earth science calculations
75
76
This modular design allows MetPy to serve as both a comprehensive toolkit and a foundation for domain-specific meteorological applications.
77
78
## Capabilities
79
80
### Meteorological Calculations
81
82
Comprehensive set of 150+ atmospheric science calculation functions covering thermodynamics, dynamics, and kinematics. Includes temperature conversions, moisture calculations, stability indices, wind analysis, and advanced atmospheric physics.
83
84
```python { .api }
85
# Thermodynamic functions
86
def potential_temperature(pressure, temperature): ...
87
def equivalent_potential_temperature(pressure, temperature, dewpoint): ...
88
def mixing_ratio(partial_press, total_press): ...
89
def relative_humidity_from_dewpoint(temperature, dewpoint): ...
90
def dewpoint_from_relative_humidity(temperature, relative_humidity): ...
91
def specific_humidity_from_dewpoint(pressure, dewpoint): ...
92
def precipitable_water(pressure, dewpoint): ...
93
94
# Dynamic meteorology functions
95
def geostrophic_wind(geopotential, f=None, dx=None, dy=None): ...
96
def vorticity(u, v, dx=None, dy=None): ...
97
def divergence(u, v, dx=None, dy=None): ...
98
def advection(scalar, u, v, dx=None, dy=None): ...
99
def q_vector(geopotential, temperature, pressure, u, v): ...
100
def shearing_deformation(u, v, dx=None, dy=None): ...
101
102
# Stability and parcel functions
103
def lifted_index(pressure, temperature, parcel_profile): ...
104
def cape_cin(pressure, temperature, dewpoint, parcel_profile): ...
105
def surface_based_cape_cin(pressure, temperature, dewpoint): ...
106
def most_unstable_cape_cin(pressure, temperature, dewpoint): ...
107
def parcel_profile(pressure, temperature, dewpoint): ...
108
def lfc(pressure, temperature, dewpoint): ...
109
def el(pressure, temperature, dewpoint): ...
110
def ccl(pressure, temperature, dewpoint): ...
111
112
# Stability indices
113
def k_index(pressure, temperature, dewpoint): ...
114
def showalter_index(pressure, temperature, dewpoint): ...
115
def total_totals_index(pressure, temperature, dewpoint): ...
116
117
# Severe weather parameters
118
def bulk_shear(pressure, u, v, height=None, bottom=None, depth=None): ...
119
def storm_relative_helicity(height, u, v, depth): ...
120
```
121
122
[Meteorological Calculations](./calculation-functions.md)
123
124
### Physical Constants
125
126
Complete library of 60+ physical constants for Earth, atmospheric, and water properties. All constants include proper units and are ready for use in calculations without unit conversion errors.
127
128
```python { .api }
129
# Earth constants
130
earth_gravity = 9.80665 * units('m/s^2')
131
earth_avg_radius = 6371008.7714 * units.m
132
133
# Atmospheric constants
134
dry_air_gas_constant = 287.0 * units('J/(kg*K)')
135
atmos_pressure_sea_level = 101325.0 * units.Pa
136
137
# Water/moisture constants
138
water_heat_vaporization = 2.501e6 * units('J/kg')
139
water_molecular_weight = 18.0153 * units('g/mol')
140
```
141
142
[Physical Constants](./physical-constants.md)
143
144
### Data Input/Output
145
146
Robust I/O support for major meteorological file formats including GEMPAK surface/sounding/grid data, NEXRAD Level 2/3 radar data, GINI satellite imagery, and METAR observations with automatic format detection and metadata preservation.
147
148
```python { .api }
149
# File format readers
150
class GempakSurface: ...
151
class GempakSounding: ...
152
class GempakGrid: ...
153
class Level2File: ... # NEXRAD
154
class Level3File: ... # NEXRAD
155
class GiniFile: ... # Satellite data
156
157
# METAR parsing
158
def parse_metar_file(filename): ...
159
def parse_metar_to_dataframe(filename): ...
160
```
161
162
[Data Input/Output](./data-io.md)
163
164
### Meteorological Plotting
165
166
Specialized plotting system for atmospheric science including Skew-T log-P diagrams, hodographs, station plots, and declarative plotting framework for publication-quality meteorological visualizations.
167
168
```python { .api }
169
# Specialized meteorological diagrams
170
class SkewT: ...
171
class Hodograph: ...
172
class StationPlot: ...
173
174
# Declarative plotting framework
175
class ImagePlot: ...
176
class ContourPlot: ...
177
class FilledContourPlot: ...
178
class BarbPlot: ... # Wind barbs
179
class ArrowPlot: ... # Wind vectors
180
class MapPanel: ...
181
class PanelContainer: ...
182
```
183
184
[Meteorological Plotting](./plotting.md)
185
186
### XArray Integration
187
188
Seamless integration with xarray providing meteorology-aware data analysis through custom accessors. Automatic coordinate identification, unit handling, CRS support, and coordinate transformations for atmospheric data.
189
190
```python { .api }
191
# DataArray accessor methods (via .metpy)
192
@property
193
def units: ... # Get/set units
194
def convert_units(units): ...
195
def quantify(): ... # Convert to pint quantities
196
def assign_crs(cf_attributes): ...
197
def coordinates(*args): ... # Get coordinates by type
198
199
# Dataset accessor methods (via .metpy)
200
def parse_cf(varname=None): ...
201
def assign_latitude_longitude(): ...
202
def quantify(): ...
203
```
204
205
[XArray Integration](./xarray-integration.md)
206
207
### Spatial Interpolation
208
209
Advanced interpolation functions for meteorological data including natural neighbor, inverse distance weighting, Barnes and Cressman objective analysis, and cross-section extraction from 3D atmospheric data.
210
211
```python { .api }
212
# Grid interpolation methods
213
def natural_neighbor_to_grid(xp, yp, variable, interp_type='linear'): ...
214
def inverse_distance_to_grid(xp, yp, variable, hres, search_radius=None): ...
215
def barnes_to_grid(xp, yp, variable, hres, search_radius): ...
216
def cressman_to_grid(xp, yp, variable, hres, search_radius): ...
217
218
# Cross-section analysis
219
def cross_section(data, start, end): ...
220
def interpolate_1d(x, xp, *args, axis=0): ...
221
```
222
223
[Spatial Interpolation](./interpolation.md)
224
225
## Types
226
227
```python { .api }
228
# Common types used throughout MetPy
229
from typing import Union, Optional, Sequence
230
import numpy as np
231
import xarray as xr
232
from pint import Quantity
233
234
# Meteorological data types
235
ArrayLike = Union[np.ndarray, xr.DataArray, Sequence, Quantity]
236
Pressure = Quantity # Must be pressure units
237
Temperature = Quantity # Must be temperature units
238
Length = Quantity # Must be length units
239
Speed = Quantity # Must be velocity units
240
241
# Coordinate system types
242
CRS = object # Coordinate reference system
243
```