0
# Data Extraction
1
2
Functionality for extracting meteorological data arrays, coordinate grids, and metadata from GRIB messages. Handles various grid types and supports data subsetting.
3
4
## Capabilities
5
6
### Data Array Access
7
8
Extract meteorological data values from GRIB messages as NumPy arrays.
9
10
```python { .api }
11
class gribmessage:
12
def __getitem__(self, key):
13
"""
14
Get GRIB key values, including special 'values' key for data.
15
16
Parameters:
17
- key: str, GRIB key name
18
Special keys:
19
- 'values': returns data array (numpy.ndarray)
20
- any GRIB key: returns metadata value
21
22
Returns:
23
Value depends on key - numpy array for 'values', various types for metadata
24
"""
25
26
def expand_grid(self, expand_reduced: bool):
27
"""
28
Control whether reduced grids are expanded to regular grids.
29
30
Parameters:
31
- expand_reduced: bool
32
True: expand reduced grids to regular grids (default)
33
False: keep data on unstructured reduced grid (1D array)
34
"""
35
```
36
37
Usage example:
38
```python
39
grbs = pygrib.open('weather.grb')
40
grb = grbs.select(shortName='t', level=500)[0]
41
42
# Get data array (default: expanded to regular grid)
43
data = grb['values'] # 2D numpy array
44
print(f"Data shape: {data.shape}")
45
print(f"Temperature range: {data.min():.1f} to {data.max():.1f} K")
46
47
# Control grid expansion
48
grb.expand_grid(False) # Keep as reduced grid
49
data_1d = grb['values'] # 1D numpy array
50
print(f"Reduced grid shape: {data_1d.shape}")
51
```
52
53
### Coordinate Grid Access
54
55
Extract latitude and longitude coordinate arrays corresponding to the data grid.
56
57
```python { .api }
58
class gribmessage:
59
def latlons(self):
60
"""
61
Get latitude/longitude coordinate arrays for the grid.
62
63
Supports regular lat/lon, Gaussian, Mercator, stereographic,
64
Lambert conformal, Albers equal-area, space-view, azimuthal
65
equidistant, reduced Gaussian, reduced lat/lon, Lambert
66
azimuthal equal-area, rotated lat/lon and rotated Gaussian grids.
67
68
Returns:
69
Tuple of (lats, lons) where:
70
- lats: numpy.ndarray, latitude values in degrees
71
- lons: numpy.ndarray, longitude values in degrees
72
Arrays have same shape as data grid (when expanded)
73
74
Raises:
75
ValueError: If grid type is unsupported
76
"""
77
```
78
79
Usage example:
80
```python
81
grb = grbs.select(shortName='t', level=500)[0]
82
83
# Get coordinate grids
84
lats, lons = grb.latlons()
85
print(f"Lat range: {lats.min():.1f} to {lats.max():.1f} degrees")
86
print(f"Lon range: {lons.min():.1f} to {lons.max():.1f} degrees")
87
print(f"Grid shape: {lats.shape}")
88
89
# Use with data for geographic analysis
90
data = grb['values']
91
import matplotlib.pyplot as plt
92
plt.contourf(lons, lats, data)
93
plt.colorbar()
94
```
95
96
### Data Subsetting
97
98
Extract data for specific geographic regions by latitude/longitude bounds.
99
100
```python { .api }
101
class gribmessage:
102
def data(self, lat1=None, lat2=None, lon1=None, lon2=None):
103
"""
104
Extract data subset for specified lat/lon boundaries.
105
106
Parameters:
107
- lat1: float, optional, southern boundary latitude
108
- lat2: float, optional, northern boundary latitude
109
- lon1: float, optional, western boundary longitude
110
- lon2: float, optional, eastern boundary longitude
111
112
Returns:
113
Tuple of (data_subset, lats_subset, lons_subset):
114
- data_subset: numpy.ndarray, data values in region
115
- lats_subset: numpy.ndarray, latitude coordinates
116
- lons_subset: numpy.ndarray, longitude coordinates
117
"""
118
```
119
120
Usage example:
121
```python
122
grb = grbs.select(shortName='t', level=500)[0]
123
124
# Extract data for North America region
125
data_subset, lats_subset, lons_subset = grb.data(
126
lat1=25, # Southern boundary
127
lat2=70, # Northern boundary
128
lon1=220, # Western boundary (260W = 220E)
129
lon2=320 # Eastern boundary (40W = 320E)
130
)
131
132
print(f"Subset shape: {data_subset.shape}")
133
print(f"Lat bounds: {lats_subset.min():.1f} to {lats_subset.max():.1f}")
134
print(f"Lon bounds: {lons_subset.min():.1f} to {lons_subset.max():.1f}")
135
```
136
137
### Metadata Access
138
139
Query GRIB keys and metadata from messages.
140
141
```python { .api }
142
class gribmessage:
143
def keys(self):
144
"""
145
Get list of available GRIB keys for this message.
146
147
Returns:
148
List of str, all available GRIB key names
149
"""
150
151
def has_key(self, key: str) -> bool:
152
"""
153
Check if GRIB key exists in message.
154
155
Parameters:
156
- key: str, GRIB key name
157
158
Returns:
159
bool, True if key exists
160
"""
161
162
def valid_key(self, key: str) -> bool:
163
"""
164
Check if GRIB key is valid and accessible.
165
166
Parameters:
167
- key: str, GRIB key name
168
169
Returns:
170
bool, True if key is valid and can be accessed
171
"""
172
173
def is_missing(self, key: str) -> bool:
174
"""
175
Check if GRIB key value is missing/undefined.
176
177
Parameters:
178
- key: str, GRIB key name
179
180
Returns:
181
bool, True if key value is missing
182
"""
183
```
184
185
Usage example:
186
```python
187
grb = grbs.select(shortName='t', level=500)[0]
188
189
# Explore available keys
190
all_keys = grb.keys()
191
print(f"Total keys: {len(all_keys)}")
192
print(f"First 10 keys: {all_keys[:10]}")
193
194
# Check key availability
195
print(f"Has temperature data: {grb.has_key('values')}")
196
print(f"Has forecast time: {grb.has_key('forecastTime')}")
197
print(f"Valid shortName: {grb.valid_key('shortName')}")
198
199
# Check for missing values
200
print(f"Missing bitmap: {grb.is_missing('bitmap')}")
201
202
# Access common metadata
203
metadata = {
204
'parameter': grb['shortName'],
205
'level': grb['level'],
206
'units': grb['units'],
207
'forecast_time': grb['forecastTime'],
208
'valid_date': grb.validDate,
209
'analysis_date': grb.analDate
210
}
211
print(metadata)
212
```
213
214
### Special Message Attributes
215
216
Access computed attributes that pygrib adds to GRIB messages.
217
218
```python { .api }
219
class gribmessage:
220
@property
221
def messagenumber(self) -> int:
222
"""Message number in the file"""
223
224
@property
225
def projparams(self) -> dict:
226
"""Proj4 projection parameters (None for unsupported grids)"""
227
228
@property
229
def expand_reduced(self) -> bool:
230
"""Whether reduced grids are expanded to regular grids"""
231
232
@property
233
def fcstimeunits(self) -> str:
234
"""Forecast time units string"""
235
236
@property
237
def analDate(self):
238
"""Analysis date as datetime object"""
239
240
@property
241
def validDate(self):
242
"""Valid forecast date as datetime object"""
243
```
244
245
Usage example:
246
```python
247
grb = grbs.select(shortName='t', level=500)[0]
248
249
# Message position info
250
print(f"Message number: {grb.messagenumber}")
251
252
# Date/time information
253
print(f"Analysis date: {grb.analDate}")
254
print(f"Valid date: {grb.validDate}")
255
print(f"Forecast time units: {grb.fcstimeunits}")
256
257
# Projection information
258
if grb.projparams:
259
print(f"Projection: {grb.projparams}")
260
else:
261
print("Unsupported or simple lat/lon grid")
262
263
# Grid expansion setting
264
print(f"Expand reduced grids: {grb.expand_reduced}")
265
```
266
267
### Attribute-Style Access
268
269
GRIB keys can be accessed as object attributes for convenience.
270
271
```python { .api }
272
class gribmessage:
273
def __getattr__(self, item):
274
"""Access GRIB keys as attributes"""
275
276
def __setattr__(self, name, value):
277
"""Set GRIB keys as attributes"""
278
```
279
280
Usage example:
281
```python
282
grb = grbs.select(shortName='t', level=500)[0]
283
284
# Access via attributes (equivalent to grb['key'])
285
param_name = grb.shortName
286
level_value = grb.level
287
units = grb.units
288
forecast_hour = grb.forecastTime
289
290
print(f"{param_name} at {level_value} {grb.typeOfLevel}")
291
print(f"Units: {units}")
292
print(f"Forecast: +{forecast_hour} hours")
293
294
# Set via attributes (equivalent to grb['key'] = value)
295
grb.forecastTime = 120
296
grb.parameterNumber = 11 # Change parameter
297
```