Skip to content

Commit 29da87b

Browse files
committed
Addressed review comments by @pllim
* Added entry in stability page of docs * Add documentation about missing values in the pandas conversion * Added Kepler/TESS reader to the API docs * Use real files to demonstrate I/O * Clarify example of .loc * Added a note about duplicates and sorting with vstack * Fix example on analysis page * Clean up formatting and docstrings * Improve example in docs to include units
1 parent 84cf252 commit 29da87b

16 files changed

Lines changed: 191 additions & 100 deletions

‎astropy/timeseries/binned.py‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,14 @@
88
from astropy.time import Time, TimeDelta
99
from astropy import units as u
1010
from astropy.units import Quantity
11+
from astropy.utils.misc import InheritDocstrings
1112

1213
from astropy.timeseries.core import BaseTimeSeries
1314

1415
__all__ = ['BinnedTimeSeries']
1516

1617

17-
class BinnedTimeSeries(BaseTimeSeries):
18+
class BinnedTimeSeries(BaseTimeSeries, metaclass=InheritDocstrings):
1819
"""
1920
A class to represent binned time series data in tabular form.
2021
@@ -248,7 +249,7 @@ def read(self, filename, time_bin_start_column=None, time_bin_end_column=None,
248249
time_bin_size_column: str, optional
249250
The name of the column with the size for each bin. Either this
250251
option or ``time_bin_end_column`` should be specified.
251-
time_bin_size_unit: `astropy.units.quantity.Quantity`, optional
252+
time_bin_size_unit: `astropy.units.Unit`, optional
252253
If ``time_bin_size_column`` is specified but does not have a unit
253254
set in the table, you can specify the unit manually.
254255
time_format: str, optional
@@ -312,8 +313,8 @@ def read(self, filename, time_bin_start_column=None, time_bin_end_column=None,
312313
raise ValueError("Bin size column '{}' not found in the input data.".format(time_bin_size_column))
313314

314315
if time_bin_size.unit is None:
315-
if time_bin_size_unit is None or not isinstance(time_bin_size_unit, u.Quantity):
316-
raise ValueError("The bin size unit should be specified as an astropy Quantity using ``time_bin_size_unit``.")
316+
if time_bin_size_unit is None or not isinstance(time_bin_size_unit, u.UnitBase):
317+
raise ValueError("The bin size unit should be specified as an astropy Unit using ``time_bin_size_unit``.")
317318
time_bin_size = time_bin_size * time_bin_size_unit
318319
else:
319320
time_bin_size = u.Quantity(time_bin_size)

‎astropy/timeseries/io/kepler.py‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -14,30 +14,33 @@
1414

1515
def kepler_fits_reader(filename):
1616
"""
17-
This serves as the FITS reader for KEPLER or TESS files within astropy-timeseries.
17+
This serves as the FITS reader for KEPLER or TESS files within
18+
astropy-timeseries.
1819
19-
This allows reading a supported FITS file using syntax such as::
20-
>>> from astropy.timeseries.sampled import TimeSeries
21-
>>> timeseries = TimeSeries.read('<name of fits file>', format='kepler.fits') # doctest: +SKIP
20+
This function should generally not be called directly, and instead this
21+
time series reader should be accessed with the
22+
:meth:`~astropy.timeseries.TimeSeries.read` method::
23+
24+
>>> from astropy.timeseries import TimeSeries
25+
>>> ts = TimeSeries.read('kplr33122.fits', format='kepler.fits') # doctest: +SKIP
2226
2327
Parameters
2428
----------
25-
filename: `str`, `pathlib.Path`
29+
filename: `str` or `pathlib.Path`
2630
File to load.
2731
2832
Returns
2933
-------
30-
`astropy.timeseries.sampled.TimeSeries`
34+
`astropy.timeseries.TimeSeries`
3135
Data converted into a TimeSeries.
32-
3336
"""
3437
hdulist = fits.open(filename)
3538
# Get the lightcurve HDU
36-
telescop = hdulist[0].header['telescop'].lower()
39+
telescope = hdulist[0].header['telescop'].lower()
3740

38-
if telescop == 'tess':
41+
if telescope == 'tess':
3942
hdu = hdulist['LIGHTCURVE']
40-
elif telescop == 'kepler':
43+
elif telescope == 'kepler':
4144
hdu = hdulist[1]
4245
else:
4346
raise NotImplementedError("{} is not implemented, only KEPLER or TESS are "

‎astropy/timeseries/sampled.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,14 @@
88
from astropy.time import Time, TimeDelta
99
from astropy import units as u
1010
from astropy.units import Quantity
11+
from astropy.utils.misc import InheritDocstrings
1112

1213
from astropy.timeseries.core import BaseTimeSeries
1314

1415
__all__ = ['TimeSeries']
1516

1617

17-
class TimeSeries(BaseTimeSeries):
18+
class TimeSeries(BaseTimeSeries, metaclass=InheritDocstrings):
1819
"""
1920
A class to represent time series data in tabular form.
2021
@@ -176,6 +177,7 @@ def __getitem__(self, item):
176177
return super().__getitem__(item)
177178

