Skip to content

Commit 23c8f0b

Browse files
taldcrofttaldcroft
committed
Content improvements
1 parent ca4fe0f commit 23c8f0b

File tree

1 file changed

+177
-148
lines changed

1 file changed

+177
-148
lines changed

‎docs/index.rst

+177-148
Original file line numberDiff line numberDiff line change
@@ -3,111 +3,146 @@
33
You can adapt this file completely to your liking, but it should at least
44
contain the root `toctree` directive.
55
6-
.. _Time: http://docs.astropy.org/en/stable/api/astropy.time.Time.html#astropy.time.Time
6+
.. _Time: http://docs.astropy.org/en/stable/time/index.html
77
.. _TimeDelta: http://docs.astropy.org/en/stable/time/index.html#time-deltas
8-
.. _astropytime: http://docs.astropy.org/en/stable/time/index.html
98
.. _DateTime: http://cxc.harvard.edu/mta/ASPECT/tool_doc/pydocs/Chandra.Time.html
9+
.. _astropy.time: http://docs.astropy.org/en/stable/time/index.html
1010
.. |CxoTime| replace:: :class:`~cxotime.cxotime.CxoTime`
1111

12-
Chandra-specific astropy Time class
13-
===================================
1412

15-
The ``cxotime`` package provides a |CxoTime| class which provides Chandra-specific
16-
functionality while deriving from the Time_ class of the astropytime_ package.
17-
The astropytime_ package provides robust 128-bit time representation,
18-
arithmetic, and comparisons.
13+
.. toctree::
14+
:hidden:
15+
16+
Chandra Time
17+
============
18+
19+
The ``cxotime`` package provides the |CxoTime| class to represent and manipulate times.
20+
It also provides :mod:`fast converter functions <cxotime.converters>` for converting
21+
between time formats.
22+
23+
The |CxoTime| class adds Chandra-specific functionality to the Time_ class of the
24+
`astropy.time`_ package. The `astropy.time`_ package provides robust 128-bit time
25+
representation, arithmetic, and comparisons.
26+
27+
Basics
28+
------
29+
30+
The |CxoTime| class can be initialized with a variety of input formats, including
31+
strings, floats, integers, and arrays of these. The following examples show some
32+
of the ways to create a |CxoTime| object.
33+
34+
>>> from cxotime import CxoTime
35+
>>> t = CxoTime('2022:001:00:00:00.123')
36+
>>> t
37+
<CxoTime object: scale='utc' format='date' value=2022:001:00:00:00.123>
38+
>>> print(t)
39+
2022:001:00:00:00.123
40+
41+
Now you can convert to a different format:
42+
43+
>>> t.greta
44+
'2022001.000000123'
45+
>>> t.iso
46+
'2022-01-01 00:00:00.123'
47+
>>> t.secs
48+
757382469.307
49+
50+
You can get the current time with the :meth:`~cxotime.CxoTime.now` class method:
51+
52+
>>> t = CxoTime.now()
53+
54+
String formatted inputs are unique and you do not need to specify the format when
55+
creating a |CxoTime| object. The format is automatically inferred from the input.
56+
57+
>>> t = CxoTime('2022001.000000123')
58+
>>> t.format
59+
'greta'
60+
61+
The ``greta`` format is a little special since it can be input as either a string or a
62+
float. However, |CxoTime| will always return it as a string. By default |CxoTime|
63+
always interprets a float number as CXC seconds, so if you have a ``greta`` float
64+
then you can explicitly specify the format:
65+
66+
>>> t = CxoTime(2022001.000000123, format='greta')
67+
>>> t.date
68+
'2022:001:00:00:00.123'
69+
70+
You can also create a |CxoTime| object from a numpy array of strings, floats, or
71+
integers. When possible, the format is inferred from the input. However, if performance
72+
is an issue and you know the format in advance, you should specify it.
73+
74+
>>> import numpy as np
75+
>>> t = CxoTime(np.array([2022001.000000123, 2022002.000000123]), format='greta')
76+
>>> t.date
77+
array(['2022:001:00:00:00.123', '2022:002:00:00:00.123'], dtype='<U21')
78+
79+
Time arithmetic
80+
---------------
81+
82+
You can add and subtract times using the standard arithmetic operators and astropy
83+
units and `Quantity <https://docs.astropy.org/en/latest/units/quantity.html>`_ objects:
84+
85+
>>> import astropy.units as u
86+
>>> t0 = CxoTime("2025:001")
87+
>>> dt = [1, 2] * u.day + [10, 20] * u.s # Quantity with time units (day)
88+
>>> t1 = t0 + dt
89+
>>> print(t1)
90+
['2025:002:00:00:10.000' '2025:003:00:00:20.000']
91+
92+
If you subtract two times you get a TimeDelta_ object:
93+
94+
>>> dt = t1 - t0
95+
>>> dt.sec
96+
array([ 86410., 172820.])
97+
>>> dt.jd # days
98+
array([1.00011574, 2.00023148])
99+
100+
You can convert the TimeDelta_ object to a float type with any time unit:
101+
102+
>>> dt.to_value(u.ks)
103+
array([ 86.41, 172.82])
104+
105+
Available time formats
106+
----------------------
19107

