0
# Core Data Objects
1
2
Light curves and target pixel files are the fundamental data containers in lightkurve, providing comprehensive functionality for time series analysis and visualization.
3
4
## Capabilities
5
6
### Light Curve Classes
7
8
#### Generic Light Curve
9
10
```python { .api }
11
class LightCurve:
12
"""
13
Time series data with time, flux, and flux_err columns.
14
15
Subclass of astropy TimeSeries with guaranteed time, flux, and flux_err columns.
16
"""
17
18
def __init__(self, time=None, flux=None, flux_err=None, **kwargs):
19
"""
20
Initialize a light curve.
21
22
Parameters:
23
- time: astropy.time.Time or array-like - Time values
24
- flux: astropy.units.Quantity or array-like - Flux values
25
- flux_err: astropy.units.Quantity or array-like - Flux uncertainties
26
- **kwargs: Additional columns and metadata
27
"""
28
29
# Time series operations
30
def normalize(self, unit="unscaled"):
31
"""Normalize flux to relative units"""
32
33
def remove_nans(self):
34
"""Remove NaN values from the light curve"""
35
36
def remove_outliers(self, sigma=5, **kwargs):
37
"""Remove statistical outliers using sigma clipping"""
38
39
def flatten(self, window_length=101, **kwargs):
40
"""Remove long-term trends using Savitzky-Golay filter"""
41
42
def fold(self, period, epoch_time=None, **kwargs):
43
"""Fold the light curve at a given period"""
44
45
def bin(self, time_bin_size, **kwargs):
46
"""Bin the light curve to lower time resolution"""
47
48
def append(self, others, **kwargs):
49
"""Append other light curves to this one"""
50
51
# Analysis methods
52
def to_periodogram(self, method='lombscargle', **kwargs):
53
"""Create a periodogram from the light curve"""
54
55
def to_corrector(self, method='pld', **kwargs):
56
"""Create corrector object for systematics removal"""
57
58
def estimate_cdpp(self, transit_duration=13, savgol_window=101, sigma=5):
59
"""Estimate Combined Differential Photometric Precision"""
60
61
def search_neighbors(self, limit=None, radius=None):
62
"""Search for nearby targets in the same observations"""
63
64
def query_solar_system_objects(self, **kwargs):
65
"""Identify potential solar system object contamination"""
66
67
# Visualization
68
def plot(self, **kwargs):
69
"""Plot the light curve"""
70
71
def scatter(self, **kwargs):
72
"""Create a scatter plot of the light curve"""
73
74
def errorbar(self, **kwargs):
75
"""Create error bar plot of the light curve"""
76
77
def interact(self, **kwargs):
78
"""Create an interactive plot widget"""
79
```
80
81
#### Mission-Specific Light Curves
82
83
```python { .api }
84
class KeplerLightCurve(LightCurve):
85
"""Kepler light curve with mission-specific methods and metadata"""
86
87
@classmethod
88
def read(cls, filename, **kwargs):
89
"""Read Kepler light curve from FITS file"""
90
91
class TessLightCurve(LightCurve):
92
"""TESS light curve with mission-specific methods and metadata"""
93
94
@classmethod
95
def read(cls, filename, **kwargs):
96
"""Read TESS light curve from FITS file"""
97
98
class FoldedLightCurve(LightCurve):
99
"""Light curve folded at a specific period for phase analysis"""
100
101
def plot_river(self, **kwargs):
102
"""Create a river plot showing phase evolution"""
103
```
104
105
### Target Pixel File Classes
106
107
#### Generic Target Pixel File
108
109
```python { .api }
110
class TargetPixelFile:
111
"""
112
Abstract base class for pixel-level time series data.
113
Contains 3D array of pixels over time plus metadata.
114
"""
115
116
# Data access properties
117
@property
118
def time(self):
119
"""Time array for the observations"""
120
121
@property
122
def flux(self):
123
"""3D flux array (time, row, column)"""
124
125
@property
126
def flux_err(self):
127
"""3D flux error array (time, row, column)"""
128
129
@property
130
def pos_corr1(self):
131
"""Position correction in first axis"""
132
133
@property
134
def pos_corr2(self):
135
"""Position correction in second axis"""
136
137
# Light curve extraction
138
def to_lightcurve(self, aperture_mask=None, **kwargs):
139
"""
140
Extract light curve using specified aperture.
141
142
Parameters:
143
- aperture_mask: array-like, str, or callable - Pixel selection method
144
145
Returns:
146
LightCurve object
147
"""
148
149
# Visualization
150
def plot(self, ax=None, frame=0, **kwargs):
151
"""Plot a single frame of the target pixel file"""
152
153
def animate(self, **kwargs):
154
"""Create an animation of the pixel data over time"""
155
156
def interact(self, **kwargs):
157
"""Create interactive pixel selection widget"""
158
159
# Analysis
160
def create_threshold_mask(self, threshold=3, reference_pixel=None):
161
"""Create aperture mask based on flux threshold"""
162
163
def estimate_centroids(self, **kwargs):
164
"""Estimate centroid positions for each frame"""
165
166
def estimate_background(self, **kwargs):
167
"""Estimate background flux for each frame"""
168
169
def cutout(self, size=5, **kwargs):
170
"""Create smaller cutout from target pixel file"""
171
172
def extract_aperture_photometry(self, aperture_mask, **kwargs):
173
"""Perform aperture photometry with specified mask"""
174
175
def to_corrector(self, method='pld', **kwargs):
176
"""Create corrector object for systematics removal"""
177
```
178
179
#### Mission-Specific Target Pixel Files
180
181
```python { .api }
182
class KeplerTargetPixelFile(TargetPixelFile):
183
"""Kepler target pixel file with mission-specific functionality"""
184
185
@property
186
def quality_bitmask(self):
187
"""Kepler quality flags bitmask"""
188
189
def correct(self, method='sff', **kwargs):
190
"""Apply systematics correction to pixel data"""
191
192
@classmethod
193
def read(cls, filename, **kwargs):
194
"""Read Kepler target pixel file from FITS"""
195
196
class TessTargetPixelFile(TargetPixelFile):
197
"""TESS target pixel file with mission-specific functionality"""
198
199
@property
200
def quality_bitmask(self):
201
"""TESS quality flags bitmask"""
202
203
def interact_sky(self, **kwargs):
204
"""Interactive sky view with Gaia overlay"""
205
206
@classmethod
207
def read(cls, filename, **kwargs):
208
"""Read TESS target pixel file from FITS"""
209
```
210
211
### Data Collections
212
213
```python { .api }
214
class LightCurveCollection:
215
"""Collection of multiple light curves with batch operations"""
216
217
def __init__(self, lightcurves):
218
"""Initialize collection from list of LightCurve objects"""
219
220
def stitch(self, **kwargs):
221
"""Combine multiple light curves into single LightCurve"""
222
223
def normalize(self, **kwargs):
224
"""Normalize all light curves in the collection"""
225
226
def remove_outliers(self, **kwargs):
227
"""Remove outliers from all light curves"""
228
229
def plot(self, **kwargs):
230
"""Plot all light curves together"""
231
232
class TargetPixelFileCollection:
233
"""Collection of multiple target pixel files with batch operations"""
234
235
def __init__(self, tpfs):
236
"""Initialize collection from list of TargetPixelFile objects"""
237
238
def to_lightcurve(self, **kwargs):
239
"""Extract light curves from all TPFs"""
240
241
def plot(self, **kwargs):
242
"""Plot all target pixel files"""
243
```
244
245
## Usage Examples
246
247
### Basic Light Curve Operations
248
249
```python
250
import lightkurve as lk
251
import astropy.units as u
252
253
# Create light curve from arrays
254
import numpy as np
255
time = np.linspace(0, 10, 1000)
256
flux = 1 + 0.01 * np.sin(2 * np.pi * time / 2.5) # 2.5-day period
257
lc = lk.LightCurve(time=time, flux=flux)
258
259
# Basic processing
260
lc = lc.normalize().remove_outliers()
261
262
# Fold at known period
263
folded = lc.fold(period=2.5 * u.day)
264
folded.plot()
265
```
266
267
### Target Pixel File Analysis
268
269
```python
270
# Download TPF and create custom apertures
271
search = lk.search_targetpixelfile('Kepler-10')
272
tpf = search[0].download()
273
274
# Visualize pixels
275
tpf.plot()
276
277
# Create different aperture masks
278
threshold_mask = tpf.create_threshold_mask(threshold=5)
279
custom_mask = tpf.flux[0] > 1000 # Custom threshold
280
281
# Extract light curves with different apertures
282
lc_threshold = tpf.to_lightcurve(aperture_mask=threshold_mask)
283
lc_custom = tpf.to_lightcurve(aperture_mask=custom_mask)
284
```
285
286
### Working with Collections
287
288
```python
289
# Download multiple quarters/sectors
290
search = lk.search_lightcurve('KIC 11904151', quarter=[4, 5, 6, 7])
291
collection = search.download_all()
292
293
# Process entire collection
294
collection = collection.normalize().remove_outliers()
295
296
# Stitch together into single light curve
297
long_lc = collection.stitch()
298
299
# Plot all quarters together
300
collection.plot()
301
```
302
303
### Quality Filtering
304
305
```python
306
# Apply different quality filters
307
lc_default = search[0].download(quality_bitmask='default')
308
lc_hard = search[0].download(quality_bitmask='hard')
309
lc_custom = search[0].download(quality_bitmask=1024) # Custom bitmask
310
```