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
```