20108
The Chandra-specific time formats which are added to the astropy Time_ class
21109
are shown in the table below. Like DateTime_, the |CxoTime| class
22110
default is to interpret any numerical values as ``secs`` (aka ``cxcsec`` in
23111
the native Time_ class).
24112

25-
========= =========================================== =======
26-
Format Description System
27-
========= =========================================== =======
28-
secs Seconds since 1998-01-01T00:00:00 (TT) utc
29-
date YYYY:DDD:hh:mm:ss.ss.. utc
30-
frac_year YYYY.ffffff = date as a floating point year utc
31-
greta YYYYDDD.hhmmsssss (string) utc
32-
maude YYYYDDDhhmmsssss (integer) utc
33-
========= =========================================== =======
34-
35-
The standard built-in Time formats that are available in |CxoTime| are:
36-
37-
=========== ==============================
38-
Format Example
39-
=========== ==============================
40-
byear 1950.0
41-
byear_str 'B1950.0'
42-
cxcsec 63072064.184
43-
datetime datetime(2000, 1, 2, 12, 0, 0)
44-
decimalyear 2000.45
45-
fits '2000-01-01T00:00:00.000(TAI)'
46-
gps 630720013.0
47-
iso '2000-01-01 00:00:00.000'
48-
isot '2000-01-01T00:00:00.000'
49-
jd 2451544.5
50-
jyear 2000.0
51-
jyear_str 'J2000.0'
52-
mjd 51544.0
53-
plot_date 730120.0003703703
54-
unix 946684800.0
55-
yday 2000:001:00:00:00.000
56-
=========== ==============================
57-
58-
59-
Basic initialization
60-
--------------------
61-
::
62-
63-
>>> from cxotime import CxoTime
64-
>>> t = CxoTime(100.0)
65-
>>> t.date
66-
'1998:001:00:00:36.816'
67-
>>> t.format
68-
'secs'
69-
>>> t.scale
70-
'utc'
71-
72-
>>> import astropy.units as u
73-
>>> t2 = t + [1, 2] * u.day + [10, 20] * u.s
74-
>>> t2.date
75-
array(['1998:002:00:00:46.816', '1998:003:00:00:56.816'], dtype='<U21')
76-
77-
>>> t = CxoTime([['1998:001:00:00:01.000', '1998:001:00:00:02.000'],
78-
['1998:001:00:00:03.000', '1998:001:00:00:04.000']])
79-
>>> t.secs
80-
array([[ 64.184, 65.184],
81-
[ 66.184, 67.184]])
82-
83-
>>> t.format
84-
'date'
85-
86-
Guessing and specifying the format
87-
----------------------------------
88-
89-
Generally speaking ``CxoTime`` will successfully guess the format for
90-
string-based times. However this requires some time, so if you know the
91-
format in advance then it is recommended to provide this via the ``format``
92-
argument.
93-
::
94-
95-
>>> t = CxoTime('2020001223344555', format='maude')
96-
>>> t.date
97-
'2020:001:22:33:44.555'
98-
99-
.. toctree::
100-
:maxdepth: 2
101-
102-
103-
Fast conversion between formats
104-
-------------------------------
113+
========= ===========================================
114+
Format Description
115+
========= ===========================================
116+
secs Seconds since 1998-01-01T00:00:00 (TT)
117+
date YYYY:DDD:hh:mm:ss.ss..
118+
frac_year YYYY.ffffff = date as a floating point year
119+
greta YYYYDDD.hhmmsssss (string)
120+
maude YYYYDDDhhmmsssss (integer)
121+
========= ===========================================
122+
123+
Some of more useful built-in Time_ formats that are also available in |CxoTime| are:
124+
125+
=========== ======================== ==============================
126+
Format Description Example
127+
=========== ======================== ==============================
128+
datetime Python datetime class datetime(2000, 1, 2, 12, 0, 0)
129+
datetime64 Numpy datetime64 class np.datetime64('2000-01-02')
130+
decimalyear Same as frac_year 2000.45
131+
iso ISO time with a space '2000-01-01 00:00:00.000'
132+
isot ISO time with a T '2000-01-01T00:00:00.000'
133+
jd Julian Date 2451544.5
134+
plot_date Matplotlib date 730120.0003703703
135+
unix Unix time (approx) 946684800.0
136+
=========== ======================== ==============================
137+
138+
Fast format conversion
139+
----------------------
105140

