0
# Time Series Analysis
1
2
Comprehensive periodogram analysis for detecting periodic signals in time series data, with specialized algorithms for different types of astrophysical variability.
3
4
## Capabilities
5
6
### Generic Periodogram
7
8
```python { .api }
9
class Periodogram:
10
"""
11
Power spectrum representation with peak detection and analysis tools.
12
13
Attributes:
14
- frequency: astropy.units.Quantity - Frequency array
15
- power: astropy.units.Quantity - Power spectrum values
16
"""
17
18
def __init__(self, frequency, power, **kwargs):
19
"""
20
Initialize periodogram.
21
22
Parameters:
23
- frequency: array-like - Frequency values
24
- power: array-like - Power spectrum values
25
"""
26
27
# Analysis methods
28
def show_properties(self):
29
"""Display statistical properties of the periodogram"""
30
31
def smooth(self, filter_width=0.1):
32
"""Smooth the periodogram using a moving average"""
33
34
def flatten(self):
35
"""Flatten the periodogram by removing red noise trend"""
36
37
# Peak detection properties
38
@property
39
def max_power(self):
40
"""Maximum power value in the periodogram"""
41
42
@property
43
def frequency_at_max_power(self):
44
"""Frequency corresponding to maximum power"""
45
46
@property
47
def period_at_max_power(self):
48
"""Period corresponding to maximum power"""
49
50
# Visualization
51
def plot(self, **kwargs):
52
"""Plot the periodogram"""
53
54
def interact(self, **kwargs):
55
"""Create interactive periodogram widget"""
56
```
57
58
### Lomb-Scargle Periodogram
59
60
```python { .api }
61
class LombScarglePeriodogram(Periodogram):
62
"""
63
Lomb-Scargle periodogram for detecting periodic signals in unevenly sampled data.
64
Optimal for general stellar variability and rotation periods.
65
"""
66
67
@classmethod
68
def from_lightcurve(cls, lc, minimum_frequency=None, maximum_frequency=None,
69
samples_per_peak=5, **kwargs):
70
"""
71
Create Lomb-Scargle periodogram from light curve.
72
73
Parameters:
74
- lc: LightCurve - Input light curve
75
- minimum_frequency: float - Minimum frequency to analyze
76
- maximum_frequency: float - Maximum frequency to analyze
77
- samples_per_peak: int - Frequency sampling density
78
- normalization: str - Power normalization ('standard', 'model', 'log', 'psd')
79
80
Returns:
81
LombScarglePeriodogram object
82
"""
83
84
# Note: Statistical significance methods available in specialized packages
85
# Use astropy.stats or related libraries for false alarm probability estimation
86
```
87
88
### Box Least Squares Periodogram
89
90
```python { .api }
91
class BoxLeastSquaresPeriodogram(Periodogram):
92
"""
93
Box Least Squares periodogram optimized for detecting transiting exoplanets.
94
Searches for box-shaped transit signals.
95
"""
96
97
@classmethod
98
def from_lightcurve(cls, lc, minimum_period=None, maximum_period=None,
99
minimum_n_transit=3, **kwargs):
100
"""
101
Create BLS periodogram from light curve.
102
103
Parameters:
104
- lc: LightCurve - Input light curve
105
- minimum_period: float - Minimum period to search
106
- maximum_period: float - Maximum period to search
107
- minimum_n_transit: int - Minimum number of transits required
108
- duration: float or array - Transit duration(s) to test
109
110
Returns:
111
BoxLeastSquaresPeriodogram object
112
"""
113
114
def get_transit_model(self, period=None, **kwargs):
115
"""
116
Get best-fit transit model.
117
118
Parameters:
119
- period: float - Period for model (uses highest peak if None)
120
121
Returns:
122
LightCurve object with transit model
123
"""
124
125
def compute_stats(self, period=None, **kwargs):
126
"""Compute detailed transit statistics for a given period"""
127
```
128
129
### Folded Light Curve Analysis
130
131
```python { .api }
132
class FoldedLightCurve(LightCurve):
133
"""Light curve folded at a specific period for phase analysis"""
134
135
def plot_river(self, **kwargs):
136
"""
137
Create river plot showing phase evolution over time.
138
Useful for detecting period variations.
139
"""
140
141
def bin(self, bins=None, **kwargs):
142
"""
143
Bin the folded light curve in phase.
144
145
Parameters:
146
- bins: int or array - Number of phase bins or bin edges
147
148
Returns:
149
Binned FoldedLightCurve
150
"""
151
```
152
153
## Usage Examples
154
155
### Basic Periodogram Analysis
156
157
```python
158
import lightkurve as lk
159
160
# Download and process light curve
161
lc = lk.search_lightcurve('KIC 11904151')[0].download()
162
lc = lc.normalize().remove_outliers()
163
164
# Create Lomb-Scargle periodogram
165
pg = lc.to_periodogram(method='lombscargle')
166
167
# Plot and find peaks
168
pg.plot()
169
max_period = pg.period_at_max_power
170
print(f"Strongest peak at {max_period.value:.2f} days")
171
```
172
173
### Transit Search with BLS
174
175
```python
176
# Search for transiting planets
177
bls = lc.to_periodogram(method='bls',
178
minimum_period=0.5,
179
maximum_period=20)
180
181
# Plot BLS periodogram
182
bls.plot()
183
184
# Get transit model for highest peak
185
period = bls.period_at_max_power
186
transit_model = bls.get_transit_model(period=period)
187
188
# Plot original data with model
189
lc.plot(label='Data')
190
transit_model.plot(label='Transit Model')
191
```
192
193
### Custom Frequency Grid
194
195
```python
196
import numpy as np
197
import astropy.units as u
198
199
# Define custom frequency range
200
min_freq = 1 / (30 * u.day)
201
max_freq = 1 / (0.1 * u.day)
202
203
# High-resolution periodogram
204
pg_hires = lc.to_periodogram(method='lombscargle',
205
minimum_frequency=min_freq,
206
maximum_frequency=max_freq,
207
samples_per_peak=10)
208
```
209
210
### Folding and Phase Analysis
211
212
```python
213
# Fold at detected period
214
folded = lc.fold(period=2.45 * u.day)
215
folded.plot()
216
217
# Bin for cleaner view
218
folded_binned = folded.bin(bins=50)
219
folded_binned.plot()
220
221
# River plot to check period stability
222
folded.plot_river()
223
```
224
225
### Multi-Harmonic Analysis
226
227
```python
228
# Look for harmonics of main period
229
main_period = 5.2 * u.day
230
harmonics = [main_period / n for n in [1, 2, 3, 4]]
231
232
for i, period in enumerate(harmonics):
233
folded = lc.fold(period=period)
234
folded.plot(label=f'P/{i+1}')
235
```
236
237
### Peak Significance Analysis
238
239
```python
240
# Analyze peak significance using power values
241
max_power = pg.max_power
242
mean_power = pg.power.mean()
243
power_ratio = max_power / mean_power
244
print(f"Peak power ratio: {power_ratio:.1f}")
245
print(f"Maximum power: {max_power:.3f}")
246
```
247
248
### BLS Transit Fitting
249
250
```python
251
# Detailed transit analysis
252
stats = bls.compute_stats(period=period)
253
print(f"Transit depth: {stats['depth']:.1f} ppm")
254
print(f"Transit duration: {stats['duration']:.2f} hours")
255
print(f"Signal-to-noise: {stats['snr']:.1f}")
256
257
# Get individual transit times
258
transit_times = bls.transit_times(period=period)
259
```
260
261
### Comparing Different Methods
262
263
```python
264
# Compare LS and BLS for same data
265
ls_pg = lc.to_periodogram(method='lombscargle')
266
bls_pg = lc.to_periodogram(method='bls')
267
268
# Plot both
269
import matplotlib.pyplot as plt
270
fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 8))
271
272
ls_pg.plot(ax=ax1, title='Lomb-Scargle')
273
bls_pg.plot(ax=ax2, title='Box Least Squares')
274
```