178179
def add_columns(self, *args, **kwargs):
180+
# Note that the docstring is inherited from QTable
179181
result = super().add_columns(*args, **kwargs)
180182
if len(self.indices) == 0 and 'time' in self.colnames:
181183
self.add_index('time')

‎astropy/timeseries/tests/test_binned.py‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,16 @@
11
# Licensed under a 3-clause BSD style license - see LICENSE.rst
22

3-
import os
4-
53
import pytest
64
from numpy.testing import assert_equal
75

86
from astropy import units as u
97
from astropy.time import Time, TimeDelta
8+
from astropy.utils.data import get_pkg_data_filename
109

1110
from astropy.timeseries.binned import BinnedTimeSeries
1211

1312

14-
CSV_FILE = os.path.join(os.path.dirname(__file__), 'data', 'binned.csv')
13+
CSV_FILE = get_pkg_data_filename('data/binned.csv')
1514

1615

1716
def test_empty_initialization():
@@ -237,12 +236,12 @@ def test_read_both_extra_bins():
237236
def test_read_size_no_unit():
238237
with pytest.raises(ValueError) as exc:
239238
BinnedTimeSeries.read(CSV_FILE, time_bin_start_column='time_start', time_bin_size_column='bin_size', format='csv')
240-
assert exc.value.args[0] == "The bin size unit should be specified as an astropy Quantity using ``time_bin_size_unit``."
239+
assert exc.value.args[0] == "The bin size unit should be specified as an astropy Unit using ``time_bin_size_unit``."
241240

242241

243242
def test_read_start_time_missing():
244243
with pytest.raises(ValueError) as exc:
245-
BinnedTimeSeries.read(CSV_FILE, time_bin_start_column='abc', time_bin_size_column='bin_size', time_bin_size_unit=1*u.second, format='csv')
244+
BinnedTimeSeries.read(CSV_FILE, time_bin_start_column='abc', time_bin_size_column='bin_size', time_bin_size_unit=u.second, format='csv')
246245
assert exc.value.args[0] == "Bin start time column 'abc' not found in the input data."
247246

248247

@@ -254,14 +253,14 @@ def test_read_end_time_missing():
254253

255254
def test_read_size_missing():
256255
with pytest.raises(ValueError) as exc:
257-
BinnedTimeSeries.read(CSV_FILE, time_bin_start_column='time_start', time_bin_size_column="missing", time_bin_size_unit=1*u.second, format='csv')
256+
BinnedTimeSeries.read(CSV_FILE, time_bin_start_column='time_start', time_bin_size_column="missing", time_bin_size_unit=u.second, format='csv')
258257
assert exc.value.args[0] == "Bin size column 'missing' not found in the input data."
259258

260259

