0
# CDF File Reading
1

2
Complete API for reading CDF files including metadata extraction, variable data access, and attribute retrieval. The CDF reader supports local files, HTTP/HTTPS URLs, and S3 buckets with optional MD5 validation and custom string encoding.
3

4
## Capabilities
5

6
### CDF File Opening
7

8
Initialize a CDF reader with support for various data sources and configuration options.
9

10
```python { .api }
11
class CDF:
12
    def __init__(self, path, validate=False, string_encoding='ascii', s3_read_method=1):
13
        """
14
        Open a CDF file for reading.
15
        
16
        Parameters:
17
        - path (str | Path): Path to CDF file, HTTP/HTTPS URL, or S3 URL (s3://bucket/key)
18
        - validate (bool): If True, validate MD5 checksum of the file
19
        - string_encoding (str): Character encoding for strings (default: 'ascii')
20
        - s3_read_method (int): S3 read method (1=memory, 2=tmp file, 3=streaming)
21
        
22
        Returns:
23
        CDF reader instance
24
        """
25
```
26

27
**Usage Example:**
28

29
```python
30
import cdflib
31

32
# Local file
33
cdf = cdflib.CDF('/path/to/file.cdf')
34

35
# Remote URL
36
cdf = cdflib.CDF('https://example.com/data.cdf')
37

38
# S3 bucket
39
cdf = cdflib.CDF('s3://my-bucket/data.cdf')
40

41
# With validation and UTF-8 encoding
42
cdf = cdflib.CDF('/path/to/file.cdf', validate=True, string_encoding='utf-8')
43
```
44

45
### File Information Retrieval
46

47
Get comprehensive information about the CDF file structure and contents.
48

49
```python { .api }
50
def cdf_info(self):
51
    """
52
    Get general information about the CDF file.
53
    
54
    Returns:
55
    CDFInfo: Object containing file metadata including:
56
        - rVariables: List of record-varying variable names
57
        - zVariables: List of non-record-varying variable names  
58
        - Attributes: List of attribute names
59
        - Version: CDF library version info
60
        - Encoding: Data encoding information
61
        - Majority: Row/column majority
62
        - Format: Single/multi-file format
63
        - Compressed: Compression status
64
        - Checksum: Checksum validation status
65
    """
66
```
67

68
**Usage Example:**
69

70
```python
71
cdf = cdflib.CDF('data.cdf')
72
info = cdf.cdf_info()
73

74
print(f"Variables: {info['zVariables']}")
75
print(f"Attributes: {info['Attributes']}")
76
print(f"Compressed: {info['Compressed']}")
77
print(f"Encoding: {info['Encoding']}")
78
```
79

80
### Variable Information Inquiry
81

82
Get detailed information about specific variables including data types, dimensions, and record variance.
83

84
```python { .api }
85
def varinq(self, variable):
86
    """
87
    Get detailed information about a specific variable.
88
    
89
    Parameters:
90
    - variable (str): Variable name
91
    
92
    Returns:
93
    VDRInfo: Variable descriptor containing:
94
        - Variable: Variable name
95
        - Num_Elements: Number of elements per value
96
        - Data_Type: CDF data type constant
97
        - Data_Type_Description: Human-readable data type
98
        - Num_Dims: Number of dimensions
99
        - Dim_Sizes: List of dimension sizes
100
        - Sparse: Sparseness type
101
        - Last_Rec: Last written record number
102
        - Rec_Vary: Record variance (True/False)
103
        - Dim_Vary: Dimension variance list
104
        - Pad: Pad value
105
        - Compress: Compression type
106
        - Block_Factor: Blocking factor
107
    """
108
```
109

110
**Usage Example:**
111

112
```python
113
cdf = cdflib.CDF('data.cdf')
114
var_info = cdf.varinq('temperature')
115

116
print(f"Data type: {var_info['Data_Type_Description']}")
117
print(f"Dimensions: {var_info['Dim_Sizes']}")
118
print(f"Record varying: {var_info['Rec_Vary']}")
119
print(f"Last record: {var_info['Last_Rec']}")
120
```
121

