1.. _timeseries-data-access: 2 3Accessing Data in Time Series 4***************************** 5 6.. |time_attr| replace:: :attr:`~astropy.timeseries.TimeSeries.time` 7.. |time_bin_start| replace:: :attr:`~astropy.timeseries.BinnedTimeSeries.time_bin_start` 8.. |time_bin_center| replace:: :attr:`~astropy.timeseries.BinnedTimeSeries.time_bin_center` 9.. |time_bin_end| replace:: :attr:`~astropy.timeseries.BinnedTimeSeries.time_bin_end` 10.. |time_bin_size| replace:: :attr:`~astropy.timeseries.BinnedTimeSeries.time_bin_size` 11 12Accessing Data 13============== 14 15.. EXAMPLE START: Accessing Data in Time Series 16 17For the examples in this page, we will consider a sampled time series 18with two data columns — ``flux`` and ``temp``:: 19 20 >>> from astropy import units as u 21 >>> from astropy.timeseries import TimeSeries 22 >>> ts = TimeSeries(time_start='2016-03-22T12:30:31', 23 ... time_delta=3 * u.s, 24 ... data={'flux': [1., 4., 5., 3., 2.] * u.Jy, 25 ... 'temp': [40., 41., 39., 24., 20.] * u.K}, 26 ... names=('flux', 'temp')) 27 28As for |Table|, columns can be accessed by name:: 29 30 >>> ts['flux'] # doctest: +FLOAT_CMP 31 <Quantity [ 1., 4., 5., 3., 2.] Jy> 32 >>> ts['time'] 33 <Time object: scale='utc' format='isot' value=['2016-03-22T12:30:31.000' '2016-03-22T12:30:34.000' 34 '2016-03-22T12:30:37.000' '2016-03-22T12:30:40.000' 35 '2016-03-22T12:30:43.000']> 36 37And rows can be accessed by index:: 38 39 >>> ts[0] 40 <Row index=0> 41 time flux temp 42 Jy K 43 Time float64 float64 44 ----------------------- ------- ------- 45 2016-03-22T12:30:31.000 1.0 40.0 46 47Accessing individual values can then be done either by accessing a column and 48then a row, or vice versa:: 49 50 >>> ts[0]['flux'] # doctest: +FLOAT_CMP 51 <Quantity 1. Jy> 52 53 >>> ts['temp'][2] # doctest: +FLOAT_CMP 54 <Quantity 39. K> 55 56.. EXAMPLE END 57 58.. _timeseries-accessing-times: 59 60Accessing Times 61=============== 62 63.. duplicate example from index.rst 64 65For |TimeSeries|, the ``time`` column can be accessed using the regular column 66access notation, as shown in `Accessing Data`_, but it can also be accessed 67more conveniently using the |time_attr| attribute:: 68 69 >>> ts.time 70 <Time object: scale='utc' format='isot' value=['2016-03-22T12:30:31.000' '2016-03-22T12:30:34.000' 71 '2016-03-22T12:30:37.000' '2016-03-22T12:30:40.000' 72 '2016-03-22T12:30:43.000']> 73 74.. EXAMPLE START: Accessing the Time Column in BinnedTimeSeries 75 76For |BinnedTimeSeries|, we provide three attributes: |time_bin_start|, 77|time_bin_center|, and |time_bin_end|:: 78 79 >>> from astropy.timeseries import BinnedTimeSeries 80 >>> bts = BinnedTimeSeries(time_bin_start='2016-03-22T12:30:31', 81 ... time_bin_size=3 * u.s, n_bins=5) 82 >>> bts.time_bin_start 83 <Time object: scale='utc' format='isot' value=['2016-03-22T12:30:31.000' '2016-03-22T12:30:34.000' 84 '2016-03-22T12:30:37.000' '2016-03-22T12:30:40.000' 85 '2016-03-22T12:30:43.000']> 86 >>> bts.time_bin_center 87 <Time object: scale='utc' format='isot' value=['2016-03-22T12:30:32.500' '2016-03-22T12:30:35.500' 88 '2016-03-22T12:30:38.500' '2016-03-22T12:30:41.500' 89 '2016-03-22T12:30:44.500']> 90 >>> bts.time_bin_end 91 <Time object: scale='utc' format='isot' value=['2016-03-22T12:30:34.000' '2016-03-22T12:30:37.000' 92 '2016-03-22T12:30:40.000' '2016-03-22T12:30:43.000' 93 '2016-03-22T12:30:46.000']> 94 95In addition, the |time_bin_size| attribute can be used to access the bin sizes:: 96 97 >>> bts.time_bin_size # doctest: +SKIP 98 <Quantity [3., 3., 3., 3., 3.] s> 99 100Note that only |time_bin_start| and |time_bin_size| are available as actual 101columns, and |time_bin_center| and |time_bin_end| are computed on the fly. 102 103.. EXAMPLE END 104 105See :ref:`timeseries-times` for more information about changing between 106different representations of time. 107 108Extracting a Subset of Columns 109============================== 110 111.. EXAMPLE START: Extracting a Subset of Columns in TimeSeries 112 113We can create a new time series with just the ``flux`` column by doing:: 114 115 >>> ts['time', 'flux'] 116 <TimeSeries length=5> 117 time flux 118 Jy 119 Time float64 120 ----------------------- ------- 121 2016-03-22T12:30:31.000 1.0 122 2016-03-22T12:30:34.000 4.0 123 2016-03-22T12:30:37.000 5.0 124 2016-03-22T12:30:40.000 3.0 125 2016-03-22T12:30:43.000 2.0 126 127Note that the new columns will be copies (not views) of the original columns. 128We can also create a plain |QTable| by extracting just the ``flux`` and 129``temp`` columns:: 130 131 >>> ts['flux', 'temp'] 132 <QTable length=5> 133 flux temp 134 Jy K 135 float64 float64 136 ------- ------- 137 1.0 40.0 138 4.0 41.0 139 5.0 39.0 140 3.0 24.0 141 2.0 20.0 142 143.. EXAMPLE END 144 145Extracting a Subset of Rows 146=========================== 147 148.. EXAMPLE START: Extracting a Subset of Rows in TimeSeries 149 150|TimeSeries| objects can be sliced by rows, using the same syntax as for |Time|, 151for example:: 152 153 >>> ts[0:2] 154 <TimeSeries length=2> 155 time flux temp 156 Jy K 157 Time float64 float64 158 ----------------------- ------- ------- 159 2016-03-22T12:30:31.000 1.0 40.0 160 2016-03-22T12:30:34.000 4.0 41.0 161 162|TimeSeries| objects are also automatically indexed using the functionality 163described in :ref:`table-indexing`. This provides the ability to access rows and 164a subset of rows using the :attr:`~astropy.timeseries.TimeSeries.loc` and 165:attr:`~astropy.timeseries.TimeSeries.iloc` attributes. 166 167.. EXAMPLE END 168 169.. EXAMPLE START: Slicing TimeSeries by Time 170 171The :attr:`~astropy.timeseries.TimeSeries.loc` attribute can be used to slice 172|TimeSeries| objects by time. For example, the following can be used to extract 173all entries for a given timestamp:: 174 175 >>> from astropy.time import Time 176 >>> ts.loc[Time('2016-03-22T12:30:31.000')] # doctest: +SKIP 177 <Row index=0> 178 time flux temp 179 Jy K 180 Time float64 float64 181 ----------------------- ------- ------- 182 2016-03-22T12:30:31.000 1.0 40.0 183 184Or within a time range:: 185 186 >>> ts.loc['2016-03-22T12:30:30':'2016-03-22T12:30:41'] 187 <TimeSeries length=4> 188 time flux temp 189 Jy K 190 Time float64 float64 191 ----------------------- ------- ------- 192 2016-03-22T12:30:31.000 1.0 40.0 193 2016-03-22T12:30:34.000 4.0 41.0 194 2016-03-22T12:30:37.000 5.0 39.0 195 2016-03-22T12:30:40.000 3.0 24.0 196 197.. EXAMPLE END 198 199Note that in this case we did not specify |Time| — this is not needed if the 200string is an ISO 8601 time string. As for the |QTable| and |Table| class ``loc`` 201attribute, in order to be consistent with `pandas 202<https://pandas.pydata.org/>`_, the last item in the ``loc`` range is inclusive. 203 204Also note that the result will always be sorted by time. Similarly, the 205:attr:`~astropy.timeseries.TimeSeries.iloc` attribute can be used to fetch 206rows from the time series *sorted by time*, so for example, the first two 207entries (by time) can be accessed with:: 208 209 >>> ts.iloc[0:2] 210 <TimeSeries length=2> 211 time flux temp 212 Jy K 213 Time float64 float64 214 ----------------------- ------- ------- 215 2016-03-22T12:30:31.000 1.0 40.0 216 2016-03-22T12:30:34.000 4.0 41.0 217