-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathquickstart.html
644 lines (631 loc) · 66.6 KB
/
quickstart.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
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
<!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>SpacePy - A Quick Start Documentation — 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="SpacePy Help" href="help.html" />
<link rel="prev" title="Windows Installation" href="install_windows.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="help.html" title="SpacePy Help"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="install_windows.html" title="Windows Installation"
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="">SpacePy - A Quick Start Documentation</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="spacepy-a-quick-start-documentation">
<h1>SpacePy - A Quick Start Documentation<a class="headerlink" href="#spacepy-a-quick-start-documentation" title="Link to this heading">¶</a></h1>
<p>The SpacePy Team
(Steve Morley, Josef Koller, Dan Welling, Brian Larsen, Jon Niehof,
Mike Henderson)</p>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Link to this heading">¶</a></h2>
<p>See <a class="reference internal" href="install.html"><span class="doc">Installing SpacePy</span></a>.</p>
</section>
<section id="toolbox-a-box-full-of-tools">
<h2>Toolbox - A Box Full of Tools<a class="headerlink" href="#toolbox-a-box-full-of-tools" title="Link to this heading">¶</a></h2>
<p>Contains tools that don’t fit anywhere else but are, in general, quite
useful. The following functions are a selection of those implemented:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.windowMean" title="spacepy.toolbox.windowMean"><code class="xref py py-func docutils literal notranslate"><span class="pre">windowMean()</span></code></a>: windowing mean with variable window size and overlap</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.dictree" title="spacepy.toolbox.dictree"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictree()</span></code></a>: pretty prints the contents of dictionaries (recursively)</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.loadpickle" title="spacepy.toolbox.loadpickle"><code class="xref py py-func docutils literal notranslate"><span class="pre">loadpickle()</span></code></a>: single line convenience routine for loading Python pickles</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.savepickle" title="spacepy.toolbox.savepickle"><code class="xref py py-func docutils literal notranslate"><span class="pre">savepickle()</span></code></a>: same as loadpickle, but for saving</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.update" title="spacepy.toolbox.update"><code class="xref py py-func docutils literal notranslate"><span class="pre">update()</span></code></a>: updates the OMNI database and the leap seconds database (internet connection required)</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.tOverlap" title="spacepy.toolbox.tOverlap"><code class="xref py py-func docutils literal notranslate"><span class="pre">tOverlap()</span></code></a>: find interval of overlap between two time series</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.tCommon" title="spacepy.toolbox.tCommon"><code class="xref py py-func docutils literal notranslate"><span class="pre">tCommon()</span></code></a>: find times common to two time series</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.binHisto" title="spacepy.toolbox.binHisto"><code class="xref py py-func docutils literal notranslate"><span class="pre">binHisto()</span></code></a>: calculate number of bins for a histogram</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.medAbsDev" title="spacepy.toolbox.medAbsDev"><code class="xref py py-func docutils literal notranslate"><span class="pre">medAbsDev()</span></code></a>: find the median absolute deviation of a data series</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.normalize" title="spacepy.toolbox.normalize"><code class="xref py py-func docutils literal notranslate"><span class="pre">normalize()</span></code></a>: normalize a data series</p></li>
</ul>
</div></blockquote>
<p>Import this module as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.toolbox</span> <span class="k">as</span> <span class="nn">tb</span>
</pre></div>
</div>
<p>Examples:</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">spacepy.toolbox</span> <span class="k">as</span> <span class="nn">tb</span>
<span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'entry1'</span><span class="p">:</span><span class="s1">'val1'</span><span class="p">,</span> <span class="s1">'entry2'</span><span class="p">:</span><span class="mi">2</span><span class="p">,</span> <span class="s1">'recurse1'</span><span class="p">:{</span><span class="s1">'one'</span><span class="p">:</span><span class="mi">1</span><span class="p">,</span> <span class="s1">'two'</span><span class="p">:</span><span class="mi">2</span><span class="p">}}</span>
<span class="gp">>>> </span><span class="n">tb</span><span class="o">.</span><span class="n">dictree</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="go">+</span>
<span class="go">|____entry1</span>
<span class="go">|____entry2</span>
<span class="go">|____recurse1</span>
<span class="go"> |____one</span>
<span class="go"> |____two</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">dat</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="mi">100</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">tb</span><span class="o">.</span><span class="n">binHisto</span><span class="p">(</span><span class="n">dat</span><span class="p">)</span>
<span class="go">(0.19151723370512266, 5.0)</span>
</pre></div>
</div>
</section>
<section id="time-and-coordinate-transformations">
<h2>Time and Coordinate Transformations<a class="headerlink" href="#time-and-coordinate-transformations" title="Link to this heading">¶</a></h2>
<p>Import the modules as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.time</span> <span class="k">as</span> <span class="nn">spt</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.coords</span> <span class="k">as</span> <span class="nn">spc</span>
</pre></div>
</div>
<section id="ticktock-class">
<h3>Ticktock Class<a class="headerlink" href="#ticktock-class" title="Link to this heading">¶</a></h3>
<p>The Ticktock class provides a number of time conversion routines and is
implemented as a container class built on the functionality of the Python
datetime module. The following time coordinates are provided</p>
<blockquote>
<div><ul class="simple">
<li><p>UTC: Coordinated Universal Time implemented as a <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.datetime</span></code></a></p></li>
<li><p>ISO: standard ISO 8601 format like <code class="docutils literal notranslate"><span class="pre">2002-10-25T14:33:59</span></code></p></li>
<li><p>TAI: International Atomic Time in units of seconds since Jan 1, 1958 (midnight) and includes leap seconds, i.e. every second has the same length</p></li>
<li><p>JD: Julian Day</p></li>
<li><p>MJD: Modified Julian Day</p></li>
<li><p>UNX: UNIX time in seconds since Jan 1, 1970</p></li>
<li><p>RDT: Rata Die Time (Gregorian Ordinal Time) in days since Jan 1, 1 AD midnight</p></li>
<li><p>CDF: CDF Epoch time in milliseconds since Jan 1, year 0</p></li>
<li><p>DOY: Day of Year including fractions</p></li>
<li><p>leaps: Leap seconds according to <a class="reference external" href="ftp://maia.usno.navy.mil/ser7/tai-utc.dat">ftp://maia.usno.navy.mil/ser7/tai-utc.dat</a></p></li>
</ul>
</div></blockquote>
<p>To access these time coordinates, you’ll create an instance of a
Ticktock class, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">t</span> <span class="o">=</span> <span class="n">spt</span><span class="o">.</span><span class="n">Ticktock</span><span class="p">(</span><span class="s1">'2002-10-25T12:30:00'</span><span class="p">,</span> <span class="s1">'ISO'</span><span class="p">)</span>
</pre></div>
</div>
<p>Instead of ISO you may use any of the formats listed above. You can also
use numpy arrays or lists of time points. <code class="docutils literal notranslate"><span class="pre">t</span></code> has now the class
attributes:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">t</span><span class="o">.</span><span class="n">dtype</span> <span class="o">=</span> <span class="s1">'ISO'</span>
<span class="gp">>>> </span><span class="n">t</span><span class="o">.</span><span class="n">data</span> <span class="o">=</span> <span class="s1">'2002-10-25T12:30:00'</span>
</pre></div>
</div>
<p>FYI <code class="docutils literal notranslate"><span class="pre">t.UTC</span></code> is added automatically.</p>
<p>If you want to convert/add a class attribute from the list above,
simply type e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">t</span><span class="o">.</span><span class="n">RTD</span>
</pre></div>
</div>
<p>You can replace RTD with any from the list above.</p>
<p>You can find out how many leap seconds were used by issuing the command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">t</span><span class="o">.</span><span class="n">getleapsecs</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="timedelta-class">
<h3>Timedelta Class<a class="headerlink" href="#timedelta-class" title="Link to this heading">¶</a></h3>
<p>You can add/subtract time from a Ticktock class instance by using an
instance of <a class="reference external" href="https://docs.python.org/3/library/datetime.html#datetime.timedelta" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.timedelta</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dt</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mf">2.3</span><span class="p">)</span>
</pre></div>
</div>
<p>Then you can add by e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">t</span><span class="o">+</span><span class="n">dt</span>
</pre></div>
</div>
</section>
<section id="coords-class">
<h3>Coords Class<a class="headerlink" href="#coords-class" title="Link to this heading">¶</a></h3>
<p>The spatial coordinate class includes the following coordinate systems in
Cartesian and spherical forms.</p>
<blockquote>
<div><ul class="simple">
<li><p>GZD: (altitude, latitude, longitude) in km, deg, deg</p></li>
<li><p>GEO: cartesian, Re</p></li>
<li><p>GSM: cartesian, Re</p></li>
<li><p>GSE: cartesian, Re</p></li>
<li><p>SM: cartesian, Re</p></li>
<li><p>GEI: cartesian, Re</p></li>
<li><p>MAG: cartesian, Re</p></li>
<li><p>SPH: same as GEO but in spherical</p></li>
<li><p>RLL: radial distance, latitude, longitude, Re, deg, deg.</p></li>
</ul>
</div></blockquote>
<p>Create a Coords instance with spherical=’sph’ or cartesian=’car’
coordinates:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">spaco</span> <span class="o">=</span> <span class="n">spc</span><span class="o">.</span><span class="n">Coords</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">4</span><span class="p">],[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">]],</span> <span class="s1">'GEO'</span><span class="p">,</span> <span class="s1">'car'</span><span class="p">)</span>
</pre></div>
</div>
<p>This will let you request, for example, all y-coordinates by <code class="docutils literal notranslate"><span class="pre">spaco.y</span></code>
or if given in spherical coordinates by <code class="docutils literal notranslate"><span class="pre">spaco.lati</span></code>. One can transform
the coordinates by <code class="docutils literal notranslate"><span class="pre">newcoord</span> <span class="pre">=</span> <span class="pre">spaco.convert('GSM',</span> <span class="pre">'sph')</span></code>.
This will return GSM coordinates in a spherical system. Since GSM
coordinates depend on time, you’ll have to add first a Ticktock
vector with the name <code class="docutils literal notranslate"><span class="pre">ticks</span></code> like <code class="docutils literal notranslate"><span class="pre">spaco.ticks</span> <span class="pre">=</span> <span class="pre">spt.Ticktock(['2002-02-02T12:00:00',</span>
<span class="pre">'2002-02-02T12:00:00'],</span> <span class="pre">'ISO')</span></code></p>
<p>Unit conversion will be implemented in the future.</p>
</section>
</section>
<section id="omni-module">
<h2>OMNI Module<a class="headerlink" href="#omni-module" title="Link to this heading">¶</a></h2>
<p>The OMNI database is an hourly resolution, multi-source data set
with coverage from November 1963; higher temporal resolution versions of
the OMNI database exist, but with coverage from 1995. The primary data are
near-Earth solar wind, magnetic field and plasma parameters. However, a
number of modern magnetic field models require derived input parameters,
and Qin and Denton (2007) have used the publicly-available OMNI database to provide
a modified version of this database containing all parameters necessary
for these magnetic field models. These data are available through ViRBO - the Virtual
Radiation Belt Observatory.</p>
<p>In SpacePy this data is made available, at 1-hourly resolution, on request
on first import; if not downloaded when SpacePy is first used then any
attempt to import the omni module will
ask the user whether they wish to download the data. Should the user
require the latest data, the toolbox.update function can
be used to fetch the latest files from ViRBO.</p>
<p>The following example fetches the OMNI data for the storms of
October and November, 2003.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.time</span> <span class="k">as</span> <span class="nn">spt</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.omni</span> <span class="k">as</span> <span class="nn">om</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">datetime</span> <span class="k">as</span> <span class="nn">dt</span>
<span class="gp">>>> </span><span class="n">st</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2003</span><span class="p">,</span><span class="mi">10</span><span class="p">,</span><span class="mi">20</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">en</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2003</span><span class="p">,</span><span class="mi">12</span><span class="p">,</span><span class="mi">5</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">delta</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">ticks</span> <span class="o">=</span> <span class="n">spt</span><span class="o">.</span><span class="n">tickrange</span><span class="p">(</span><span class="n">st</span><span class="p">,</span> <span class="n">en</span><span class="p">,</span> <span class="n">delta</span><span class="p">,</span> <span class="s1">'UTC'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="n">om</span><span class="o">.</span><span class="n">get_omni</span><span class="p">(</span><span class="n">ticks</span><span class="p">)</span>
</pre></div>
</div>
<p><em>data</em> is a dictionary containing all the OMNI data, by variable, for the timestamps
contained within the <code class="docutils literal notranslate"><span class="pre">Ticktock</span></code> object <em>ticks</em>. Now it is simple to plot Dst values
for instance:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">pyplot</span> <span class="k">as</span> <span class="nn">p</span>
<span class="gp">>>> </span><span class="n">p</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">ticks</span><span class="o">.</span><span class="n">eDOY</span><span class="p">,</span> <span class="n">data</span><span class="p">[</span><span class="s1">'Dst'</span><span class="p">])</span>
</pre></div>
</div>
</section>
<section id="the-irbempy-module">
<h2>The irbempy Module<a class="headerlink" href="#the-irbempy-module" title="Link to this heading">¶</a></h2>
<p>ONERA (Office National d’Etudes et Recherches Aerospatiales) initiated a
well-known FORTRAN library that provides routines to compute magnetic
coordinates for any location in the Earth’s magnetic field, to perform
coordinate conversions, to compute magnetic field vectors in geospace for
a number of external field models, and to propagate satellite orbits in
time. Older versions of this library were called ONERA-DESP-LIB. Recently
the library has changed its name to IRBEM-LIB and is maintained by a number
of different institutions.</p>
<p>A number of key routines in IRBEM-LIB have been made available through the
module <a class="reference internal" href="autosummary/spacepy.irbempy.html#module-spacepy.irbempy" title="spacepy.irbempy"><code class="xref py py-mod docutils literal notranslate"><span class="pre">irbempy</span></code></a>. Current functionality includes calls to calculate the local
magnetic field vectors at any point in geospace, calculation of the magnetic
mirror point for a particle of a given pitch angle (the angle between a
particle’s velocity vector and the magnetic field line that it immediately
orbits such that a pitch angle of 90 degrees signifies gyration perpendicular
to the local field) anywhere in geospace, and calculation of electron drift
shells in the inner magnetosphere.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.time</span> <span class="k">as</span> <span class="nn">spt</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.coordinates</span> <span class="k">as</span> <span class="nn">spc</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.irbempy</span> <span class="k">as</span> <span class="nn">ib</span>
<span class="gp">>>> </span><span class="n">t</span> <span class="o">=</span> <span class="n">spt</span><span class="o">.</span><span class="n">Ticktock</span><span class="p">([</span><span class="s1">'2002-02-02T12:00:00'</span><span class="p">,</span> <span class="s1">'2002-02-02T12:10:00'</span><span class="p">],</span> <span class="s1">'ISO'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">y</span> <span class="o">=</span> <span class="n">spc</span><span class="o">.</span><span class="n">Coords</span><span class="p">([[</span><span class="mi">3</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">],[</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">]],</span> <span class="s1">'GEO'</span><span class="p">,</span> <span class="s1">'car'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">ib</span><span class="o">.</span><span class="n">get_Bfield</span><span class="p">(</span><span class="n">t</span><span class="p">,</span><span class="n">y</span><span class="p">)</span>
<span class="gp">>>> </span><span class="c1"># {'Blocal': array([ 976.42565251, 3396.25991675]),</span>
<span class="gp">>>> </span><span class="c1"># 'Bvec': array([[ -5.01738885e-01, -1.65104338e+02, 9.62365503e+02], [ 3.33497974e+02, -5.42111173e+02, 3.33608693e+03]])}</span>
</pre></div>
</div>
<p>One can also calculate the drift shell L* for a 90 degree pitch angle value by using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ib</span><span class="o">.</span><span class="n">get_Lstar</span><span class="p">(</span><span class="n">t</span><span class="p">,</span><span class="n">y</span><span class="p">,</span> <span class="p">[</span><span class="mi">90</span><span class="p">])</span>
<span class="gp">>>> </span><span class="c1"># {'Bmin': array([ 975.59122652, 3388.2476667 ]),</span>
<span class="gp">>>> </span><span class="c1"># 'Bmirr': array([[ 976.42565251], [ 3396.25991675]]),</span>
<span class="gp">>>> </span><span class="c1"># 'Lm': array([[ 3.13508015], [ 2.07013638]]),</span>
<span class="gp">>>> </span><span class="c1"># 'Lstar': array([[ 2.86958324], [ 1.95259007]]),</span>
<span class="gp">>>> </span><span class="c1"># 'MLT': array([ 11.97222034, 12.13378624]),</span>
<span class="gp">>>> </span><span class="c1"># 'Xj': array([[ 0.00081949], [ 0.00270321]])}</span>
</pre></div>
</div>
<p>Other function wrapped with the IRBEM library include:</p>
<ul class="simple">
<li><p><a class="reference internal" href="autosummary/spacepy.irbempy.html#spacepy.irbempy.find_Bmirror" title="spacepy.irbempy.find_Bmirror"><code class="xref py py-func docutils literal notranslate"><span class="pre">find_Bmirror()</span></code></a></p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.irbempy.html#spacepy.irbempy.find_magequator" title="spacepy.irbempy.find_magequator"><code class="xref py py-func docutils literal notranslate"><span class="pre">find_magequator()</span></code></a></p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.irbempy.html#spacepy.irbempy.coord_trans" title="spacepy.irbempy.coord_trans"><code class="xref py py-func docutils literal notranslate"><span class="pre">coord_trans()</span></code></a></p></li>
</ul>
</section>
<section id="pycdf-python-access-to-nasa-cdf-library">
<h2>pyCDF - Python Access to NASA CDF Library<a class="headerlink" href="#pycdf-python-access-to-nasa-cdf-library" title="Link to this heading">¶</a></h2>
<p>pycdf provides a “pythonic” interface to the NASA CDF library. It requires
that the NASA CDF C-library is properly installed.
The module can then be imported, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.pycdf</span> <span class="k">as</span> <span class="nn">cdf</span>
</pre></div>
</div>
<p>To open and close a CDF file, we use the <a class="reference internal" href="autosummary/spacepy.pycdf.CDF.html#spacepy.pycdf.CDF" title="spacepy.pycdf.CDF"><code class="xref py py-class docutils literal notranslate"><span class="pre">CDF</span></code></a> class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cdf_file</span> <span class="o">=</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="gp">>>> </span><span class="n">cdf_file</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="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="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>
<p>CDF files act as Python dictionaries, holding CDF variables keyed
by the variable name:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">var_names</span> <span class="o">=</span> <span class="n">keys</span><span class="p">(</span><span class="n">cdf_file</span><span class="p">)</span> <span class="c1">#list of all variables</span>
<span class="gp">>>> </span><span class="k">for</span> <span class="n">var_name</span> <span class="ow">in</span> <span class="n">cdf_file</span><span class="p">:</span>
<span class="gp">>>> </span> <span class="nb">print</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">cdf_file</span><span class="p">[</span><span class="n">var_name</span><span class="p">]))</span> <span class="c1">#number of records in each variable</span>
<span class="gp">>>> </span><span class="c1">#list comprehensions work, too</span>
<span class="gp">>>> </span><span class="n">lengths</span> <span class="o">=</span> <span class="p">[</span><span class="nb">len</span><span class="p">(</span><span class="n">cdf_file</span><span class="p">[</span><span class="n">var_name</span><span class="p">])</span> <span class="k">for</span> <span class="n">var_name</span> <span class="ow">in</span> <span class="n">cdf_file</span><span class="p">]</span>
</pre></div>
</div>
<p>Each CDF variable acts like a numpy array, where the first dimension is the
record number. Multidimensional CDF variables can be subscripted using
numpy’s multidimensional slice notation. Many common list operations are also
implemented, where each record acts as one element of the list and can be
independently deleted, inserted, etc. Creating a Python <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>
object does not read the data from disc; data are only read as they are
accessed:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">epoch</span> <span class="o">=</span> <span class="n">cdf_file</span><span class="p">[</span><span class="s1">'Epoch'</span><span class="p">]</span> <span class="c1">#Python object created, nothing read from disc</span>
<span class="gp">>>> </span><span class="n">epoch</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="c1">#time of first record in CDF (datetime object)</span>
<span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">epoch</span><span class="p">[</span><span class="o">...</span><span class="p">]</span> <span class="c1">#copy all times to list a</span>
<span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">epoch</span><span class="p">[</span><span class="o">-</span><span class="mi">5</span><span class="p">:]</span> <span class="c1">#copy last five times to list a</span>
<span class="gp">>>> </span><span class="n">b_gse</span> <span class="o">=</span> <span class="n">cdf_file</span><span class="p">[</span><span class="s1">'B_GSE'</span><span class="p">]</span> <span class="c1">#B_GSE is a 1D, three-element array</span>
<span class="gp">>>> </span><span class="n">bz</span> <span class="o">=</span> <span class="n">b_gse</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">]</span> <span class="c1">#Z component of first record</span>
<span class="gp">>>> </span><span class="n">bx</span> <span class="o">=</span> <span class="n">b_gse</span><span class="p">[:,</span><span class="mi">0</span><span class="p">]</span> <span class="c1">#copy X component of all records to bx</span>
<span class="gp">>>> </span><span class="n">bx</span> <span class="o">=</span> <span class="n">cdf_file</span><span class="p">[</span><span class="s1">'B_GSE'</span><span class="p">][:,</span><span class="mi">0</span><span class="p">]</span> <span class="c1">#same as above</span>
</pre></div>
</div>
</section>
<section id="the-datamodel-module">
<h2>The datamodel Module<a class="headerlink" href="#the-datamodel-module" title="Link to this heading">¶</a></h2>
<p>The SpacePy datamodel module implements classes that are designed to make implementing a standard
data model easy. The concepts are very similar to those used in standards like HDF5, netCDF and
NASA CDF.</p>
<p>The basic container type is analogous to a folder (on a filesystem; HDF5 calls this a
group): Here we implement this as a dictionary-like object, 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, which
also carries attributes. These attributes can be considered to be global, i.e. relevant for the
entire folder. The next container type is for storing data and is based on a numpy array, this
class is <a class="reference internal" href="autosummary/spacepy.datamodel.dmarray.html#spacepy.datamodel.dmarray" title="spacepy.datamodel.dmarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">dmarray</span></code></a> and also carries attributes. The dmarray class is analogous to an
HDF5 dataset.</p>
<section id="guide-for-nasa-cdf-users">
<h3>Guide for NASA CDF users<a class="headerlink" href="#guide-for-nasa-cdf-users" title="Link to this heading">¶</a></h3>
<p>By definition, a NASA CDF only has a single ‘layer’. That is, a CDF contains a series of records
(stored variables of various types) and a set of attributes that are either global or local in
scope. Thus to use SpacePy’s datamodel to capture the functionality of CDF the two basic data types
are all that is required, and the main constraint is that datamodel.SpaceData objects cannot be
nested (more on this later, if conversion from a nested datamodel to a flat datamodel is required).</p>
<p>This is best illustrated with an example. Imagine representing some satellite data within a CDF –
the global attributes might be the mission name and the instrument PI, the variables might be the
instrument counts [n-dimensional array], timestamps[1-dimensional array and an orbit number [scalar].
Each variable will have one attribute (for this example).</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">spacepy.datamodel</span> <span class="k">as</span> <span class="nn">dm</span>
<span class="gp">>>> </span><span class="n">mydata</span> <span class="o">=</span> <span class="n">dm</span><span class="o">.</span><span class="n">SpaceData</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">'MissionName'</span><span class="p">:</span> <span class="s1">'BigSat1'</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">mydata</span><span class="p">[</span><span class="s1">'Counts'</span><span class="p">]</span> <span class="o">=</span> <span class="n">dm</span><span class="o">.</span><span class="n">dmarray</span><span class="p">([[</span><span class="mi">42</span><span class="p">,</span> <span class="mi">69</span><span class="p">,</span> <span class="mi">77</span><span class="p">],</span> <span class="p">[</span><span class="mi">100</span><span class="p">,</span> <span class="mi">200</span><span class="p">,</span> <span class="mi">250</span><span class="p">]],</span> <span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">'Units'</span><span class="p">:</span> <span class="s1">'cnts/s'</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">mydata</span><span class="p">[</span><span class="s1">'Epoch'</span><span class="p">]</span> <span class="o">=</span> <span class="n">dm</span><span class="o">.</span><span class="n">dmarray</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">'units'</span><span class="p">:</span> <span class="s1">'minutes'</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">mydata</span><span class="p">[</span><span class="s1">'OrbitNumber'</span><span class="p">]</span> <span class="o">=</span> <span class="n">dm</span><span class="o">.</span><span class="n">dmarray</span><span class="p">(</span><span class="mi">16</span><span class="p">,</span> <span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">'StartsFrom'</span><span class="p">:</span> <span class="mi">1</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">attrs</span><span class="p">[</span><span class="s1">'PI'</span><span class="p">]</span> <span class="s1">'Prof. Big Shot'</span>
</pre></div>
</div>
<p>This has now populated a structure that can map directly to a NASA CDF. To visualize our datamodel,
we can use the <a class="reference internal" href="autosummary/spacepy.datamodel.SpaceData.html#spacepy.datamodel.SpaceData.tree" title="spacepy.datamodel.SpaceData.tree"><code class="xref py py-meth docutils literal notranslate"><span class="pre">tree()</span></code></a> method, which is equivalent to <a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.dictree" title="spacepy.toolbox.dictree"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictree()</span></code></a>
(which works for any dictionary-like object, including PyCDF file objects).</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">tree</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">+</span>
<span class="go">:|____MissionName</span>
<span class="go">:|____PI</span>
<span class="go">|____Counts</span>
<span class="go"> :|____Units</span>
<span class="go">|____Epoch</span>
<span class="go"> :|____units</span>
<span class="go">|____OrbitNumber</span>
<span class="go"> :|____StartsFrom</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.toolbox</span> <span class="k">as</span> <span class="nn">tb</span>
<span class="gp">>>> </span><span class="n">tb</span><span class="o">.</span><span class="n">dictree</span><span class="p">(</span><span class="n">mydata</span><span class="p">,</span> <span class="n">attrs</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">+</span>
<span class="go">:|____MissionName</span>
<span class="go">:|____PI</span>
<span class="go">|____Counts</span>
<span class="go"> :|____Units</span>
<span class="go">|____Epoch</span>
<span class="go"> :|____units</span>
<span class="go">|____OrbitNumber</span>
<span class="go"> :|____StartsFrom</span>
</pre></div>
</div>
<p>Attributes are denoted by a leading colon. The global attributes are those in the base level,
and the local attributes are attached to each variable.</p>
<p>If we have data that has nested ‘folders’, allowed by HDF5 but not by NASA CDF, then how can this be
represented such that the data structure can be mapped directly to a NASA CDF? The data will need to
be flattened so that it is single layered. Let us now store some ephemerides in our data structure:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mydata</span><span class="p">[</span><span class="s1">'Ephemeris'</span><span class="p">]</span> <span class="o">=</span> <span class="n">dm</span><span class="o">.</span><span class="n">SpaceData</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">mydata</span><span class="p">[</span><span class="s1">'Ephemeris'</span><span class="p">][</span><span class="s1">'GSM'</span><span class="p">]</span> <span class="o">=</span> <span class="n">dm</span><span class="o">.</span><span class="n">dmarray</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">3</span><span class="p">],</span> <span class="p">[</span><span class="mf">1.2</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mf">2.5</span><span class="p">],</span> <span class="p">[</span><span class="mf">1.4</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mf">1.9</span><span class="p">]])</span>
<span class="gp">>>> </span><span class="n">tb</span><span class="o">.</span><span class="n">dictree</span><span class="p">(</span><span class="n">mydata</span><span class="p">,</span> <span class="n">attrs</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">+</span>
<span class="go">:|____MissionName</span>
<span class="go">:|____PI</span>
<span class="go">|____Counts</span>
<span class="go"> :|____Units</span>
<span class="go">|____Ephemeris</span>
<span class="go"> |____GSM</span>
<span class="go">|____Epoch</span>
<span class="go"> :|____units</span>
<span class="go">|____OrbitNumber</span>
<span class="go"> :|____StartsFrom</span>
</pre></div>
</div>
<p>Nested dictionary-like objects is not uncommon in Python (and can be exceptionally useful for representing
data, so to make this compatible with NASA CDF we call the <a class="reference internal" href="autosummary/spacepy.datamodel.SpaceData.html#spacepy.datamodel.SpaceData.flatten" title="spacepy.datamodel.SpaceData.flatten"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flatten()</span></code></a> method .</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">flatten</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">tb</span><span class="o">.</span><span class="n">dictree</span><span class="p">(</span><span class="n">mydata</span><span class="p">,</span> <span class="n">attrs</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">+</span>
<span class="go">:|____MissionName</span>
<span class="go">:|____PI</span>
<span class="go">|____Counts</span>
<span class="go"> :|____Units</span>
<span class="go">|____Ephemeris<--GSM</span>
<span class="go">|____Epoch</span>
<span class="go"> :|____units</span>
<span class="go">|____OrbitNumber</span>
<span class="go"> :|____StartsFrom</span>
</pre></div>
</div>
<p>Note that the nested SpaceData has been moved to a variable with a new name reflecting its origin. The
data structure is now flat again and can be mapped directly to NASA CDF.</p>
</section>
<section id="converters-to-from-datamodel">
<h3>Converters to/from datamodel<a class="headerlink" href="#converters-to-from-datamodel" title="Link to this heading">¶</a></h3>
<p>Currently converters exist to read HDF5 and NASA CDF files directly to a SpacePy datamodel. This capability
also exists for JSON-headed ASCII files (RBSP/AutoPlot-compatible). A converter from the datamodel to HDF5
is now available and a converter to NASA CDF is under development. Also under development is the reverse of
the SpaceData.flatten method, so that flattened objects can be restored to their former glory.</p>
</section>
</section>
<section id="empiricals-module">
<h2>Empiricals Module<a class="headerlink" href="#empiricals-module" title="Link to this heading">¶</a></h2>
<p>The empiricals module provides access to some useful empirical models.
As of SpacePy 0.1.2, the models available are:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference internal" href="autosummary/spacepy.empiricals.html#spacepy.empiricals.getLmax" title="spacepy.empiricals.getLmax"><code class="xref py py-func docutils literal notranslate"><span class="pre">getLmax()</span></code></a> An empirical parametrization of the L* of the last closed drift shell
(Lmax)</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.empiricals.html#spacepy.empiricals.getPlasmaPause" title="spacepy.empiricals.getPlasmaPause"><code class="xref py py-func docutils literal notranslate"><span class="pre">getPlasmaPause()</span></code></a> The plasmapause location, following either Carpenter and Anderson
(1992) or Moldwin et al. (2002)</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.empiricals.html#spacepy.empiricals.getMPstandoff" title="spacepy.empiricals.getMPstandoff"><code class="xref py py-func docutils literal notranslate"><span class="pre">getMPstandoff()</span></code></a> The magnetopause standoff location (i.e. the sub-solar point), using
the Shue et al. (1997) model</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.empiricals.html#spacepy.empiricals.vampolaPA" title="spacepy.empiricals.vampolaPA"><code class="xref py py-func docutils literal notranslate"><span class="pre">vampolaPA()</span></code></a> A conversion of omnidirectional electron flux to pitch-angle dependent
flux, using the sin <sup>n</sup> model of Vampola (1996)</p></li>
</ul>
</div></blockquote>
<p>Each of the first three models is called by passing it a Ticktock object (see above) which then
calculates the model output using the 1-hour Qin-Denton OMNI data (from the
OMNI module; see above). For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.time</span> <span class="k">as</span> <span class="nn">spt</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.empiricals</span> <span class="k">as</span> <span class="nn">emp</span>
<span class="gp">>>> </span><span class="n">ticks</span> <span class="o">=</span> <span class="n">spt</span><span class="o">.</span><span class="n">tickrange</span><span class="p">(</span><span class="s1">'2002-01-01T12:00:00'</span><span class="p">,</span><span class="s1">'2002-01-04T00:00:00'</span><span class="p">,</span><span class="mf">.25</span><span class="p">)</span>
</pre></div>
</div>
<p>calls <a class="reference internal" href="autosummary/spacepy.time.html#spacepy.time.tickrange" title="spacepy.time.tickrange"><code class="xref py py-func docutils literal notranslate"><span class="pre">tickrange()</span></code></a> and makes a Ticktock object
with times from midday on January 1st 2002 to midnight January 4th 2002,
incremented 6-hourly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Lpp</span> <span class="o">=</span> <span class="n">emp</span><span class="o">.</span><span class="n">getPlasmaPause</span><span class="p">(</span><span class="n">ticks</span><span class="p">)</span>
</pre></div>
</div>
<p>then returns the model plasmapause location using the default setting of the
Moldwin et al. (2002) model. The Carpenter and Anderson model can be used by
setting the Lpp_model keyword to ‘CA1992’.</p>
<p>The magnetopause standoff location can be called using this syntax, or can be
called for specific solar wind parameters (ram pressure, P, and IMF Bz) passed
through in a Python dictionary:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'P'</span><span class="p">:</span> <span class="p">[</span><span class="mi">2</span><span class="p">,</span><span class="mi">4</span><span class="p">],</span> <span class="s1">'Bz'</span><span class="p">:</span> <span class="p">[</span><span class="o">-</span><span class="mf">2.4</span><span class="p">,</span> <span class="o">-</span><span class="mf">2.4</span><span class="p">]}</span>
<span class="gp">>>> </span><span class="n">emp</span><span class="o">.</span><span class="n">getMPstandoff</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">>>> </span> <span class="c1"># array([ 10.29156018, 8.96790412])</span>
</pre></div>
</div>
</section>
<section id="seapy-superposed-epoch-analysis-in-python">
<h2>SeaPy - Superposed Epoch Analysis in Python<a class="headerlink" href="#seapy-superposed-epoch-analysis-in-python" title="Link to this heading">¶</a></h2>
<p>Superposed epoch analysis is a technique used to reveal consistent responses,
relative to some repeatable phenomenon, in noisy data . Time series of the variables
under investigation are extracted from a window around the epoch and all data
at a given time relative to epoch forms the sample of events at that lag. The
data at each time lag are then averaged so that fluctuations not
consistent about the epoch cancel. In many superposed epoch analyses the mean of
the data at each time <em>u</em> relative to epoch, is used to
represent the central tendency. In SeaPy we calculate both the mean and the median,
since the median is a more robust measure of central tendency and is less affected
by departures from normality. SeaPy also calculates a measure of spread at each time
relative to epoch when performing the superposed epoch analysis; the interquartile
range is the default, but the median absolute deviation and bootstrapped confidence
intervals of the median (or mean) are also available.</p>
<p>As an example we fetch OMNI data for 4 years and perform a superposed epoch analysis
of the solar wind radial velocity, with a set of epoch times read from a text file:</p>
<div class="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="k">as</span> <span class="nn">dt</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.seapy</span> <span class="k">as</span> <span class="nn">sea</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.omni</span> <span class="k">as</span> <span class="nn">om</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.toolbox</span> <span class="k">as</span> <span class="nn">tb</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.time</span> <span class="k">as</span> <span class="nn">spt</span>
<span class="gp">>>> </span><span class="c1"># now read the epochs for the analysis (the path specified is the default</span>
<span class="gp">>>> </span><span class="c1"># install location on linux, different OS will have this elsewhere)</span>
<span class="gp">>>> </span><span class="n">epochs</span> <span class="o">=</span> <span class="n">sea</span><span class="o">.</span><span class="n">readepochs</span><span class="p">(</span><span class="s1">'~/.local/lib/python2.7/site-packages/spacepy/data/SEA_epochs_OMNI.txt'</span><span class="p">)</span>
</pre></div>
</div>
<p>The readepochs function can handle multiple formats by a user-specified format code.
ISO 8601 format is directly supported though it is not used here. The the readepochs docstring
for more information. As above, we use the get_omni function to retrieve the hourly data
from the OMNI module:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ticks</span> <span class="o">=</span> <span class="n">spt</span><span class="o">.</span><span class="n">tickrange</span><span class="p">(</span><span class="n">dt</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2005</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">dt</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2009</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">dt</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">1</span><span class="p">))</span>
<span class="gp">>>> </span><span class="n">omni1hr</span> <span class="o">=</span> <span class="n">om</span><span class="o">.</span><span class="n">get_omni</span><span class="p">(</span><span class="n">ticks</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">omni1hr</span><span class="o">.</span><span class="n">tree</span><span class="p">(</span><span class="n">levels</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">+</span>
<span class="o">|</span><span class="n">____ByIMF</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Bz1</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Bz2</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Bz3</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Bz4</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Bz5</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Bz6</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____BzIMF</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____DOY</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Dst</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____G</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,</span> <span class="mi">3</span><span class="p">))</span>
<span class="o">|</span><span class="n">____Hr</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Kp</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Pdyn</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Qbits</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">SpaceData</span> <span class="p">[</span><span class="mi">7</span><span class="p">])</span>
<span class="o">|</span><span class="n">____RDT</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____UTC</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____W</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,</span> <span class="mi">6</span><span class="p">))</span>
<span class="o">|</span><span class="n">____Year</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____akp3</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____dens</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
</pre></div>
</div>
<p>and these data are used for the superposed epoch analysis.
the temporal resolution is 1 hr and the window is +/- 3 days</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">delta</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">window</span><span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">sevx</span> <span class="o">=</span> <span class="n">sea</span><span class="o">.</span><span class="n">Sea</span><span class="p">(</span><span class="n">omni1hr</span><span class="p">[</span><span class="s1">'velo'</span><span class="p">],</span> <span class="n">omni1hr</span><span class="p">[</span><span class="s1">'UTC'</span><span class="p">],</span> <span class="n">epochs</span><span class="p">,</span> <span class="n">window</span><span class="p">,</span> <span class="n">delta</span><span class="p">)</span>
<span class="go"> #rather than quartiles, we calculate the 95% confidence interval on the median</span>
<span class="gp">>>> </span><span class="n">sevx</span><span class="o">.</span><span class="n">sea</span><span class="p">(</span><span class="n">ci</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">sevx</span><span class="o">.</span><span class="n">plot</span><span class="p">()</span>
</pre></div>
</div>
</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="#">SpacePy - A Quick Start Documentation</a><ul>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#toolbox-a-box-full-of-tools">Toolbox - A Box Full of Tools</a></li>
<li><a class="reference internal" href="#time-and-coordinate-transformations">Time and Coordinate Transformations</a><ul>
<li><a class="reference internal" href="#ticktock-class">Ticktock Class</a></li>
<li><a class="reference internal" href="#timedelta-class">Timedelta Class</a></li>
<li><a class="reference internal" href="#coords-class">Coords Class</a></li>
</ul>
</li>
<li><a class="reference internal" href="#omni-module">OMNI Module</a></li>
<li><a class="reference internal" href="#the-irbempy-module">The irbempy Module</a></li>
<li><a class="reference internal" href="#pycdf-python-access-to-nasa-cdf-library">pyCDF - Python Access to NASA CDF Library</a></li>
<li><a class="reference internal" href="#the-datamodel-module">The datamodel Module</a><ul>
<li><a class="reference internal" href="#guide-for-nasa-cdf-users">Guide for NASA CDF users</a></li>
<li><a class="reference internal" href="#converters-to-from-datamodel">Converters to/from datamodel</a></li>
</ul>
</li>
<li><a class="reference internal" href="#empiricals-module">Empiricals Module</a></li>
<li><a class="reference internal" href="#seapy-superposed-epoch-analysis-in-python">SeaPy - Superposed Epoch Analysis in Python</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="install_windows.html"
title="previous chapter">Windows Installation</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="help.html"
title="next chapter">SpacePy Help</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/quickstart.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="help.html" title="SpacePy Help"
>next</a> |</li>
<li class="right" >
<a href="install_windows.html" title="Windows Installation"
>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="">SpacePy - A Quick Start Documentation</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>