106141
Converting between time formats (e.g. from CXC seconds to Year Day-of-Year) is
107142
easily done with the |CxoTime| class, but this involves some overhead and is
108143
relatively slow for scalar values or small arrays (less than around 100
109144
elements). For applications where this conversion time ends up being significant,
110-
the `cxotime` package provides a different interface that is typically at least
145+
the ``cxotime`` package provides a different interface that is typically at least
111146
10x faster for scalar values or small arrays.
112147

113148
For fast conversion of an input date or dates to a different format there are
@@ -120,11 +155,11 @@ The first option is a generalized time format conversion function
120155
:func:`~cxotime.convert.convert_time_format` that can be used to convert between
121156
any of the supported *fast* formats:
122157

123-
- `secs`: CXC seconds
124-
- `date`: Year Day-of-Year
125-
- `greta`: GRETA format (input can be string, float or int)
126-
- `maude`: MAUDE format (input can be string or int)
127-
- `jd`: Julian Day (requires `fmt_in="jd"` to identity this format)
158+
- ``secs``: CXC seconds
159+
- ``date``: Year Day-of-Year
160+
- ``greta``: GRETA format (input can be string, float or int)
161+
- ``maude``: MAUDE format (input can be string or int)
162+
- ``jd``: Julian Day (requires ``fmt_in="jd"`` to identity this format)
128163

129164
For example::
130165

@@ -153,21 +188,22 @@ Convenience functions like ``secs2date``
153188
For historical compatibility and for succinct code, direct conversion between any two
154189
of the "fast" formats is also available via convenience functions. These have the name
155190
``<fmt_in>2<fmt_out>`` where ``fmt_in`` and ``fmt_out`` are the input and output formats.
191+
192+
The full list of available functions is shown in :mod:`cxotime.converters`.
193+
156194
Examples include :func:`~cxotime.convert.date2secs`, :func:`~cxotime.convert.secs2greta`,
157195
and :func:`~cxotime.convert.greta2jd`.
158196

159-
::
160-
>>> from cxotime import secs2greta
161-
>>> secs2greta([100, 1000])
162-
array(['1998001.000036816', '1998001.001536816'], dtype='<U17')
163-
197+
>>> from cxotime import secs2greta
198+
>>> secs2greta([100, 1000])
199+
array(['1998001.000036816', '1998001.001536816'], dtype='<U17')
164200

165-
Print common time conversions
166-
-----------------------------
201+
Common time conversions
202+
-----------------------
167203

168204
The `cxotime` package has functionality to convert a time betweeen a variety of common
169205
time formats. This convenience function is available in two ways, either as a
170-
command line script or as class method :meth:`~cxotime.CxoTime.print_conversions`::
206+
command line script or as class method :meth:`~cxotime.CxoTime.get_conversions`::
171207