261260
def test_read_time_unit_missing():
262261
with pytest.raises(ValueError) as exc:
263262
BinnedTimeSeries.read(CSV_FILE, time_bin_start_column='time_start', time_bin_size_column="bin_size", format='csv')
264-
assert exc.value.args[0] == "The bin size unit should be specified as an astropy Quantity using ``time_bin_size_unit``."
263+
assert exc.value.args[0] == "The bin size unit should be specified as an astropy Unit using ``time_bin_size_unit``."
265264

266265

267266
def test_read():
@@ -274,7 +273,7 @@ def test_read():
274273

275274
timeseries = BinnedTimeSeries.read(CSV_FILE, time_bin_start_column='time_start',
276275
time_bin_size_column='bin_size',
277-
time_bin_size_unit=1*u.second, format='csv')
276+
time_bin_size_unit=u.second, format='csv')
278277
assert timeseries.colnames == ['time_bin_start', 'time_bin_size', 'time_end', 'A', 'B', 'C', 'D', 'E', 'F']
279278
assert len(timeseries) == 10
280279
assert timeseries['B'].sum() == 1151.54

‎astropy/timeseries/tests/test_sampled.py‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
# Licensed under a 3-clause BSD style license - see LICENSE.rst
22

3-
import os
43
from datetime import datetime
54

65
import pytest
@@ -19,7 +18,7 @@
1918
'2016-03-22T12:30:40'])
2019
PLAIN_TABLE = Table([[1, 2, 11], [3, 4, 1], [1, 1, 1]], names=['a', 'b', 'c'])
2120

22-
CSV_FILE = os.path.join(os.path.dirname(__file__), 'data', 'sampled.csv')
21+
CSV_FILE = get_pkg_data_filename('data/sampled.csv')
2322

2423

2524
def test_empty_initialization():

‎docs/stability.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -251,6 +251,17 @@ The current planned and existing sub-packages are:
251251
for the foreseeable future.
252252
</td>
253253
</tr>
254+
<tr>
255+
<td>
256+
astropy.timeseries
257+
</td>
258+
<td align='center'>
259+
<span class="mature"></span>
260+
</td>
261+
<td>
262+
New in v3.2, in heavy development.
263+
</td>
264+
</tr>
254265
<tr>
255266
<td>
256267
astropy.units

‎docs/timeseries/analysis.rst‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,11 @@ series cannot be combined with binned time series and vice-versa)::
2222
>>> from astropy import units as u
2323
>>> from astropy.timeseries import TimeSeries
2424
>>> ts_a = TimeSeries(time='2016-03-22T12:30:31',
25-
... time_delta=3 * u.s,
26-
... data={'flux': [1, 4, 5, 3, 2] * u.mJy})
25+
... time_delta=3 * u.s,
26+
... data={'flux': [1, 4, 5, 3, 2] * u.mJy})
2727
>>> ts_b = TimeSeries(time='2016-03-22T12:50:31',
28-
... time_delta=3 * u.s,
29-
... data={'flux': [4, 3, 1, 2, 3] * u.mJy})
28+
... time_delta=3 * u.s,
29+
... data={'flux': [4, 3, 1, 2, 3] * u.mJy})
3030
>>> ts_ab = vstack([ts_a, ts_b])
3131
>>> ts_ab
3232
<TimeSeries length=10>
@@ -45,6 +45,9 @@ series cannot be combined with binned time series and vice-versa)::
4545
2016-03-22T12:50:40.000 2.0
4646
2016-03-22T12:50:43.000 3.0
4747

48+
Note that :func:`~astropy.table.vstack` does not automatically sort, nor get rid
49+
of duplicates - this is something you would need to do explicitly afterwards.
50+
4851
Time series can also be combined 'horizontally' or column-wise with other tables
4952
using the :func:`~astropy.table.hstack` function, though these should not be
5053
time series (as having multiple time columns would be confusing)::
@@ -71,8 +74,8 @@ Sorting time series in-place can be done using the
7174
:meth:`~astropy.table.Table.sort` method, as for |Table|::
7275

