0
# Time Series
1

2
Time series data structures and analysis tools for astronomical time-domain observations.
3

4
## Core Imports
5

6
```python
7
from astropy.timeseries import TimeSeries, BinnedTimeSeries
8
from astropy.timeseries import LombScargle
9
from astropy.timeseries import aggregate_downsample
10
```
11

12
## Capabilities
13

14
### Time Series Data Structures
15

16
Classes for representing time series data with time-aware operations and astronomical data integration.
17

18
```python { .api }
19
class TimeSeries:
20
    """
21
    Base class for time series data.
22
    
23
    Parameters:
24
    - time: Time column (astropy.time.Time)
25
    - data: Additional columns (dict, Table, or None)
26
    - **kwargs: Additional column data
27
    """
28
    def __init__(self, time=None, data=None, **kwargs): ...
29
    
30
    def fold(self, period, epoch_time=None, epoch_phase=0, wrap_phase=None, normalize_phase=False):
31
        """
32
        Fold time series by a given period.
33
        
34
        Parameters:
35
        - period: folding period (Quantity with time units)
36
        - epoch_time: reference time for folding
37
        - epoch_phase: phase at reference time
38
        - wrap_phase: phase range for wrapping
39
        - normalize_phase: whether to normalize phase to [0,1]
40
        
41
        Returns:
42
        TimeSeries: folded time series
43
        """
44
    
45
    def bin_time(self, time_bin_size=None, time_bin_start=None, time_bin_end=None):
46
        """
47
        Bin time series data.
48
        
49
        Parameters:
50
        - time_bin_size: size of time bins
51
        - time_bin_start: start times for bins
52
        - time_bin_end: end times for bins
53
        
54
        Returns:
55
        BinnedTimeSeries: binned time series
56
        """
57
    
58
    @classmethod
59
    def read(cls, filename, format=None, **kwargs):
60
        """Read time series from file."""
61
    
62
    def write(self, filename, format=None, **kwargs):
63
        """Write time series to file."""
64
    
65
    @property
66
    def time(self):
67
        """Time column."""
68

69
class BinnedTimeSeries(TimeSeries):
70
    """
71
    Time series with binned data.
72
    
73
    Parameters:
74
    - time_bin_start: start times for bins
75
    - time_bin_end: end times for bins (optional if time_bin_size given)
76
    - time_bin_size: size of time bins (optional)
77
    - data: additional column data
78
    """
79
    def __init__(self, time_bin_start=None, time_bin_end=None, time_bin_size=None, data=None, **kwargs): ...
80
    
81
    @property
82
    def time_bin_start(self):
83
        """Start times of bins."""
84
    
85
    @property
86
    def time_bin_end(self):
87
        """End times of bins."""
88
    
89
    @property
90
    def time_bin_center(self):
91
        """Center times of bins."""
92
    
93
    @property
94
    def time_bin_size(self):
95
        """Sizes of time bins."""
96
```
97

98
### Periodogram Analysis
99

100
Tools for period detection and frequency analysis in time series data.
101

102
```python { .api }
103
class LombScargle:
104
    """
105
    Lomb-Scargle periodogram for unevenly sampled data.
106
    
107
    Parameters:
108
    - t: observation times
109
    - y: observed values
110
    - dy: uncertainties in y (optional)
111
    - fit_mean: whether to fit mean offset
112
    - center_data: whether to center data around mean
113
    - nterms: number of Fourier terms for multi-term periodogram
114
    """
115
    def __init__(self, t, y, dy=None, fit_mean=True, center_data=True, nterms=1): ...
116
    
117
    def power(self, frequency, normalization='standard', method='auto', method_kwds=None):
118
        """
119
        Compute Lomb-Scargle power at given frequencies.
120
        
121
        Parameters:
122
        - frequency: frequencies to compute power
123
        - normalization: normalization method ('standard', 'model', 'log', 'psd')
124
        - method: computational method ('auto', 'slow', 'fast', 'scipy', 'chi2')
125
        - method_kwds: additional method arguments
126
        
127
        Returns:
128
        array: power at each frequency
129
        """
130
    
131
    def autopower(self, samples_per_peak=5, nyquist_factor=5, minimum_frequency=None, maximum_frequency=None, **kwargs):
132
        """
133
        Compute power at automatically chosen frequencies.
134
        
135
        Parameters:
136
        - samples_per_peak: frequency sampling per peak width
137
        - nyquist_factor: multiple of average Nyquist frequency for max frequency
138
        - minimum_frequency: minimum frequency to consider
139
        - maximum_frequency: maximum frequency to consider
140
        - **kwargs: additional arguments for power()
141
        
142
        Returns:
143
        tuple: (frequency, power) arrays
144
        """
145
    
146
    def false_alarm_probability(self, power, method='baluev'):
147
        """
148
        Compute false alarm probability for given power.
149
        
150
        Parameters:
151
        - power: power values
152
        - method: method for computation ('baluev', 'bootstrap')
153
        
154
        Returns:
155
        array: false alarm probabilities
156
        """
157
    
158
    def false_alarm_level(self, false_alarm_probability, method='baluev'):
159
        """
160
        Compute power level for given false alarm probability.
161
        
162
        Parameters:
163
        - false_alarm_probability: target false alarm probability
164
        - method: method for computation
165
        
166
        Returns:
167
        float: power level
168
        """
169
    
170
    def model(self, t, frequency):
171
        """
172
        Compute best-fit model at given frequency.
173
        
174
        Parameters:
175
        - t: times for model evaluation
176
        - frequency: frequency for model
177
        
178
        Returns:
179
        array: model values
180
        """
181
    
182
    def design_matrix(self, frequency, t=None):
183
        """
184
        Compute design matrix for given frequency.
185
        
186
        Parameters:
187
        - frequency: frequency value
188
        - t: times (default uses fitted times)
189
        
190
        Returns:
191
        array: design matrix
192
        """
193
```
194

