0
# cdflib
1

2
A Python CDF reader toolkit for reading and writing CDF (Common Data Format) files without requiring NASA CDF library installation. This package provides comprehensive functionality for accessing scientific data stored in CDF format commonly used in space physics and earth sciences, with support for reading CDF metadata, variables, and attributes through a simple Python API.
3

4
## Package Information
5

6
- **Package Name**: cdflib
7
- **Language**: Python  
8
- **Installation**: `pip install cdflib`
9
- **Requirements**: Python >= 3.9, numpy >= 1.21
10

11
## Core Imports
12

13
```python
14
import cdflib
15
```
16

17
Reading CDF files:
18
```python
19
from cdflib import CDF
20
```
21

22
Time epoch handling:
23
```python
24
from cdflib import cdfepoch
25
```
26

27
XArray integration (optional):
28
```python
29
from cdflib.xarray import cdf_to_xarray, xarray_to_cdf
30
```
31

32
## Basic Usage
33

34
### Reading CDF Files
35

36
```python
37
import cdflib
38

39
# Open a CDF file
40
cdf_file = cdflib.CDF('/path/to/file.cdf')
41

42
# Get file information
43
info = cdf_file.cdf_info()
44
print(f"Variables: {info['zVariables']}")
45

46
# Read variable data
47
data = cdf_file.varget('VariableName')
48
print(data)
49

50
# Read with record range
51
subset = cdf_file.varget('VariableName', startrec=0, endrec=100)
52

53
# Get variable attributes
54
attrs = cdf_file.varattsget('VariableName')
55
print(attrs)
56

57
# Get global attributes
58
global_attrs = cdf_file.globalattsget()
59
```
60

61
### Writing CDF Files
62

63
```python
64
import cdflib
65
import numpy as np
66

67
# Create a new CDF file
68
cdf = cdflib.cdfwrite.CDF('/path/to/output.cdf')
69

70
# Write global attributes
71
cdf.write_globalattrs({'Title': 'My Dataset', 'Version': '1.0'})
72

73
# Define and write a variable
74
var_spec = {
75
    'Variable': 'temperature',
76
    'Data_Type': cdf.CDF_REAL4,
77
    'Num_Elements': 1,
78
    'Dims': []
79
}
80
var_data = np.array([20.5, 21.0, 19.8, 22.1])
81
cdf.write_var(var_spec, var_data=var_data)
82

83
# Close the file
84
cdf.close()
85
```
86

87
### Time Epoch Conversion
88

89
```python
90
import cdflib
91

92
# Convert date components to CDF epoch
93
epoch = cdflib.cdfepoch.compute_epoch([2023, 1, 1, 12, 0, 0, 0])
94

95
# Convert CDF epoch to human-readable string
96
time_str = cdflib.cdfepoch.encode_epoch(epoch)
97
print(time_str)  # "01-Jan-2023 12:00:00.000"
98

99
# Convert to Unix timestamp
100
unix_time = cdflib.cdfepoch.unixtime(epoch)
101

102
# Convert Unix timestamp back to CDF epoch
103
new_epoch = cdflib.cdfepoch.timestamp_to_cdfepoch(unix_time)
104
```
105

106
## Architecture
107

108
cdflib follows a modular design with clear separation of concerns:
109

110
- **CDF Reader**: File parsing, metadata extraction, and data reading with support for local files, URLs, and S3 buckets
111
- **CDF Writer**: File creation, metadata writing, and data serialization with compression support
112
- **Epoch System**: Comprehensive time handling for three CDF epoch formats (CDF_EPOCH, CDF_EPOCH16, TT2000)
113
- **XArray Integration**: Seamless conversion between CDF files and xarray Datasets with ISTP compliance
114
- **Data Classes**: Structured containers for CDF metadata and file information
115

116
The library supports multiple data sources (local files, HTTP/HTTPS URLs, S3 buckets) and provides extensive time format conversion capabilities essential for scientific data analysis.
117

118
## Capabilities
119

120
### CDF File Reading
121

122
Complete API for reading CDF files including metadata extraction, variable data access, and attribute retrieval. Supports local files, URLs, and S3 buckets with optional validation and custom string encoding.
123

124
```python { .api }
125
class CDF:
126
    def __init__(self, path, validate=False, string_encoding='ascii', s3_read_method=1): ...
127
    def cdf_info(self): ...
128
    def varget(self, variable, epoch=None, startrec=0, endrec=None): ...
129
    def varinq(self, variable): ...
130
    def attget(self, attribute, entry=None): ...
131
    def globalattsget(self): ...
132
    def varattsget(self, variable): ...
133
```
134

135
[CDF Reading](./cdf-reading.md)
136

137
### CDF File Writing
138

139
Complete API for creating and writing CDF files with support for global attributes, variable definitions, data writing, and file-level compression.
140

141
```python { .api }
142
class CDF:
143
    def __init__(self, path, cdf_spec=None): ...
144
    def write_globalattrs(self, globalAttrs): ...
145
    def write_variableattrs(self, variableAttrs): ...
146
    def write_var(self, var_spec, var_attrs=None, var_data=None): ...
147
    def close(self): ...
148
```
149

150
[CDF Writing](./cdf-writing.md)
151

152
### Time Epoch Conversion
153

154
Comprehensive time handling system supporting all three CDF epoch formats with conversion between CDF epochs, Unix timestamps, numpy datetime64, and human-readable strings.
155

156
```python { .api }
157
class CDFepoch:
158
    @staticmethod
159
    def compute_epoch(dates): ...
160
    @staticmethod
161
    def encode_epoch(epochs, iso_8601=True): ...
162
    @staticmethod
163
    def breakdown_epoch(epochs): ...
164
    @staticmethod
165
    def unixtime(cdf_time): ...
166
    @staticmethod
167
    def timestamp_to_cdfepoch(unixtime_data): ...
168
```
169

170
[Epochs](./epochs.md)
171

172
### XArray Integration
173

174
Seamless conversion between CDF files and xarray Datasets with ISTP (International Solar-Terrestrial Physics) compliance checking and automatic metadata handling.
175

176
```python { .api }
177
def cdf_to_xarray(filename, to_datetime=True, to_unixtime=False, fillval_to_nan=False): ...
178
def xarray_to_cdf(dataset, file_name, ...): ...
179
```
180

181
[XArray Integration](./xarray-integration.md)
182

183
## Core Types
184

185
```python { .api }
186
# Data classes for CDF metadata
187
class CDFInfo:
188
    """General CDF file information"""
189
    
190
class VDRInfo:
191
    """Variable descriptor record information"""
192
    
193
class ADRInfo:
194
    """Attribute descriptor record information"""
195
    
196
class AttData:
197
    """Attribute data container"""
198

199
# CDF data type constants (for cdfwrite)
200
CDF_INT1 = 1
201
CDF_INT2 = 2  
202
CDF_INT4 = 4
203
CDF_INT8 = 8
204
CDF_UINT1 = 11
205
CDF_UINT2 = 12
206
CDF_UINT4 = 14
207
CDF_REAL4 = 21
208
CDF_REAL8 = 22
209
CDF_EPOCH = 31
210
CDF_EPOCH16 = 32
211
CDF_TIME_TT2000 = 33
212
CDF_BYTE = 41
213
CDF_FLOAT = 44
214
CDF_DOUBLE = 45
215
CDF_CHAR = 51
216
CDF_UCHAR = 52
217
```