.. _astropy-timeseries: ********************************** Time Series (`astropy.timeseries`) ********************************** Introduction ============ From sampling a continuous variable at fixed times to counting events binned into time windows, many different areas of astrophysics require the manipulation of 1D time series data. To address this need, the `astropy.timeseries` subpackage provides classes to represent and manipulate time series. The time series classes presented below are |QTable| subclasses that have special columns to represent times using the |Time| class. Therefore, much of the functionality described in :ref:`astropy-table` applies here. But the main purpose of the new classes are to provide time series-specific functionality above and beyond |QTable|. Getting Started =============== In this section, we take a quick look at how to read in a time series, access the data, and carry out some basic analysis. For more details about creating and using time series, see the full documentation in :ref:`using-timeseries`. The most basic time series class is |TimeSeries| — it represents a time series as a collection of values at specific points in time. If you are interested in representing time series as measurements in discrete time bins, you will likely be interested in the |BinnedTimeSeries| subclass which we show in :ref:`using-timeseries`). .. EXAMPLE START: Using the TimeSeries Class To start off, we retrieve a FITS file containing a Kepler light curve for a source:: >>> from astropy.utils.data import get_pkg_data_filename >>> filename = get_pkg_data_filename('timeseries/kplr010666592-2009131110544_slc.fits') # doctest: +REMOTE_DATA .. note:: The light curve provided here is handpicked for example purposes. For more information about the Kepler FITS format, see `Section 2.3.1 of the Kepler Archive Manual `_. To get other light curves for science purposes using Python, see the `astroquery `_ affiliated package. We can then use the |TimeSeries| class to read in this file:: >>> from astropy.timeseries import TimeSeries >>> ts = TimeSeries.read(filename, format='kepler.fits') # doctest: +REMOTE_DATA +IGNORE_WARNINGS Time series are specialized kinds of |Table| objects:: >>> ts # doctest: +REMOTE_DATA time timecorr ... pos_corr1 pos_corr2 d ... pix pix Time float32 ... float32 float32 ----------------------- ------------- ... -------------- -------------- 2009-05-02T00:41:40.338 6.630610e-04 ... 1.5822421e-03 -1.4463664e-03 2009-05-02T00:42:39.188 6.630857e-04 ... 1.5743829e-03 -1.4540013e-03 2009-05-02T00:43:38.045 6.631103e-04 ... 1.5665225e-03 -1.4616371e-03 2009-05-02T00:44:36.894 6.631350e-04 ... 1.5586632e-03 -1.4692718e-03 2009-05-02T00:45:35.752 6.631597e-04 ... 1.5508028e-03 -1.4769078e-03 2009-05-02T00:46:34.601 6.631844e-04 ... 1.5429436e-03 -1.4845425e-03 2009-05-02T00:47:33.451 6.632091e-04 ... 1.5350844e-03 -1.4921773e-03 2009-05-02T00:48:32.291 6.632337e-04 ... 1.5272264e-03 -1.4998110e-03 2009-05-02T00:49:31.149 6.632584e-04 ... 1.5193661e-03 -1.5074468e-03 ... ... ... ... ... 2009-05-11T17:58:22.526 1.014493e-03 ... 3.6121816e-03 3.1950327e-03 2009-05-11T17:59:21.376 1.014518e-03 ... 3.6102540e-03 3.1872767e-03 2009-05-11T18:00:20.225 1.014542e-03 ... 3.6083264e-03 3.1795206e-03 2009-05-11T18:01:19.065 1.014567e-03 ... 3.6063993e-03 3.1717657e-03 2009-05-11T18:02:17.923 1.014591e-03 ... 3.6044715e-03 3.1640085e-03 2009-05-11T18:03:16.772 1.014615e-03 ... 3.6025438e-03 3.1562524e-03 2009-05-11T18:04:15.630 1.014640e-03 ... 3.6006160e-03 3.1484952e-03 2009-05-11T18:05:14.479 1.014664e-03 ... 3.5986886e-03 3.1407392e-03 2009-05-11T18:06:13.328 1.014689e-03 ... 3.5967610e-03 3.1329831e-03 2009-05-11T18:07:12.186 1.014713e-03 ... 3.5948332e-03 3.1252259e-03 .. EXAMPLE END .. EXAMPLE START: Slicing TimeSeries Objects Using Index Notation In the same way as for |Table| objects, the various columns and rows of |TimeSeries| objects can be accessed and sliced using index notation:: >>> ts['sap_flux'] # doctest: +REMOTE_DATA >>> ts['time', 'sap_flux'] # doctest: +REMOTE_DATA time sap_flux electron / s Time float32 ----------------------- -------------- 2009-05-02T00:41:40.338 1.0270451e+06 2009-05-02T00:42:39.188 1.0271844e+06 2009-05-02T00:43:38.045 1.0270762e+06 2009-05-02T00:44:36.894 1.0271414e+06 2009-05-02T00:45:35.752 1.0271569e+06 2009-05-02T00:46:34.601 1.0272296e+06 2009-05-02T00:47:33.451 1.0273199e+06 2009-05-02T00:48:32.291 1.0271497e+06 2009-05-02T00:49:31.149 1.0271755e+06 ... ... 2009-05-11T17:58:22.526 1.0234769e+06 2009-05-11T17:59:21.376 1.0234574e+06 2009-05-11T18:00:20.225 1.0238128e+06 2009-05-11T18:01:19.065 1.0243234e+06 2009-05-11T18:02:17.923 1.0244257e+06 2009-05-11T18:03:16.772 1.0248654e+06 2009-05-11T18:04:15.630 1.0250156e+06 2009-05-11T18:05:14.479 1.0254516e+06 2009-05-11T18:06:13.328 1.0254685e+06 2009-05-11T18:07:12.186 1.0259309e+06 >>> ts[0:4] # doctest: +REMOTE_DATA time timecorr ... pos_corr1 pos_corr2 d ... pix pix Time float32 ... float32 float32 ----------------------- ------------- ... -------------- -------------- 2009-05-02T00:41:40.338 6.630610e-04 ... 1.5822421e-03 -1.4463664e-03 2009-05-02T00:42:39.188 6.630857e-04 ... 1.5743829e-03 -1.4540013e-03 2009-05-02T00:43:38.045 6.631103e-04 ... 1.5665225e-03 -1.4616371e-03 2009-05-02T00:44:36.894 6.631350e-04 ... 1.5586632e-03 -1.4692718e-03 .. EXAMPLE END .. EXAMPLE START: Accessing the Time Column in TimeSeries Objects As seen in the previous examples, |TimeSeries| objects have a ``time`` column, which is always the first column. This column can also be accessed using the ``.time`` attribute:: >>> ts.time # doctest: +REMOTE_DATA