0
# pygrib
1

2
A high-level Python interface to the ECMWF ECCODES C library for reading and writing GRIB (GRIdded Binary) meteorological data files. pygrib provides comprehensive functionality for accessing GRIB file contents, extracting meteorological data arrays, querying metadata and parameters, and performing limited GRIB file modifications.
3

4
## Package Information
5

6
- **Package Name**: pygrib
7
- **Language**: Python
8
- **Installation**: `pip install pygrib` or `conda install -c conda-forge pygrib`
9

10
## Core Imports
11

12
```python
13
import pygrib
14
```
15

16
## Basic Usage
17

18
```python
19
import pygrib
20
import numpy as np
21

22
# Open a GRIB file
23
grbs = pygrib.open('weather_data.grb')
24

25
# Iterate through all messages
26
for grb in grbs:
27
    print(grb)
28

29
# Select specific messages by criteria
30
temperature_msgs = grbs.select(shortName='t', level=500)
31
for grb in temperature_msgs:
32
    # Get the data array
33
    data = grb['values']
34
    # Get lat/lon coordinates  
35
    lats, lons = grb.latlons()
36
    print(f"Temperature at 500mb: {data.min():.1f} to {data.max():.1f} K")
37

38
grbs.close()
39
```
40

41
## Architecture
42

43
pygrib's architecture centers around three main classes:
44

45
- **open**: GRIB file iterator providing sequential and random access to messages
46
- **gribmessage**: Individual GRIB message containing meteorological data and metadata
47
- **index**: Fast search index for efficient message filtering by key/value criteria
48

49
The library integrates tightly with NumPy for efficient data handling and supports various GRIB grid types including regular/irregular lat/lon, Gaussian, Lambert conformal, stereographic, and Mercator projections.
50

51
## Capabilities
52

53
### File Operations
54

55
Core functionality for opening, reading, and managing GRIB files. Provides iterator-based access with file-like methods for navigation and message retrieval.
56

57
```python { .api }
58
class open:
59
    def __init__(self, filepath_or_buffer): ...
60
    def close(self): ...
61
    def read(self, msgs=None): ...
62
    def readline(self): ...
63
    def seek(self, msg, from_what=0): ...
64
    def tell(self): ...
65
```
66

67
[File Operations](./file-operations.md)
68

69
### Message Access and Selection
70

71
Methods for accessing individual messages, iterating through files, and selecting messages based on criteria. Supports flexible filtering with scalars, sequences, and functions.
72

73
```python { .api }
74
class open:
75
    def message(self, N): ...
76
    def select(self, **kwargs): ...
77
    def rewind(self): ...
78
    
79
def fromstring(gribstring): ...
80
```
81

82
[Message Access](./message-access.md)
83

84
### Data Extraction
85

86
Functionality for extracting meteorological data arrays, coordinate grids, and metadata from GRIB messages. Handles various grid types and supports data subsetting.
87

88
```python { .api }
89
class gribmessage:
90
    def latlons(self): ...
91
    def data(self, lat1=None, lat2=None, lon1=None, lon2=None): ...
92
    def keys(self): ...
93
    def has_key(self, key): ...
94
    def __getitem__(self, key): ...
95
```
96

97
[Data Extraction](./data-extraction.md)
98

99
### Index Operations
100

101
High-performance indexing system for fast message searching and retrieval. Creates optimized indexes on GRIB keys for efficient filtering of large files.
102

103
```python { .api }
104
class index:
105
    def __init__(self, filename, *args): ...
106
    def select(self, **kwargs): ...
107
    def write(self, filename): ...
108
    def close(self): ...
109
```
110

111
[Index Operations](./index-operations.md)
112

113
### Message Modification
114

115
Limited capabilities for modifying existing GRIB messages and writing them to new files. Supports changing metadata keys and data values.
116

117
```python { .api }
118
class gribmessage:
119
    def __setitem__(self, key, value): ...
120
    def tostring(self): ...
121
    
122
def reload(grb): ...
123
```
124

125
[Message Modification](./message-modification.md)
126

127
### Utility Functions
128

129
Helper functions for coordinate transformations, date/time conversions, grid operations, and library configuration.
130

131
```python { .api }
132
def redtoreg(redgrid_data, lonsperlat, missval=None): ...
133
def julian_to_datetime(jd): ...
134
def datetime_to_julian(d): ...
135
def gaulats(nlats): ...
136
def tolerate_badgrib_on(): ...
137
def tolerate_badgrib_off(): ...
138
```
139

140
[Utility Functions](./utility-functions.md)
141

142
## Types
143

144
```python { .api }
145
__version__: str = "2.1.6"
146
"""pygrib package version string"""
147

148
class open:
149
    """GRIB file iterator object"""
150
    messages: int  # Total number of messages
151
    messagenumber: int  # Current position
152
    name: str  # Filename
153
    closed: bool  # File status
154
    has_multi_field_msgs: bool  # Multi-field message flag
155

156
class gribmessage:
157
    """Individual GRIB message object"""
158
    messagenumber: int  # Message number in file
159
    projparams: dict  # Proj4 projection parameters
160
    expand_reduced: bool  # Grid expansion setting
161
    fcstimeunits: str  # Forecast time units
162
    analDate: datetime  # Analysis date
163
    validDate: datetime  # Valid forecast date
164

165
class index:
166
    """GRIB index for fast searching"""  
167
    keys: list  # Indexed key names
168
    types: list  # Key type declarations
169
```