-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathtime.html
294 lines (281 loc) · 20.3 KB
/
time.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
<!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>time - Time conversion, manipulation and implementation of Ticktock class — 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="Writing Pythonic Code" href="pythonic.html" />
<link rel="prev" title="pycdf - Python interface to CDF files" href="pycdf.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="pythonic.html" title="Writing Pythonic Code"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="pycdf.html" title="pycdf - Python interface to CDF files"
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="">time - Time conversion, manipulation and implementation of Ticktock class</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="time-time-conversion-manipulation-and-implementation-of-ticktock-class">
<h1>time - Time conversion, manipulation and implementation of Ticktock class<a class="headerlink" href="#time-time-conversion-manipulation-and-implementation-of-ticktock-class" 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="#introduction" id="id2">Introduction</a></p></li>
<li><p><a class="reference internal" href="#examples" id="id3">Examples</a></p></li>
</ul>
</nav>
<p>See also the <a class="reference internal" href="autosummary/spacepy.time.html#module-spacepy.time" title="spacepy.time"><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="introduction">
<h3><a class="toc-backref" href="#id2" role="doc-backlink">Introduction</a><a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h3>
<p>The handling of time, in particular the conversions between representations,
can be more complicated than it seems on the surface. This can result in
some surprising behavior, particularly when requiring second-level accuracy and
converting between time systems outside of the period 1972 to present.
It is strongly recommended to use TAI if transferring times between SpacePy
and other libraries. TAI has a consistent, unambiguous definition and no
discontinuities.</p>
<p>Some time systems (e.g. the UTC representation via datetime) cannot represent
times during a leapsecond. SpacePy represents all these times as the latest
representable time in the day, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">spacepy</span><span class="o">.</span><span class="n">time</span><span class="o">.</span><span class="n">Ticktock</span><span class="p">(</span><span class="s1">'2008-12-31T23:59:60'</span><span class="p">)</span><span class="o">.</span><span class="n">UTC</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">datetime.datetime(2008, 12, 31, 23, 59, 59, 999999)</span>
</pre></div>
</div>
<p>Conversions between continuous time representations (e.g. TAI), leap second
aware representations (e.g. ISO timestrings), and those that ignore leap
seconds (e.g. UTC datetime, Unix time) are well-defined between the
introduction of the leap second system to UTC in 1972 and the present.
For systems that cannot represent leap seconds, the leap second moment is
considered not to exist. For example, from 23:59:59 on 2008-12-31 to 00:00:00
on 2009-01-01 is two seconds, but only represents a one-second increment in
Unix time. Details are also discussed in the individual time representations.</p>
<p>UTC times more than six months in the future are not well-defined, since
the schedule of leap second insertion is not known in advance. SpacePy
performs conversions assuming there are no leapseconds after those which have
been announced by IERS.</p>
<p>Between 1960 and 1972, UTC was defined by means of fractional leap
seconds and a varying-length second. From 1958 (when UTC was set equal
to TAI) and 1972, SpacePy treats UTC time similar to after 1972, with
a consistent second the same length of the SI second, and applying a
full leap second before the beginning of January and July if UTC - UT1
exceeded 0.4s. The difference with other methods of calculating UTC is
less than half a second.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.2.3: </span>The application of post-1972 rules to 1958-1927 is new in
0.2.3. Before, SpacePy applied leap seconds wherever there was an
entry in the USNO record of TAI-UTC, rounding fractional total leap
second counts to the integer (0.5 rounds up). The UTC second was still
treated as the same length as the SI second (i.e., rate changed were
not applied.) This resulted in the application of six leap seconds at
the beginning of 1972. The discrepancy with other means of calculating
TAI-UTC was as much as five seconds by the end of this period.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.2.2: </span>Before 0.2.2, SpacePy truncated fractional leapseconds rather than rounding.</p>
</div>
<p>Before 1958, UTC is not defined. SpacePy assumes days of constant length
86400 seconds, equal to the SI second. This is almost guaranteed to be wrong;
for times well out of the space era, it is strongly recommended to work
consistently in either a continuous time system (e.g. TAI) or a day-based
system (e.g. JD).</p>
<p>SpacePy assumes dates including and after 1582-10-15 to be in the Gregorian
calendar and dates including and before 1582-10-04 to be Julian. 10-05 through
10-14 do not exist. This change is ignored for continuously-running non leap
second aware timebases: CDF and RDT.</p>
<p>See the <a class="reference internal" href="autosummary/spacepy.time.Ticktock.html#spacepy.time.Ticktock" title="spacepy.time.Ticktock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Ticktock</span></code></a> documentation and its various <code class="docutils literal notranslate"><span class="pre">get</span></code> functions for
more details on the exact definitions of time systems used by SpacePy.</p>
</section>
<section id="examples">
<h3><a class="toc-backref" href="#id3" role="doc-backlink">Examples</a><a class="headerlink" href="#examples" title="Link to this heading">¶</a></h3>
<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.time</span> <span class="k">as</span> <span class="nn">spt</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>
</pre></div>
</div>
<p>Day of year calculations</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dts</span> <span class="o">=</span> <span class="n">spt</span><span class="o">.</span><span class="n">doy2date</span><span class="p">([</span><span class="mi">2002</span><span class="p">]</span><span class="o">*</span><span class="mi">4</span><span class="p">,</span> <span class="nb">range</span><span class="p">(</span><span class="mi">186</span><span class="p">,</span><span class="mi">190</span><span class="p">),</span> <span class="n">dtobj</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">dts</span>
<span class="go">[datetime.datetime(2002, 7, 5, 0, 0),</span>
<span class="go">datetime.datetime(2002, 7, 6, 0, 0),</span>
<span class="go">datetime.datetime(2002, 7, 7, 0, 0),</span>
<span class="go">datetime.datetime(2002, 7, 8, 0, 0)]</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dts</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="n">dts</span><span class="p">,</span><span class="s1">'UTC'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">dts</span><span class="o">.</span><span class="n">DOY</span>
<span class="go">array([ 186., 187., 188., 189.])</span>
</pre></div>
</div>
<p>Ticktock object creation</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">isodates</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'2009-12-01T12:00:00'</span><span class="p">,</span> <span class="s1">'2009-12-04T00:00:00'</span><span class="p">,</span> <span class="s1">'2009-12-06T12:00:00'</span><span class="p">]</span>
<span class="gp">>>> </span><span class="n">dts</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="n">isodates</span><span class="p">,</span> <span class="s1">'ISO'</span><span class="p">)</span>
</pre></div>
</div>
<p>OR</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dtdates</span> <span class="o">=</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">12</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">12</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">12</span><span class="p">,</span><span class="mi">4</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">12</span><span class="p">,</span><span class="mi">6</span><span class="p">,</span><span class="mi">12</span><span class="p">)]</span>
<span class="gp">>>> </span><span class="n">dts</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="n">dtdates</span><span class="p">,</span> <span class="s1">'UTC'</span><span class="p">)</span>
</pre></div>
</div>
<p>ISO time formatting</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dts</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">'2009-12-01T12:00:00'</span><span class="p">,</span><span class="s1">'2009-12-06T12:00:00'</span><span class="p">,</span><span class="mf">2.5</span><span class="p">)</span>
</pre></div>
</div>
<p>OR</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dts</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">2009</span><span class="p">,</span><span class="mi">12</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">12</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">12</span><span class="p">,</span><span class="mi">6</span><span class="p">,</span><span class="mi">12</span><span class="p">),</span> \
<span class="go"> dt.timedelta(days=2, hours=12))</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dts</span>
<span class="go">Ticktock( ['2009-12-01T12:00:00', '2009-12-04T00:00:00', '2009-12-06T12:00:00'] ), dtype=ISO</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dts</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span>
<span class="go">Current ISO output format is %Y-%m-%dT%H:%M:%S</span>
<span class="go">Options are: [('seconds', '%Y-%m-%dT%H:%M:%S'), ('microseconds', '%Y-%m-%dT%H:%M:%S.%f')]</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dts</span><span class="o">.</span><span class="n">isoformat</span><span class="p">(</span><span class="s1">'microseconds'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">dts</span><span class="o">.</span><span class="n">ISO</span>
<span class="go">['2009-12-01T12:00:00.000000',</span>
<span class="go"> '2009-12-04T00:00:00.000000',</span>
<span class="go"> '2009-12-06T12:00:00.000000']</span>
</pre></div>
</div>
<p>Time manipulation</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">new_dts</span> <span class="o">=</span> <span class="n">dts</span> <span class="o">+</span> <span class="n">tdelt</span>
<span class="gp">>>> </span><span class="n">new_dts</span><span class="o">.</span><span class="n">UTC</span>
<span class="go">[datetime.datetime(2009, 12, 2, 18, 0),</span>
<span class="go"> datetime.datetime(2009, 12, 5, 6, 0),</span>
<span class="go"> datetime.datetime(2009, 12, 7, 18, 0)]</span>
</pre></div>
</div>
<p>Other time formats</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dts</span><span class="o">.</span><span class="n">RDT</span> <span class="c1"># Gregorian ordinal time</span>
<span class="go">array([ 733742.5, 733745. , 733747.5])</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dts</span><span class="o">.</span><span class="n">GPS</span> <span class="c1"># GPS time</span>
<span class="go">array([ 9.43704015e+08, 9.43920015e+08, 9.44136015e+08])</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dts</span><span class="o">.</span><span class="n">JD</span> <span class="c1"># Julian day</span>
<span class="go">array([ 2455167. , 2455169.5, 2455172. ])</span>
</pre></div>
</div>
<p>And so on.</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="#">time - Time conversion, manipulation and implementation of Ticktock class</a><ul>
<li><a class="reference internal" href="#contents">Contents</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a></li>
<li><a class="reference internal" href="#examples">Examples</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="pycdf.html"
title="previous chapter">pycdf - Python interface to CDF files</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="pythonic.html"
title="next chapter">Writing Pythonic Code</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/time.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="pythonic.html" title="Writing Pythonic Code"
>next</a> |</li>
<li class="right" >
<a href="pycdf.html" title="pycdf - Python interface to CDF files"
>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="">time - Time conversion, manipulation and implementation of Ticktock class</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>