-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathpycdf.html
487 lines (474 loc) · 46.5 KB
/
pycdf.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<title>pycdf - Python interface to CDF files — SpacePy v0.7.0 Manual</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b76e3c8a" />
<link rel="stylesheet" type="text/css" href="_static/sphinxdoc.css?v=92e3d466" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css?v=fd3f3429" />
<link rel="stylesheet" type="text/css" href="_static/plot_directive.css" />
<script src="_static/documentation_options.js?v=fe7df9b0"></script>
<script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script type="text/javascript" src="_static/copybutton.js"></script>
<link rel="icon" href="_static/spacepy_favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="time - Time conversion, manipulation and implementation of Ticktock class" href="time.html" />
<link rel="prev" title="PyBats - SWMF & BATS-R-US Analysis Tools" href="pybats.html" />
</head><body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="index.html"><img src="_static/spacepy_logo.jpg" border="0" alt="spacepy_logo"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="time.html" title="time - Time conversion, manipulation and implementation of Ticktock class"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="pybats.html" title="PyBats - SWMF & BATS-R-US Analysis Tools"
accesskey="P">previous</a> |</li>
<li><a href="https://spacepy.github.io/"">homepage</a>| </li>
<li><a href="https://github.com/spacepy/spacepy">development</a>| </li>
<li><a href="search.html">search</a>| </li>
<li><a href="index.html">documentation </a> »</li>
<li class="nav-item nav-item-this"><a href="">pycdf - Python interface to CDF files</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="pycdf-python-interface-to-cdf-files">
<h1>pycdf - Python interface to CDF files<a class="headerlink" href="#pycdf-python-interface-to-cdf-files" title="Link to this heading">¶</a></h1>
<section id="contents">
<h2>Contents<a class="headerlink" href="#contents" title="Link to this heading">¶</a></h2>
<nav class="contents local" id="id1">
<ul class="simple">
<li><p><a class="reference internal" href="#create-a-cdf" id="id2">Create a CDF</a></p></li>
<li><p><a class="reference internal" href="#read-a-cdf" id="id3">Read a CDF</a></p></li>
<li><p><a class="reference internal" href="#modify-a-cdf" id="id4">Modify a CDF</a></p></li>
<li><p><a class="reference internal" href="#non-record-varying" id="id5">Non record-varying</a></p></li>
<li><p><a class="reference internal" href="#slicing-and-indexing" id="id6">Slicing and indexing</a></p></li>
<li><p><a class="reference internal" href="#string-handling" id="id7">String handling</a></p></li>
<li><p><a class="reference internal" href="#troubleshooting" id="id8">Troubleshooting</a></p>
<ul>
<li><p><a class="reference internal" href="#cannot-load-cdf-c-library" id="id9">Cannot load CDF C library</a></p></li>
<li><p><a class="reference internal" href="#zlib-error-when-opening-a-cdf" id="id10">ZLIB_ERROR when opening a CDF</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#access-to-cdf-constants-and-the-c-library" id="id11">Access to CDF constants and the C library</a></p></li>
</ul>
</nav>
<p>See also the <a class="reference internal" href="autosummary/spacepy.pycdf.html#module-spacepy.pycdf" title="spacepy.pycdf"><code class="xref py py-obj docutils literal notranslate"><span class="pre">full</span> <span class="pre">API</span> <span class="pre">documentation</span></code></a>.</p>
<section id="create-a-cdf">
<h3><a class="toc-backref" href="#id2" role="doc-backlink">Create a CDF</a><a class="headerlink" href="#create-a-cdf" title="Link to this heading">¶</a></h3>
<p>This example presents the entire sequence of creating a CDF and populating
it with some data; the parts are explained individually below.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">spacepy</span> <span class="kn">import</span> <span class="n">pycdf</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">datetime</span>
<span class="gp">>>> </span><span class="n">time</span> <span class="o">=</span> <span class="p">[</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2000</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">val</span><span class="p">)</span> <span class="k">for</span> <span class="n">val</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">60</span><span class="p">)]</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
<span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">random_sample</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">time</span><span class="p">))</span>
<span class="gp">>>> </span><span class="n">cdf</span> <span class="o">=</span> <span class="n">pycdf</span><span class="o">.</span><span class="n">CDF</span><span class="p">(</span><span class="s1">'MyCDF.cdf'</span><span class="p">,</span> <span class="s1">''</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'Epoch'</span><span class="p">]</span> <span class="o">=</span> <span class="n">time</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'data'</span><span class="p">]</span> <span class="o">=</span> <span class="n">data</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">attrs</span><span class="p">[</span><span class="s1">'Author'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'John Doe'</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">attrs</span><span class="p">[</span><span class="s1">'CreateDate'</span><span class="p">]</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'data'</span><span class="p">]</span><span class="o">.</span><span class="n">attrs</span><span class="p">[</span><span class="s1">'units'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'MeV'</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>Import the pycdf module.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">spacepy</span> <span class="kn">import</span> <span class="n">pycdf</span>
</pre></div>
</div>
<p>Make a data set of <a class="reference external" href="https://docs.python.org/3/library/datetime.html#datetime.datetime" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a>. These will be converted into
CDF_TIME_TT2000 types.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">datetime</span>
<span class="gp">>>> </span><span class="c1"># make a dataset every minute for a hour</span>
<span class="gp">>>> </span><span class="n">time</span> <span class="o">=</span> <span class="p">[</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2000</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">val</span><span class="p">)</span> <span class="k">for</span> <span class="n">val</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">60</span><span class="p">)]</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>A CDF can be created in backward compatibility mode for reading with
CDF library before 3.0, using <a class="reference internal" href="autosummary/spacepy.pycdf.Library.html#spacepy.pycdf.Library.set_backward" title="spacepy.pycdf.Library.set_backward"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_backward()</span></code></a>.
Then <a class="reference external" href="https://docs.python.org/3/library/datetime.html#datetime.datetime" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> objects are degraded to CDF_EPOCH
(millisecond resolution), not CDF_EPOCH16 (microsecond resolution).
Use <a class="reference internal" href="autosummary/spacepy.pycdf.CDF.html#spacepy.pycdf.CDF.new" title="spacepy.pycdf.CDF.new"><code class="xref py py-meth docutils literal notranslate"><span class="pre">new()</span></code></a> to specify a data type.</p>
</div>
<p>Create some random data.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
<span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">random_sample</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">time</span><span class="p">))</span>
</pre></div>
</div>
<p>Create a new empty CDF. The empty string, ‘’, is the name of the CDF to use
as a master; given an empty string, an empty CDF will be created, rather than
copying from a master CDF.
If a master is used, data in the master will be copied to the new CDF.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf</span> <span class="o">=</span> <span class="n">pycdf</span><span class="o">.</span><span class="n">CDF</span><span class="p">(</span><span class="s1">'MyCDF.cdf'</span><span class="p">,</span> <span class="s1">''</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>You cannot create a new CDF with a name that already exists on disk.
It will throw a <a class="reference external" href="https://docs.python.org/3/library/exceptions.html#NameError" title="(in Python v3.13)"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NameError</span></code></a></p>
</div>
<p>To put data into a CDF, assign it directly to an element of the CDF.
CDF objects behave like Python dictionaries.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="c1"># put time into CDF variable Epoch</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'Epoch'</span><span class="p">]</span> <span class="o">=</span> <span class="n">time</span>
<span class="gp">>>> </span><span class="c1"># and the same with data (the smallest data type that fits the data is used by default)</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'data'</span><span class="p">]</span> <span class="o">=</span> <span class="n">data</span>
</pre></div>
</div>
<p>Adding attributes is done similarly. CDF attributes are also treated as dictionaries.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="c1"># add some attributes to the CDF and the data</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">attrs</span><span class="p">[</span><span class="s1">'Author'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'John Doe'</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">attrs</span><span class="p">[</span><span class="s1">'CreateDate'</span><span class="p">]</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'data'</span><span class="p">]</span><span class="o">.</span><span class="n">attrs</span><span class="p">[</span><span class="s1">'units'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'MeV'</span>
</pre></div>
</div>
<p>Closing the CDF ensures the new data are written to disk:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>CDF files, like standard Python files, act as context managers</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">with</span> <span class="n">cdf</span><span class="o">.</span><span class="n">CDF</span><span class="p">(</span><span class="s1">'filename.cdf'</span><span class="p">,</span> <span class="s1">''</span><span class="p">)</span> <span class="k">as</span> <span class="n">cdf_file</span><span class="p">:</span>
<span class="gp">... </span> <span class="c1">#do brilliant things with cdf_file</span>
<span class="gp">>>> </span><span class="c1">#cdf_file is automatically closed here</span>
</pre></div>
</div>
</section>
<section id="read-a-cdf">
<h3><a class="toc-backref" href="#id3" role="doc-backlink">Read a CDF</a><a class="headerlink" href="#read-a-cdf" title="Link to this heading">¶</a></h3>
<p>Reading a CDF is very similar: the CDF object behaves like a dictionary.
The file is only accessed when data are requested. A full example using the above CDF:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">spacepy</span> <span class="kn">import</span> <span class="n">pycdf</span>
<span class="gp">>>> </span><span class="n">cdf</span> <span class="o">=</span> <span class="n">pycdf</span><span class="o">.</span><span class="n">CDF</span><span class="p">(</span><span class="s1">'MyCDF.cdf'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">cdf</span><span class="p">)</span>
<span class="go"> Epoch: CDF_TIME_TT2000 [60]</span>
<span class="go"> data: CDF_FLOAT [60]</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'data'</span><span class="p">][</span><span class="mi">4</span><span class="p">]</span>
<span class="go"> 0.8609974384307861</span>
<span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="n">cdf</span><span class="p">[</span><span class="s1">'data'</span><span class="p">][</span><span class="o">...</span><span class="p">]</span> <span class="c1"># don't forget the [...]</span>
<span class="gp">>>> </span><span class="n">cdf_dat</span> <span class="o">=</span> <span class="n">cdf</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">cdf_dat</span><span class="o">.</span><span class="n">keys</span><span class="p">()</span>
<span class="go"> ['Epoch', 'data']</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>Again import the pycdf module</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">spacepy</span> <span class="kn">import</span> <span class="n">pycdf</span>
</pre></div>
</div>
<p>Then open the CDF, this looks the same and creation, but without mention of a master CDF.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf</span> <span class="o">=</span> <span class="n">pycdf</span><span class="o">.</span><span class="n">CDF</span><span class="p">(</span><span class="s1">'MyCDF.cdf'</span><span class="p">)</span>
</pre></div>
</div>
<p>The default <code class="docutils literal notranslate"><span class="pre">__str__()</span></code> and <code class="docutils literal notranslate"><span class="pre">__repr__()</span></code> behavior explains the contents, type, and size but not the data.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">cdf</span><span class="p">)</span>
<span class="go"> Epoch: CDF_TIME_TT2000 [60]</span>
<span class="go"> data: CDF_FLOAT [60]</span>
</pre></div>
</div>
<p>To access the data one has to request specific elements of the variable, similar to a Python list.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'data'</span><span class="p">][</span><span class="mi">4</span><span class="p">]</span>
<span class="go"> 0.8609974384307861</span>
<span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="n">cdf</span><span class="p">[</span><span class="s1">'data'</span><span class="p">][</span><span class="o">...</span><span class="p">]</span> <span class="c1"># don't forget the [...]</span>
</pre></div>
</div>
<p><a class="reference internal" href="autosummary/spacepy.pycdf.CDF.html#spacepy.pycdf.CDF.copy" title="spacepy.pycdf.CDF.copy"><code class="xref py py-func docutils literal notranslate"><span class="pre">CDF.copy()</span></code></a> will return the entire contents of a CDF, including
attributes, as a <a class="reference internal" href="autosummary/spacepy.datamodel.SpaceData.html#spacepy.datamodel.SpaceData" title="spacepy.datamodel.SpaceData"><code class="xref py py-class docutils literal notranslate"><span class="pre">SpaceData</span></code></a> object:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf_dat</span> <span class="o">=</span> <span class="n">cdf</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
</pre></div>
</div>
<p>Since CDF objects behave like dictionaries they have a <code class="docutils literal notranslate"><span class="pre">keys()</span></code> method and iterations are over the names in <code class="docutils literal notranslate"><span class="pre">keys()</span></code></p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf_dat</span><span class="o">.</span><span class="n">keys</span><span class="p">()</span>
<span class="go"> ['Epoch', 'data']</span>
</pre></div>
</div>
<p>Close the CDF when finished:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="modify-a-cdf">
<h3><a class="toc-backref" href="#id4" role="doc-backlink">Modify a CDF</a><a class="headerlink" href="#modify-a-cdf" title="Link to this heading">¶</a></h3>
<p>An example modifying the CDF created above:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">spacepy</span> <span class="kn">import</span> <span class="n">pycdf</span>
<span class="gp">>>> </span><span class="n">cdf</span> <span class="o">=</span> <span class="n">pycdf</span><span class="o">.</span><span class="n">CDF</span><span class="p">(</span><span class="s1">'MyCDF.cdf'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">readonly</span><span class="p">(</span><span class="kc">False</span><span class="p">)</span>
<span class="go"> False</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'newVar'</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="mf">1.0</span><span class="p">,</span> <span class="mf">2.0</span><span class="p">]</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">cdf</span><span class="p">)</span>
<span class="go"> Epoch: CDF_TIME_TT2000 [60]</span>
<span class="go"> data: CDF_FLOAT [60]</span>
<span class="go"> newVar: CDF_FLOAT [2]</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>As before, each step in this example will now be individually explained.
Existing CDF files are opened in read-only mode and must be set to read-write
before modification:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">readonly</span><span class="p">(</span><span class="kc">False</span><span class="p">)</span>
<span class="go"> False</span>
</pre></div>
</div>
<p>Then new variables can be added:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'newVar'</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="mf">1.0</span><span class="p">,</span> <span class="mf">2.0</span><span class="p">]</span>
</pre></div>
</div>
<p>Or contents can be changed:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'data'</span><span class="p">][</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="mi">8675309</span>
</pre></div>
</div>
<p>You can write all new data to an existing variable, leaving the
variable type, dimensionality, and attributes unchanged:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'Epoch'</span><span class="p">][</span><span class="o">...</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2010</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">val</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">for</span> <span class="n">val</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">60</span><span class="p">)]</span>
</pre></div>
</div>
<p>This is the common usage when using a CDF file containing all the
variables and attributes but no data, sometimes called a “master
CDF”. Although the <code class="docutils literal notranslate"><span class="pre">[...]</span></code> makes this explicit (writing new records
not a new variable), the same syntax as for a new variable can also be
used:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="c1"># Either create a new variable or overwrite data in existing</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'Epoch'</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2010</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">val</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">for</span> <span class="n">val</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">60</span><span class="p">)]</span>
</pre></div>
</div>
<p>The new variables appear immediately:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">cdf</span><span class="p">)</span>
<span class="go"> Epoch: CDF_TIME_TT2000 [60]</span>
<span class="go"> data: CDF_FLOAT [60]</span>
<span class="go"> newVar: CDF_FLOAT [2]</span>
</pre></div>
</div>
<p>Closing the CDF ensures changes are written to disk:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="non-record-varying">
<h3><a class="toc-backref" href="#id5" role="doc-backlink">Non record-varying</a><a class="headerlink" href="#non-record-varying" title="Link to this heading">¶</a></h3>
<p>Non record-varying (NRV) variables are usually used for data that does not vary
with time, such as the energy channels for an instrument.</p>
<p>NRV variables need to be created with <a class="reference internal" href="autosummary/spacepy.pycdf.CDF.html#spacepy.pycdf.CDF.new" title="spacepy.pycdf.CDF.new"><code class="xref py py-func docutils literal notranslate"><span class="pre">CDF.new()</span></code></a>, specifying the keyword ‘recVary’ as False.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">spacepy</span> <span class="kn">import</span> <span class="n">pycdf</span>
<span class="gp">>>> </span><span class="n">cdf</span> <span class="o">=</span> <span class="n">pycdf</span><span class="o">.</span><span class="n">CDF</span><span class="p">(</span><span class="s1">'MyCDF2.cdf'</span><span class="p">,</span> <span class="s1">''</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="s1">'data2'</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="n">recVary</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="go"> <Var:</span>
<span class="go"> CDF_BYTE [1] NRV</span>
<span class="go"> ></span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'data2'</span><span class="p">][</span><span class="o">...</span><span class="p">]</span>
<span class="go"> [1]</span>
</pre></div>
</div>
</section>
<section id="slicing-and-indexing">
<h3><a class="toc-backref" href="#id6" role="doc-backlink">Slicing and indexing</a><a class="headerlink" href="#slicing-and-indexing" title="Link to this heading">¶</a></h3>
<p>Subsets of data in a variable can be easily referenced with Python’s slicing
and indexing notation.</p>
<p>This example uses <a class="reference external" href="https://docs.python.org/3/library/bisect.html#module-bisect" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">bisect</span></code></a> to read a subset of the data from the
hourly data file created in earlier examples.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">spacepy</span> <span class="kn">import</span> <span class="n">pycdf</span>
<span class="gp">>>> </span><span class="n">cdf</span> <span class="o">=</span> <span class="n">pycdf</span><span class="o">.</span><span class="n">CDF</span><span class="p">(</span><span class="s1">'MyCDF.cdf'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">start</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2000</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">9</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">stop</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2000</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">35</span><span class="p">)</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">bisect</span>
<span class="gp">>>> </span><span class="n">start_ind</span> <span class="o">=</span> <span class="n">bisect</span><span class="o">.</span><span class="n">bisect_left</span><span class="p">(</span><span class="n">cdf</span><span class="p">[</span><span class="s1">'Epoch'</span><span class="p">],</span> <span class="n">start</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">stop_ind</span> <span class="o">=</span> <span class="n">bisect</span><span class="o">.</span><span class="n">bisect_left</span><span class="p">(</span><span class="n">cdf</span><span class="p">[</span><span class="s1">'Epoch'</span><span class="p">],</span> <span class="n">stop</span><span class="p">)</span>
<span class="gp">>>> </span><span class="c1"># then grab the data we want</span>
<span class="gp">>>> </span><span class="n">time</span> <span class="o">=</span> <span class="n">cdf</span><span class="p">[</span><span class="s1">'Epoch'</span><span class="p">][</span><span class="n">start_ind</span><span class="p">:</span><span class="n">stop_ind</span><span class="p">]</span>
<span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="n">cdf</span><span class="p">[</span><span class="s1">'data'</span><span class="p">][</span><span class="n">start_ind</span><span class="p">:</span><span class="n">stop_ind</span><span class="p">]</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="autosummary/spacepy.pycdf.Var.html#spacepy.pycdf.Var" title="spacepy.pycdf.Var"><code class="xref py py-class docutils literal notranslate"><span class="pre">Var</span></code></a> documentation has several additional examples.</p>
</section>
<section id="string-handling">
<span id="pycdf-string-handling"></span><h3><a class="toc-backref" href="#id7" role="doc-backlink">String handling</a><a class="headerlink" href="#string-handling" title="Link to this heading">¶</a></h3>
<blockquote>
<div><div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.3.0.</span></p>
</div>
<p>Prior to SpacePy 0.3.0, pycdf treated all strings as ASCII-encoded, and
would raise errors when writing or reading strings that were not valid
ASCII.</p>
</div></blockquote>
<p>Per the NASA CDF library, variable and attribute names must be in
ASCII. The contents of <code class="docutils literal notranslate"><span class="pre">CDF_CHAR</span></code> and <code class="docutils literal notranslate"><span class="pre">CDF_UCHAR</span></code> were redefined
to be UTF-8 as of CDF 3.8.1. As of SpacePy 0.3.0, pycdf treats all
<code class="docutils literal notranslate"><span class="pre">CHAR</span></code> variables with a default encoding of UTF-8. This is true
regardless of the version of the underlying CDF library.</p>
<p>UTF-8 is a variable-length encoding, so the number of elements in the
variable may not correspond to the number of characters if data are
not restricted to the ASCII range.</p>
<p>A different encoding can be specified with the <code class="docutils literal notranslate"><span class="pre">encoding</span></code> argument
to <code class="docutils literal notranslate"><span class="pre">spacepy.pycdf.CDF.open()</span></code> and this encoding will be used on
all reads and writes to that file. Opening a CDF read-write with
<code class="docutils literal notranslate"><span class="pre">encoding</span></code> other than <code class="docutils literal notranslate"><span class="pre">utf-8</span></code> or <code class="docutils literal notranslate"><span class="pre">ascii</span></code> will issue a warning.</p>
<p>Writing strings which cannot be represented in the desired encoding
will raise an error. When reading from a CDF, characters which cannot
be decoded will be replaced with the Unicode “replacement character”
U+FFFD, which usually displays as a question mark.</p>
<p>It is always possible to write raw bytes data to a variable, if it is
desired to use a different encoding for one time. For arrays of data,
this will usually involve <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.char.encode.html#numpy.char.encode" title="(in NumPy v2.1)"><code class="xref py py-func docutils literal notranslate"><span class="pre">numpy.char.encode()</span></code></a>:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'Variable'</span><span class="p">]</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s1">'latin-1'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">cdf</span><span class="p">[</span><span class="s1">'Variable'</span><span class="p">]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">char</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">'latin-1'</span><span class="p">)</span>
</pre></div>
</div>
<p>All encoding and decoding can also be skipped using the
<a class="reference internal" href="autosummary/spacepy.pycdf.CDF.html#spacepy.pycdf.CDF.raw_var" title="spacepy.pycdf.CDF.raw_var"><code class="xref py py-meth docutils literal notranslate"><span class="pre">raw_var()</span></code></a> method to access a variable;
however, without encoding, only <a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#bytes" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> can be written to
string variables.</p>
</section>
<section id="troubleshooting">
<h3><a class="toc-backref" href="#id8" role="doc-backlink">Troubleshooting</a><a class="headerlink" href="#troubleshooting" title="Link to this heading">¶</a></h3>
<section id="cannot-load-cdf-c-library">
<h4><a class="toc-backref" href="#id9" role="doc-backlink">Cannot load CDF C library</a><a class="headerlink" href="#cannot-load-cdf-c-library" title="Link to this heading">¶</a></h4>
<p>pycdf requires the standard NASA CDF library 3.5 or later; it can be
installed after SpacePy. Generally this is only necessary if
installing SpacePy from source. See specific instructions for
<a class="reference internal" href="install_linux.html#linux-cdf"><span class="std std-ref">Linux</span></a>, <a class="reference internal" href="install_mac.html#install-mac-cdf"><span class="std std-ref">Mac</span></a>, and
<a class="reference internal" href="install_windows.html#windows-cdf"><span class="std std-ref">Windows</span></a>.</p>
<p>The error <code class="docutils literal notranslate"><span class="pre">Cannot</span> <span class="pre">load</span> <span class="pre">CDF</span> <span class="pre">C</span> <span class="pre">library</span></code> indicates pycdf cannot find
this library. pycdf searches in locations where the library is
installed by default; if the library is not found, set the <code class="docutils literal notranslate"><span class="pre">CDF_LIB</span></code>
environment variable to the directory containing the library file
(.dll, .dylib, or .so) before importing pycdf.</p>
</section>
<section id="zlib-error-when-opening-a-cdf">
<h4><a class="toc-backref" href="#id10" role="doc-backlink">ZLIB_ERROR when opening a CDF</a><a class="headerlink" href="#zlib-error-when-opening-a-cdf" title="Link to this heading">¶</a></h4>
<p>The error message <code class="docutils literal notranslate"><span class="pre">ZLIB_ERROR:</span> <span class="pre">Error</span> <span class="pre">during</span> <span class="pre">ZLIB</span> <span class="pre">decompression</span></code> most
commonly occurs when opening a CDF which has been compressed with
whole-file compression. In this case, it must be unzipped into a
temporary location (details are in the <a class="reference external" href="https://cdf.gsfc.nasa.gov/html/cdf_docs.html">CDF User’s Guide</a>).</p>
<p>The temporary location is specified by environment variables, most
commonly <code class="docutils literal notranslate"><span class="pre">CDF_TMP</span></code>. It appears that, particularly on Windows, some
installers of the library may set this to a location which is not
writeable. In that case, the solution is to change the environment
variable to a writeable location.</p>
<p>On Windows, environment variables are set in the System Properties
control panel. Click the “Environment Variables” button on the
Advanced tab. Usually a good value for <code class="docutils literal notranslate"><span class="pre">CDF_TMP</span></code> is
<code class="docutils literal notranslate"><span class="pre">C:\Users\USERNAME\AppData\Local\Temp</span></code>. If <code class="docutils literal notranslate"><span class="pre">CDF_TMP</span></code> is not
set, variables <code class="docutils literal notranslate"><span class="pre">TMP</span></code> and <code class="docutils literal notranslate"><span class="pre">TEMP</span></code> will be used, so those values are
worth checking. Values starting with <code class="docutils literal notranslate"><span class="pre">C:\WINDOWS\system32\config</span></code>
are unlikely to work.</p>
<p>On Unix, including MacOS, <code class="docutils literal notranslate"><span class="pre">CDF_TMP</span></code> is used if set; otherwise
<code class="docutils literal notranslate"><span class="pre">TMPDIR</span></code>.</p>
</section>
</section>
<section id="access-to-cdf-constants-and-the-c-library">
<h3><a class="toc-backref" href="#id11" role="doc-backlink">Access to CDF constants and the C library</a><a class="headerlink" href="#access-to-cdf-constants-and-the-c-library" title="Link to this heading">¶</a></h3>
<p>Constants defined in cdf.h and occasionally useful in accessing CDFs are
available in the <a class="reference internal" href="autosummary/spacepy.pycdf.const.html#module-spacepy.pycdf.const" title="spacepy.pycdf.const"><code class="xref py py-mod docutils literal notranslate"><span class="pre">const</span></code></a> module.</p>
<p>The underlying C library is represented by the <a class="reference internal" href="autosummary/spacepy.pycdf.html#spacepy.pycdf.lib" title="spacepy.pycdf.lib"><code class="xref py py-attr docutils literal notranslate"><span class="pre">lib</span></code></a>
variable.</p>
</section>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/logo.png" alt="Logo"/>
</a></p>
<div>
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">pycdf - Python interface to CDF files</a><ul>
<li><a class="reference internal" href="#contents">Contents</a><ul>
<li><a class="reference internal" href="#create-a-cdf">Create a CDF</a></li>
<li><a class="reference internal" href="#read-a-cdf">Read a CDF</a></li>
<li><a class="reference internal" href="#modify-a-cdf">Modify a CDF</a></li>
<li><a class="reference internal" href="#non-record-varying">Non record-varying</a></li>
<li><a class="reference internal" href="#slicing-and-indexing">Slicing and indexing</a></li>
<li><a class="reference internal" href="#string-handling">String handling</a></li>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a><ul>
<li><a class="reference internal" href="#cannot-load-cdf-c-library">Cannot load CDF C library</a></li>
<li><a class="reference internal" href="#zlib-error-when-opening-a-cdf">ZLIB_ERROR when opening a CDF</a></li>
</ul>
</li>
<li><a class="reference internal" href="#access-to-cdf-constants-and-the-c-library">Access to CDF constants and the C library</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="pybats.html"
title="previous chapter">PyBats - SWMF & BATS-R-US Analysis Tools</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="time.html"
title="next chapter">time - Time conversion, manipulation and implementation of Ticktock class</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/pycdf.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="time.html" title="time - Time conversion, manipulation and implementation of Ticktock class"
>next</a> |</li>
<li class="right" >
<a href="pybats.html" title="PyBats - SWMF & BATS-R-US Analysis Tools"
>previous</a> |</li>
<li><a href="https://spacepy.github.io/"">homepage</a>| </li>
<li><a href="https://github.com/spacepy/spacepy">development</a>| </li>
<li><a href="search.html">search</a>| </li>
<li><a href="index.html">documentation </a> »</li>
<li class="nav-item nav-item-this"><a href="">pycdf - Python interface to CDF files</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2011-2024, The SpacePy Team.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.3.7.
</div>
</body>
</html>