195
### Downsampling and Aggregation
196

197
Functions for reducing time resolution and aggregating time series data.
198

199
```python { .api }
200
def aggregate_downsample(time_series, *, time_bin_size=None, time_bin_start=None, n_bins=None, aggregate_func=None):
201
    """
202
    Downsample time series by aggregating into time bins.
203
    
204
    Parameters:
205
    - time_series: input TimeSeries
206
    - time_bin_size: size of time bins
207
    - time_bin_start: start time for first bin
208
    - n_bins: number of bins to create
209
    - aggregate_func: function to aggregate data in each bin
210
    
211
    Returns:
212
    BinnedTimeSeries: downsampled time series
213
    """
214

215
def boxcar_downsample(time_series, *, time_bin_size=None, time_bin_start=None, n_bins=None):
216
    """
217
    Downsample using boxcar (moving average) method.
218
    
219
    Parameters:
220
    - time_series: input TimeSeries
221
    - time_bin_size: size of time bins
222
    - time_bin_start: start time for first bin  
223
    - n_bins: number of bins
224
    
225
    Returns:
226
    BinnedTimeSeries: downsampled time series
227
    """
228
```
229

230
### I/O Operations
231

232
Specialized I/O functions for common astronomical time series formats.
233

234
```python { .api }
235
def kepler_fits_reader(filename):
236
    """
237
    Reader for Kepler FITS time series files.
238
    
239
    Parameters:
240
    - filename: path to Kepler FITS file
241
    
242
    Returns:
243
    TimeSeries: loaded time series
244
    """
245

246
def tess_fits_reader(filename):
247
    """
248
    Reader for TESS FITS time series files.
249
    
250
    Parameters:
251
    - filename: path to TESS FITS file
252
    
253
    Returns:
254
    TimeSeries: loaded time series
255
    """
256
```
257

258
## Usage Examples
259

260
### Basic Time Series Operations
261

262
```python
263
import numpy as np
264
from astropy.time import Time
265
from astropy.timeseries import TimeSeries
266
import astropy.units as u
267

268
# Create time array
269
times = Time('2023-01-01') + np.arange(100) * u.day
270

271
# Create time series with mock data
272
flux = 1 + 0.1 * np.sin(2 * np.pi * np.arange(100) / 10) + 0.05 * np.random.random(100)
273
ts = TimeSeries(time=times, flux=flux)
274

275
print(f"Time series length: {len(ts)}")
276
print(f"Time range: {ts.time[0]} to {ts.time[-1]}")
277
```
278

279
### Period Detection with Lomb-Scargle
280

281
```python
282
from astropy.timeseries import LombScargle
283

284
# Simulate periodic signal with noise
285
t = np.linspace(0, 100, 1000)
286
y = np.sin(2 * np.pi * t / 10) + 0.1 * np.random.normal(size=1000)
287

288
# Create Lomb-Scargle periodogram
289
ls = LombScargle(t, y)
290

291
# Find power at automatically determined frequencies
292
frequency, power = ls.autopower()
293

294
# Find frequency with maximum power
295
best_freq = frequency[np.argmax(power)]
296
best_period = 1 / best_freq
297

298
print(f"Detected period: {best_period:.2f}")
299

300
# Compute false alarm probability
301
fap = ls.false_alarm_probability(power.max())
302
print(f"False alarm probability: {fap:.2e}")
303
```
304

305
### Folding Time Series
306

307
```python
308
# Fold time series by detected period
309
period = 10.0 * u.day
310
folded_ts = ts.fold(period=period)
311

312
print(f"Folded time series length: {len(folded_ts)}")
313
print(f"Phase range: {folded_ts['time'].min()} to {folded_ts['time'].max()}")
314
```
315

316
### Binning Time Series
317

318
```python
319
# Bin time series into daily bins
320
binned_ts = ts.bin_time(time_bin_size=1*u.day)
321

322
print(f"Original length: {len(ts)}")
323
print(f"Binned length: {len(binned_ts)}")
324
```
325

326
### Downsampling
327

328
```python
329
from astropy.timeseries import aggregate_downsample
330

331
# Downsample using mean aggregation
332
downsampled = aggregate_downsample(ts, time_bin_size=5*u.day, 
333
                                  aggregate_func=np.mean)
334

335
print(f"Downsampled to {len(downsampled)} points")
336
```
337

338
## Types
339

340
```python { .api }
341
# Time series types
342
TimeSeries = astropy.timeseries.TimeSeries
343
BinnedTimeSeries = astropy.timeseries.BinnedTimeSeries
344

345
# Periodogram types  
346
LombScargle = astropy.timeseries.LombScargle
347
```