122
### Variable Data Reading
123

124
Read variable data with optional record range filtering and epoch-based selection.
125

126
```python { .api }
127
def varget(self, variable=None, epoch=None, starttime=None, endtime=None, 
128
           startrec=0, endrec=None):
129
    """
130
    Read variable data from the CDF file.
131
    
132
    Parameters:
133
    - variable (str, optional): Variable name to read
134
    - epoch (str, optional): Name of time variable for time-based filtering
135
    - starttime (list, optional): Start time components for time range filtering
136
    - endtime (list, optional): End time components for time range filtering
137
    - startrec (int): Starting record number (0-based, default: 0)
138
    - endrec (int, optional): Ending record number (inclusive, default: all records)
139
    
140
    Returns:
141
    str | numpy.ndarray: Variable data array with appropriate dimensions and data type
142
    
143
    Notes:
144
    Time components should be provided as:
145
    - CDF_EPOCH: [year, month, day, hour, minute, second, millisecond]
146
    - CDF_EPOCH16: [year, month, day, hour, minute, second, ms, us, ns, ps]
147
    - TT2000: [year, month, day, hour, minute, second, ms, us, ns]
148
    """
149
```
150

151
**Usage Examples:**
152

153
```python
154
import cdflib
155

156
cdf = cdflib.CDF('data.cdf')
157

158
# Read all data for a variable
159
all_data = cdf.varget('temperature')
160

161
# Read specific record range
162
subset = cdf.varget('temperature', startrec=100, endrec=200)
163

164
# Read data for specific time range using time components
165
time_subset = cdf.varget('temperature', 
166
                        starttime=[2023, 1, 1, 0, 0, 0, 0],
167
                        endtime=[2023, 1, 2, 0, 0, 0, 0])
168

169
# Read with specific epoch variable name for time filtering
170
spatial_subset = cdf.varget('grid_data', 
171
                           epoch='Epoch',
172
                           starttime=[2023, 1, 1, 0, 0, 0, 0],
173
                           endtime=[2023, 1, 1, 12, 0, 0, 0])
174
```
175

176
### Attribute Information Inquiry
177

178
Get information about global or variable attributes including data types and entry counts.
179

180
```python { .api }
181
def attinq(self, attribute):
182
    """
183
    Get information about a specific attribute.
184
    
185
    Parameters:
186
    - attribute (str | int): Attribute name or number
187
    
188
    Returns:
189
    ADRInfo: Attribute descriptor containing:
190
        - Attribute: Attribute name
191
        - Scope: 'GLOBAL_SCOPE' or 'VARIABLE_SCOPE'
192
        - Max_Entry: Maximum entry number
193
        - Num_Entries: Total number of entries
194
        - Data_Type: Data type of entries
195
        - Num_Elements: Number of elements per entry
196
    """
197
```
198

199
### Attribute Data Reading
200

201
Read attribute data for global attributes or specific variable attribute entries.
202

203
```python { .api }
204
def attget(self, attribute, entry=None):
205
    """
206
    Read attribute data.
207
    
208
    Parameters:
209
    - attribute (str | int): Attribute name or number
210
    - entry (str | int, optional): Entry number for variable attributes, 
211
                                  or variable name for variable attributes
212
    
213
    Returns:
214
    AttData: Attribute data object containing:
215
        - Data: The attribute value(s) as numpy array or scalar
216
        - Data_Type: CDF data type constant
217
        - Num_Elements: Number of elements
218
    """
219
```
220

221
**Usage Examples:**
222

