Creating Time Series#
Initializing a Time Series#
The first type of time series that we will look at here is a |TimeSeries| object, which can be used for a time series which samples a continuous variable at discrete, instantaneous times. Initializing a |TimeSeries| object can be done in the same ways as initializing a |Table| object (see Data Tables), but additional arguments related to the times should be specified.
Evenly Sampled Time Series#
The most convenient way to construct an evenly sampled |TimeSeries| is to specify the start time, the time interval, and the number of samples:
>>> from astropy import units as u
>>> from astropy.timeseries import TimeSeries
>>> ts1 = TimeSeries(time_start='2016-03-22T12:30:31',
... time_delta=3 * u.s,
... n_samples=5)
>>> ts1
<TimeSeries length=5>
time
Time
-----------------------
2016-03-22T12:30:31.000
2016-03-22T12:30:34.000
2016-03-22T12:30:37.000
2016-03-22T12:30:40.000
2016-03-22T12:30:43.000
The time keyword argument can be set to anything that can be passed to the
|Time| class (see also Time and Dates) or |Time| objects
directly. Note that the n_samples argument is only needed if you are not
also passing in data during initialization (see Passing Data During
Initialization).
Arbitrarily Sampled Time Series#
To construct a sampled time series with samples at arbitrary times, you can
pass multiple times to the time argument:
>>> ts2 = TimeSeries(time=['2016-03-22T12:30:31',
... '2016-03-22T12:30:38',
... '2016-03-22T12:34:40'])
>>> ts2
<TimeSeries length=3>
time
Time
-----------------------
2016-03-22T12:30:31.000
2016-03-22T12:30:38.000
2016-03-22T12:34:40.000
You can also specify a vector |Time| object directly as the time= argument,
or a vector |TimeDelta| argument or a quantity array to the time_delta=
argument.:
>>> TimeSeries(time_start="2011-01-01T00:00:00",
... time_delta=[0.1, 0.2, 0.1, 0.3, 0.2]*u.s)
<TimeSeries length=5>
time
Time
-----------------------
2011-01-01T00:00:00.000
2011-01-01T00:00:00.100
2011-01-01T00:00:00.300
2011-01-01T00:00:00.400
2011-01-01T00:00:00.700
Initializing a Binned Time Series#
The |BinnedTimeSeries| can be used to represent time series where each entry corresponds to measurements taken over a range in time — for instance, a light curve constructed by binning X-ray photon events. This class supports equal-size or uneven bins, and contiguous and non-contiguous bins. As for |TimeSeries|, initializing a |BinnedTimeSeries| can be done in the same ways as initializing a |Table| object (see Data Tables), but additional arguments related to the times should be specified as described below.
Equal-Sized Contiguous Bins#
To create a binned time series with equal-size contiguous bins, it is sufficient to specify a start time as well as a bin size:
>>> from astropy.timeseries import BinnedTimeSeries
>>> ts3 = BinnedTimeSeries(time_bin_start='2016-03-22T12:30:31',
... time_bin_size=3 * u.s, n_bins=10)
>>> ts3
<BinnedTimeSeries length=10>
time_bin_start time_bin_size
s
Time float64
----------------------- -------------
2016-03-22T12:30:31.000 3.0
2016-03-22T12:30:34.000 3.0
2016-03-22T12:30:37.000 3.0
2016-03-22T12:30:40.000 3.0
2016-03-22T12:30:43.000 3.0
2016-03-22T12:30:46.000 3.0
2016-03-22T12:30:49.000 3.0
2016-03-22T12:30:52.000 3.0
2016-03-22T12:30:55.000 3.0
2016-03-22T12:30:58.000 3.0
Note that the n_bins argument is only needed if you are not also passing in
data during initialization (see Passing Data During Initialization).
Uneven Contiguous Bins#
When creating a binned time series with uneven contiguous bins, the bin size can
be changed to give multiple values (note that in this case n_bins is not
required):
>>> ts4 = BinnedTimeSeries(time_bin_start='2016-03-22T12:30:31',
... time_bin_size=[3, 3, 2, 3] * u.s)
>>> ts4
<BinnedTimeSeries length=4>
time_bin_start time_bin_size
s
Time float64
----------------------- -------------
2016-03-22T12:30:31.000 3.0
2016-03-22T12:30:34.000 3.0
2016-03-22T12:30:37.000 2.0
2016-03-22T12:30:39.000 3.0
Alternatively, you can create the same time series by giving an array of start times as well as a single end time:
>>> ts5 = BinnedTimeSeries(time_bin_start=['2016-03-22T12:30:31',
... '2016-03-22T12:30:34',
... '2016-03-22T12:30:37',
... '2016-03-22T12:30:39'],
... time_bin_end='2016-03-22T12:30:42')
>>> ts5
<BinnedTimeSeries length=4>
time_bin_start time_bin_size
s
Time float64
----------------------- -----------------
2016-03-22T12:30:31.000 3.0
2016-03-22T12:30:34.000 3.0
2016-03-22T12:30:37.000 2.0
2016-03-22T12:30:39.000 3.0
Uneven Non-Contiguous Bins#
To create a binned time series with non-contiguous bins, you can either specify an array of start times and bin widths:
>>> ts6 = BinnedTimeSeries(time_bin_start=['2016-03-22T12:30:31',
... '2016-03-22T12:30:38',
... '2016-03-22T12:34:40'],
... time_bin_size=[5, 100, 2]*u.s)
>>> ts6
<BinnedTimeSeries length=3>
time_bin_start time_bin_size
s
Time float64
----------------------- -------------
2016-03-22T12:30:31.000 5.0
2016-03-22T12:30:38.000 100.0
2016-03-22T12:34:40.000 2.0
Or in the most general case, you can also specify multiple times for
time_bin_start and time_bin_end:
>>> ts7 = BinnedTimeSeries(time_bin_start=['2016-03-22T12:30:31',
... '2016-03-22T12:30:33',
... '2016-03-22T12:30:40'],
... time_bin_end=['2016-03-22T12:30:32',
... '2016-03-22T12:30:35',
... '2016-03-22T12:30:41'])
>>> ts7
<BinnedTimeSeries length=3>
time_bin_start time_bin_size
s
Time float64
----------------------- ------------------
2016-03-22T12:30:31.000 1.0
2016-03-22T12:30:33.000 2.0
2016-03-22T12:30:40.000 1.0
Adding Data to the Time Series#
The above examples show how to initialize |TimeSeries| objects, but these do not include any data aside from the times. There are different ways of adding data, as with the |Table| class.
Passing Data During Initialization#
It is possible to pass data during the initialization of a |TimeSeries| object, as for |Table| objects. For instance:
>>> ts8 = BinnedTimeSeries(time_bin_start=['2016-03-22T12:30:31',
... '2016-03-22T12:30:34',
... '2016-03-22T12:30:37',
... '2016-03-22T12:30:39'],
... time_bin_end='2016-03-22T12:30:42',
... data={'flux': [1., 4., 5., 6.] * u.mJy})
>>> ts8
<BinnedTimeSeries length=4>
time_bin_start time_bin_size flux
s mJy
Time float64 float64
----------------------- ----------------- -------
2016-03-22T12:30:31.000 3.0 1.0
2016-03-22T12:30:34.000 3.0 4.0
2016-03-22T12:30:37.000 2.0 5.0
2016-03-22T12:30:39.000 3.0 6.0
Adding Data After Initialization#
Once a |TimeSeries| object is initialized, you can add columns/fields to it as you would for a |Table| object:
>>> from astropy import units as u
>>> ts1['flux'] = [1., 4., 5., 6., 4.] * u.mJy
>>> ts1
<TimeSeries length=5>
time flux
mJy
Time float64
----------------------- -------
2016-03-22T12:30:31.000 1.0
2016-03-22T12:30:34.000 4.0
2016-03-22T12:30:37.000 5.0
2016-03-22T12:30:40.000 6.0
2016-03-22T12:30:43.000 4.0
Adding Rows#
Adding rows to |TimeSeries| or |BinnedTimeSeries| can be done using the
add_row() method, as for |Table| and |QTable|. This
method takes a dictionary where the keys are column names:
>>> ts8.add_row({'time_bin_start': '2016-03-22T12:30:44.000',
... 'time_bin_size': 2 * u.s,
... 'flux': 3 * u.mJy})
>>> ts8
<BinnedTimeSeries length=5>
time_bin_start time_bin_size flux
s mJy
Time float64 float64
----------------------- ----------------- -------
2016-03-22T12:30:31.000 3.0 1.0
2016-03-22T12:30:34.000 3.0 4.0
2016-03-22T12:30:37.000 2.0 5.0
2016-03-22T12:30:39.000 3.0 6.0
2016-03-22T12:30:44.000 2.0 3.0
If you want to be able to skip some values when adding rows, you should make sure that masking is enabled — see Masking Values in Time Series for more details.