172208
$ cxotime 2022:002:12:00:00
173209
local 2022 Sun Jan 02 07:00:00 AM EST
@@ -178,50 +214,43 @@ command line script or as class method :meth:`~cxotime.CxoTime.print_conversions
178214
iso 2022-01-02 12:00:00.000
179215
unix 1641124800.000
180216

181-
::
217+
If you do not provide an argument then it will use the current time.
182218

183-
$ cxotime # Print current time
184-
local 2023 Tue Jan 10 01:41:02 PM EST
185-
iso_local 2023-01-10T13:41:02.603000-05:00
186-
date 2023:010:18:41:02.603
187-
cxcsec 789763331.787
188-
decimalyear 2023.02679
189-
iso 2023-01-10 18:41:02.603
190-
unix 1673376062.603
219+
From Python you can do the same using the :meth:`~cxotime.CxoTime.get_conversions`
220+
method:
191221

192-
or in python::
193-
194-
>>> from cxotime import CxoTime
195-
>>> tm = CxoTime("2022-01-02 12:00:00.000")
196-
>>> tm.print_conversions()
197-
local 2022 Sun Jan 02 07:00:00 AM EST
198-
iso_local 2022-01-02T07:00:00-05:00
199-
date 2022:002:12:00:00.000
200-
cxcsec 757512069.184
201-
decimalyear 2022.00411
202-
iso 2022-01-02 12:00:00.000
203-
unix 1641124800.000
222+
>>> from cxotime import CxoTime
223+
>>> tm = CxoTime("2022-01-02 12:00:00.000")
224+
>>> tm.get_conversions()
225+
{'cxcsec': 757512069.184,
226+
'date': '2022:002:12:00:00.000',
227+
'decimalyear': 2022.004109589041,
228+
'iso': '2022-01-02 12:00:00.000',
229+
'iso_local': '2022-01-02T07:00:00-05:00',
230+
'local': '2022 Sun Jan 02 07:00:00 AM EST',
231+
'unix': 1641124800.0}
204232

205-
CxoTime.NOW sentinel
206-
--------------------
233+
CxoTime.NOW
234+
-----------
207235

208-
The |CxoTime| class has a special sentinel value ``CxoTime.NOW`` which can be used
209-
to specify the current time. This is useful for example when defining a function that
210-
has accepts a CxoTime-like argument that defaults to the current time.
236+
The |CxoTime| class has a special value ``CxoTime.NOW`` which signifies the current time
237+
when used to initialize a |CxoTime| object. This is commonly useful for example when
238+
defining a function that has accepts a CxoTime-like argument that defaults to the
239+
current time.
211240

212241
.. note:: Prior to introduction of ``CxoTime.NOW``, the standard idiom was to specify
213242
``None`` as the argument default to indicate the current time. This is still
214243
supported but is strongly discouraged for new code.
215244

216-
For example::
245+
For example:
217246

218-
>>> from cxotime import CxoTime
219-
>>> def my_func(stop=CxoTime.NOW):
220-
... stop = CxoTime(stop)
221-
... print(stop)
222-
...
223-
>>> my_func()
224-
2024:006:11:37:41.930
247+
>>> from cxotime import CxoTime
248+
>>> def my_func(stop=CxoTime.NOW):
249+
... stop = CxoTime(stop)
250+
... print(stop)
251+
...
252+
>>> my_func()
253+
2024:006:11:37:41.930
225254

226255
This can also be used in a `dataclass
227256
<https://docs.python.org/3/library/dataclasses.html>`_ to specify an attribute that is
@@ -247,20 +276,20 @@ optional and defaults to the current time when the object is created::
247276
Compatibility with DateTime
248277
---------------------------
249278

250-
The key differences between |CxoTime| and DateTime_ are:
251-
252-
- In |CxoTime| the date '2000:001' is '2000:001:00:00:00' instead of
253-
'2000:001:12:00:00' in DateTime_ (prior to version 4.0). In most cases this
254-
interpretation is more rational and expected.
255-
256-
- In |CxoTime| the date '2001-01-01T00:00:00' is UTC by default, while in
257-
DateTime_ that is interpreted as TT by default. This is triggered by
258-
the ``T`` in the middle. A date like '2001-01-01 00:00:00' defaults
259-
to UTC in both |CxoTime| and DateTime_.
279+
The key differences between |CxoTime| and DateTime_ relate to the handling of time
280+
deltas:
260281

261282
- In |CxoTime| the difference of two dates is a TimeDelta_ object
262283
which is transformable to any time units. In DateTime_ the difference
263284
of two dates is a floating point value in days.
264285

265-
- Conversely, starting with |CxoTime| one can add or subtract a TimeDelta_ or
266-
any quantity with time units.
286+
- In |CxoTime| you can add or subtract with a TimeDelta_ or a `Quantity
287+
<https://docs.astropy.org/en/latest/units/quantity.html>`_ like ``500 * u.s``. If you
288+
add or subtract a float number it is interpreted as days but a warning is issued. In
289+
DateTime_ you can only add or subtract with a float number which is interpreted as
290+
days.
291+
292+
A less common difference is that in |CxoTime| the date '2001-01-01T00:00:00' is UTC by
293+
default, while in DateTime_ that is interpreted as TT by default. This is triggered by
294+
the ``T`` in the middle. A date like '2001-01-01 00:00:00' defaults to UTC in both
295+
|CxoTime| and DateTime_.

0 commit comments

Comments
 (0)