7376
>>> ts = TimeSeries(time='2016-03-22T12:30:31',
74-
... time_delta=3 * u.s,
75-
... data={'flux': [1., 4., 5., 3., 2.]})
77+
... time_delta=3 * u.s,
78+
... data={'flux': [1., 4., 5., 3., 2.]})
7679
>>> ts
7780
<TimeSeries length=5>
7881
time flux
@@ -111,6 +114,7 @@ mission into 20 minute bins using a median function. First, we read in the data
111114
using:
112115

113116
.. plot::
117+
:include-source:
114118
:context: reset
115119
:nofigs:
116120

@@ -176,6 +180,10 @@ an epoch as a :class:`~astropy.time.Time`, which defines a zero time offset:
176180
plt.xlabel('Time from midpoint epoch (days)')
177181
plt.ylabel('SAP Flux (e-/s)')
178182

183+
Note that in this example we happened to know the period and midpoint from a
184+
previous periodogram analysis - see the example in :doc:`index` for how you
185+
might do this.
186+
179187
Arithmetic
180188
==========
181189

‎docs/timeseries/binned.csv‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
time_start,bin_size,time_end,A,B,C,D,E,F
2+
2016-03-22T12:30:31.000,3,2016-03-22T12:30:34.000,164.93,114.73,26.27,19.21,28.87,63.44
3+
2016-03-22T12:30:34.000,3,2016-03-22T12:30:37.000,164.89,114.75,26.22,19.07,27.76,59.98
4+
2016-03-22T12:30:37.000,3,2016-03-22T12:30:40.000,164.63,115.04,25.78,19.01,27.04,59.61
5+
2016-03-22T12:30:40.000,3,2016-03-22T12:30:43.000,163.92,114.85,27.41,19.61,27.84,59.41
6+
2016-03-22T12:30:43.000,3,2016-03-22T12:30:46.000,163.45,114.84,26.86,19.53,28.02,60.09
7+
2016-03-22T12:30:46.000,3,2016-03-22T12:30:49.000,163.46,115.4,27.09,19.72,28.25,59.62
8+
2016-03-22T12:30:49.000,3,2016-03-22T12:30:52.000,163.22,115.56,27.13,19.63,28.24,58.65
9+
2016-03-22T12:30:52.000,3,2016-03-22T12:30:55.000,164.02,115.54,26.74,19.55,28.43,59.2
10+
2016-03-22T12:30:55.000,3,2016-03-22T12:30:58.000,163.59,115.72,27.82,20.21,29.17,56.18
11+
2016-03-22T12:30:58.000,3,2016-03-22T12:31:01.000,163.32,115.11,28.22,20.42,29.38,56.64

‎docs/timeseries/data_access.rst‎

Lines changed: 21 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -23,20 +23,15 @@ with two data columns - ``flux`` and ``temp``::
2323
>>> from astropy import units as u
2424
>>> from astropy.timeseries import TimeSeries
2525
>>> ts = TimeSeries(time='2016-03-22T12:30:31',
26-
... time_delta=3 * u.s,
27-
... data={'flux': [1., 4., 5., 3., 2.],
28-
... 'temp': [40., 41., 39., 24., 20.]},
29-
... names=('flux', 'temp'))
26+
... time_delta=3 * u.s,
27+
... data={'flux': [1., 4., 5., 3., 2.] * u.Jy,
28+
... 'temp': [40., 41., 39., 24., 20.] * u.K},
29+
... names=('flux', 'temp'))
3030

3131
As for |Table|, columns can be accessed by name::
3232

