Creating time series

Initializing a simple time series

The first type of time series that we will look at here is TimeSeries, which can be used for a time series which samples a continuous variable at discrete and instantaneous times. Initializing a TimeSeries 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 easiest way to construct an evenly sampled time series is to specify the start time, the time interval, and the number of samples, for evenly sampled time series:

>>> from astropy import units as u
>>> from astropy_timeseries import TimeSeries
>>> ts1 = TimeSeries(time='2016-03-22T12:30:31',
...                         time_delta=3 * u.s,
...                         n_samples=5)
>>> ts1
<TimeSeries length=5>
          time
         object
-----------------------
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). 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
         object
-----------------------
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="2011-01-01T00:00:00", time_delta=[0.1, 0.2, 0.1, 0.3, 0.2]*u.s)
<TimeSeries length=5>
          time
        object
-----------------------
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 example 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
        object            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

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
         object            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
      object              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
         object            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
         object              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

You can also specify vector Time objects directly.

Adding data to the time series

The above examples show how to initialize time series objects, but these don’t include any data aside from the times. There are different ways of adding data, as for the Table class.

Adding data after initalization

Once the time series 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
         object         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

Passing data during initialization

It is also possible to pass the data during the initialization, as for Table, e.g.:

>>> 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
         object              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 rows

Adding rows to TimeSeries or BinnedTimeSeries can be done using the add_row() method, as for Table and Table. 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
         object              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 miss out values when adding rows, you should make sure that masking is enabled - see Masking values in time series for more details.