223
```python
224
cdf = cdflib.CDF('data.cdf')
225

226
# Get attribute information
227
attr_info = cdf.attinq('TITLE')
228
print(f"Scope: {attr_info['Scope']}")
229
print(f"Entries: {attr_info['Num_Entries']}")
230

231
# Read global attribute
232
title_data = cdf.attget('TITLE')
233
print(f"Title: {title_data['Data']}")
234

235
# Read variable attribute for specific variable
236
units_data = cdf.attget('UNITS', 'temperature')
237
print(f"Temperature units: {units_data['Data']}")
238
```
239

240
### Bulk Attribute Reading
241

242
Efficiently read all global or variable attributes at once.
243

244
```python { .api }
245
def globalattsget(self):
246
    """
247
    Get all global attributes as a dictionary.
248
    
249
    Returns:
250
    dict: Dictionary mapping attribute names to lists of values.
251
          Each value list contains all entries for that attribute.
252
    """
253

254
def varattsget(self, variable):
255
    """
256
    Get all attributes for a specific variable.
257
    
258
    Parameters:
259
    - variable (str | int): Variable name or number
260
    
261
    Returns:
262
    dict: Dictionary mapping attribute names to values.
263
          Values are numpy arrays or scalars depending on the attribute.
264
    """
265
```
266

267
**Usage Examples:**
268

269
```python
270
cdf = cdflib.CDF('data.cdf')
271

272
# Get all global attributes
273
global_attrs = cdf.globalattsget()
274
for attr_name, attr_values in global_attrs.items():
275
    print(f"{attr_name}: {attr_values}")
276

277
# Get all attributes for a specific variable
278
temp_attrs = cdf.varattsget('temperature')
279
print(f"Units: {temp_attrs.get('UNITS', 'N/A')}")
280
print(f"Fill value: {temp_attrs.get('FILLVAL', 'N/A')}")
281
print(f"Valid range: {temp_attrs.get('VALIDMIN', 'N/A')} to {temp_attrs.get('VALIDMAX', 'N/A')}")
282
```
283

284
### Advanced Variable Descriptor Access
285

286
Get detailed variable descriptor record information for advanced use cases.
287

288
```python { .api }
289
def vdr_info(self, variable):
290
    """
291
    Get detailed variable descriptor record information.
292
    
293
    Parameters:
294
    - variable (str | int): Variable name or number
295
    
296
    Returns:
297
    VDR: Detailed variable descriptor record with low-level CDF information
298
    including internal record structure, compression details, and storage layout.
299
    """
300
```
301

302
## Error Handling
303

304
The CDF reader raises standard Python exceptions for common error conditions:
305

306
- **FileNotFoundError**: When the specified CDF file cannot be found
307
- **OSError**: For file I/O errors or permission issues
308
- **ValueError**: For invalid parameter values or malformed CDF data
309
- **KeyError**: When accessing non-existent variables or attributes
310

311
**Example Error Handling:**
312

313
```python
314
import cdflib
315

316
try:
317
    cdf = cdflib.CDF('nonexistent.cdf')
318
except FileNotFoundError:
319
    print("CDF file not found")
320

321
try:
322
    cdf = cdflib.CDF('data.cdf')
323
    data = cdf.varget('INVALID_VARIABLE')
324
except KeyError as e:
325
    print(f"Variable not found: {e}")
326

327
try:
328
    data = cdf.varget('temperature', startrec=-1)
329
except ValueError as e:
330
    print(f"Invalid parameter: {e}")
331
```
332

333
## Types
334

335
```python { .api }
336
class CDFInfo:
337
    """CDF file information dictionary containing metadata about the file structure."""
338

339
class VDRInfo:
340
    """Variable descriptor record information dictionary with variable metadata."""
341

342
class ADRInfo:
343
    """Attribute descriptor record information dictionary with attribute metadata."""
344
    
345
class AttData:
346
    """Attribute data container with 'Data', 'Data_Type', and 'Num_Elements' keys."""
347

348
class VDR:
349
    """Detailed variable descriptor record with low-level CDF internal information."""
350
```