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.