3333
>>> ts['flux']
34-
<Column name='flux' dtype='float64' length=5>
35-
1.0
36-
4.0
37-
5.0
38-
3.0
39-
2.0
34+
<Quantity [1., 4., 5., 3., 2.] Jy>
4035
>>> ts['time']
4136
<Time object: scale='utc' format='isot' value=['2016-03-22T12:30:31.000' '2016-03-22T12:30:34.000'
4237
'2016-03-22T12:30:37.000' '2016-03-22T12:30:40.000'
@@ -47,6 +42,7 @@ and rows can be accessed by index::
4742
>>> ts[0]
4843
<Row index=0>
4944
time flux temp
45+
Jy K
5046
object float64 float64
5147
----------------------- ------- -------
5248
2016-03-22T12:30:31.000 1.0 40.0
@@ -55,10 +51,10 @@ Accessing individual values can then be done either by accessing a column then a
5551
row, or vice-versa::
5652

5753
>>> ts[0]['flux']
58-
1.0
54+
<Quantity 1. Jy>
5955

6056
>>> ts['temp'][2]
61-
39.0
57+
<Quantity 39. K>
6258

6359
.. _timeseries-accessing-times:
6460

@@ -112,6 +108,7 @@ We can create a new time series with just the ``flux`` column by doing::
112108
>>> ts['time', 'flux']
113109
<TimeSeries length=5>
114110
time flux
111+
Jy
115112
object float64
116113
----------------------- -------
117114
2016-03-22T12:30:31.000 1.0
@@ -120,12 +117,14 @@ We can create a new time series with just the ``flux`` column by doing::
120117
2016-03-22T12:30:40.000 3.0
121118
2016-03-22T12:30:43.000 2.0
122119

123-
And we can also create a plain |QTable| by extracting just the ``flux`` and
120+
Note that the new columns will be copies (not views) of the original columns.
121+
We can also create a plain |QTable| by extracting just the ``flux`` and
124122
``temp`` columns::
125123

126124
>>> ts['flux', 'temp']
127125
<QTable length=5>
128126
flux temp
127+
Jy K
129128
float64 float64
130129
------- -------
131130
1.0 40.0
@@ -143,6 +142,7 @@ e.g.::
143142
>>> ts[0:2]
144143
<TimeSeries length=2>
145144
time flux temp
145+
Jy K
146146
object float64 float64
147147
----------------------- ------- -------
148148
2016-03-22T12:30:31.000 1.0 40.0
@@ -161,23 +161,28 @@ entries for a given timestamp::
161161
>>> ts.loc[Time('2016-03-22T12:30:31.000')] # doctest: +SKIP
162162
<Row index=0>
163163
time flux temp
164+
Jy K
164165
object float64 float64
165166
----------------------- ------- -------
166167
2016-03-22T12:30:31.000 1.0 40.0
167168

168169
or within a time range::
169170

170-
>>> ts.loc[Time('2016-03-22T12:30:31'):Time('2016-03-22T12:30:40')]
171+
>>> ts.loc['2016-03-22T12:30:30':'2016-03-22T12:30:41']
171172
<TimeSeries length=4>
172173
time flux temp
174+
Jy K
173175
object float64 float64
174176
----------------------- ------- -------
175177
2016-03-22T12:30:31.000 1.0 40.0
176178
2016-03-22T12:30:34.000 4.0 41.0
177179
2016-03-22T12:30:37.000 5.0 39.0
178180
2016-03-22T12:30:40.000 3.0 24.0
179181

180-
.. TODO: make it so that Time() is not required above
182+
Note that in this case we didn't specify |Time| - this isn't needed if the
183+
string is an ISO 8601 time string. Also, as for the |QTable| and |Table| class
184+
``loc`` attribute, and to be consistent with `pandas
185+
<https://pandas.pydata.org/>`_, the last item in the ``loc`` range is inclusive.
181186

182187
Note that the result will always be sorted by time. Similarly, the
183188
:attr:`~astropy.timeseries.TimeSeries.iloc` attribute can be used to fetch
@@ -187,6 +192,7 @@ entries (by time) can be accessed with::
187192
>>> ts.iloc[0:2]
188193
<TimeSeries length=2>
189194
time flux temp
195+
Jy K
190196
object float64 float64
191197
----------------------- ------- -------
192198
2016-03-22T12:30:31.000 1.0 40.0

0 commit comments

Comments
 (0)