0
# Systematics Correction
1

2
Advanced algorithms for removing instrumental systematics and improving photometric precision. Essential for detecting small astrophysical signals by correcting spacecraft-induced noise patterns.
3

4
## Capabilities
5

6
### Pixel Level Decorrelation (PLD)
7

8
```python { .api }
9
class PLDCorrector:
10
    """
11
    Pixel Level Decorrelation for removing systematic noise correlations.
12
    Uses pixel-level data to model and remove instrumental systematics.
13
    """
14
    
15
    def __init__(self, tpf, aperture_mask=None):
16
        """
17
        Initialize PLD corrector.
18
        
19
        Parameters:
20
        - tpf: TargetPixelFile - Target pixel file to correct
21
        - aperture_mask: array-like, optional - Pixel mask for aperture
22
        """
23
    
24
    def correct(self, aperture_mask=None, pld_aperture_mask=None, 
25
               pld_order=1, **kwargs):
26
        """
27
        Perform PLD correction.
28
        
29
        Parameters:
30
        - aperture_mask: array-like - Pixels for photometry
31
        - pld_aperture_mask: array-like - Pixels for PLD regressors  
32
        - pld_order: int - PLD polynomial order (1 or 2)
33
        - cadence_mask: array-like - Time points to include
34
        - sigma: float - Outlier rejection threshold
35
        
36
        Returns:
37
        Corrected LightCurve object
38
        """
39

40
class TessPLDCorrector(PLDCorrector):
41
    """TESS-optimized PLD corrector with mission-specific features"""
42
    
43
    def correct(self, **kwargs):
44
        """TESS-optimized PLD correction with default parameters"""
45
```
46

47
### Cotrending Basis Vector (CBV) Correction
48

49
```python { .api }
50
class CBVCorrector:
51
    """
52
    Cotrending Basis Vector correction using pre-computed systematic trends.
53
    Removes common systematic patterns across multiple targets.
54
    """
55
    
56
    def __init__(self, lc):
57
        """
58
        Initialize CBV corrector.
59
        
60
        Parameters:
61
        - lc: LightCurve - Light curve to correct
62
        """
63
    
64
    def correct(self, cbvs=None, **kwargs):
65
        """
66
        Perform CBV correction.
67
        
68
        Parameters:
69
        - cbvs: CotrendingBasisVectors - CBV object (auto-downloaded if None)
70
        - cbv_indices: list - Which CBV components to use
71
        - alpha: float - Regularization parameter
72
        - interpolate_missing: bool - Interpolate missing CBV data
73
        
74
        Returns:
75
        Corrected LightCurve object
76
        """
77

78
# CBV data containers
79
class CotrendingBasisVectors:
80
    """Generic container for cotrending basis vectors"""
81
    
82
class KeplerCotrendingBasisVectors(CotrendingBasisVectors):
83
    """Kepler-specific CBV implementation"""
84
    
85
class TessCotrendingBasisVectors(CotrendingBasisVectors):
86
    """TESS-specific CBV implementation"""
87

88
# CBV utility functions
89
def load_kepler_cbvs(mission, quarter, channel, **kwargs):
90
    """Load Kepler CBV files from local storage"""
91

92
def load_tess_cbvs(sector, camera, ccd, **kwargs):
93
    """Load TESS CBV files from local storage"""
94

95
def download_kepler_cbvs(mission, quarter, channel, **kwargs):
96
    """Download Kepler CBV files from MAST archive"""
97

98
def download_tess_cbvs(sector, camera, ccd, **kwargs):
99
    """Download TESS CBV files from MAST archive"""
100
```
101

102
### Self Flat Fielding (SFF)
103

104
```python { .api }
105
class SFFCorrector:
106
    """
107
    Self Flat Fielding corrector optimized for K2 data.
108
    Removes systematic effects caused by spacecraft motion.
109
    """
110
    
111
    def __init__(self, tpf):
112
        """
113
        Initialize SFF corrector.
114
        
115
        Parameters:
116
        - tpf: TargetPixelFile - K2 target pixel file
117
        """
118
    
119
    def correct(self, centroid_col=None, centroid_row=None, **kwargs):
120
        """
121
        Perform SFF correction.
122
        
123
        Parameters:
124
        - centroid_col: array-like - Column centroids (auto-computed if None)
125
        - centroid_row: array-like - Row centroids (auto-computed if None)
126
        - polyorder: int - Polynomial order for detrending
127
        - sigma: float - Outlier rejection threshold
128
        - windows: int - Number of windows for local correction
129
        
130
        Returns:
131
        Corrected LightCurve object
132
        """
133
```
134

135
### Design Matrix Framework
136

137
```python { .api }
138
class DesignMatrix:
139
    """
140
    Matrix for linear regression problems in systematics correction.
141
    Provides tools for building and manipulating design matrices.
142
    """
143
    
144
    def __init__(self, df, **kwargs):
145
        """
146
        Initialize design matrix.
147
        
148
        Parameters:
149
        - df: pandas.DataFrame or array-like - Design matrix data
150
        """
151
    
152
    def split(self, row_indices):
153
        """Split design matrix by row indices"""
154
        
155
    def append_constant(self):
156
        """Add constant column to design matrix"""
157
        
158
    def standardize(self):
159
        """Standardize columns to zero mean and unit variance"""
160
        
161
    def plot(self, **kwargs):
162
        """Visualize design matrix structure"""
163

164
class SparseDesignMatrix(DesignMatrix):
165
    """Memory-efficient sparse design matrix for large problems"""
166

167
class DesignMatrixCollection:
168
    """Collection of multiple design matrices"""
169
    
170
class SparseDesignMatrixCollection:
171
    """Collection of sparse design matrices"""
172
```
173

174
### Base Regression Corrector
175

176
```python { .api }
177
class RegressionCorrector:
178
    """
179
    Base class for regression-based systematics correction.
180
    Provides common functionality for linear regression correctors.
181
    """
182
    
183
    def __init__(self, lc):
184
        """Initialize regression corrector with light curve"""
185
    
186
    def correct(self, regressors=None, **kwargs):
187
        """
188
        Perform regression-based correction.
189
        
190
        Parameters:
191
        - regressors: array-like or DesignMatrix - Systematic regressors
192
        - sigma: float - Outlier rejection threshold
193
        - alpha: float - Regularization parameter
194
        
195
        Returns:
196
        Corrected LightCurve object
197
        """
198
```
199

200
## Usage Examples
201

202
### Basic PLD Correction
203

204
```python
205
import lightkurve as lk
206

207
# Download target pixel file
208
search = lk.search_targetpixelfile('K2-18', mission='K2', campaign=5)
209
tpf = search[0].download()
210

211
# Apply PLD correction
212
corrector = lk.PLDCorrector(tpf)
213
corrected_lc = corrector.correct()
214

215
# Compare before and after
216
raw_lc = tpf.to_lightcurve()
217
raw_lc.plot(label='Raw')
218
corrected_lc.plot(label='PLD Corrected')
219
```
220

221
### TESS PLD with Custom Parameters
222

223
```python
224
# TESS-specific PLD correction
225
tess_search = lk.search_targetpixelfile('TOI-715', mission='TESS')
226
tess_tpf = tess_search[0].download()
227

228
# Use TESS-optimized corrector
229
tess_corrector = lk.TessPLDCorrector(tess_tpf)
230
corrected_lc = tess_corrector.correct(pld_order=2, sigma=3)
231

232
# Plot results
233
corrected_lc.plot()
234
```
235

236
### CBV Correction
237

238
```python
239
# Download light curve for CBV correction
240
lc_search = lk.search_lightcurve('KIC 11904151', quarter=4)
241
lc = lc_search[0].download()
242

243
# Apply CBV correction
244
cbv_corrector = lk.CBVCorrector(lc)
245
corrected_lc = cbv_corrector.correct(cbv_indices=[1, 2, 3])
246

247
# Compare results
248
lc.plot(label='Original')
249
corrected_lc.plot(label='CBV Corrected')
250
```
251

252
### Manual CBV Loading
253

254
```python
255
# Load specific CBVs
256
cbvs = lk.load_kepler_cbvs(mission='Kepler', quarter=4, channel=20)
257

258
# Apply with custom settings
259
corrected_lc = cbv_corrector.correct(cbvs=cbvs, alpha=0.1)
260
```
261

262
### K2 SFF Correction
263

264
```python 
265
# K2 data requires SFF correction
266
k2_search = lk.search_targetpixelfile('EPIC 211945201', campaign=2)
267
k2_tpf = k2_search[0].download()
268

269
# Apply SFF correction
270
sff_corrector = lk.SFFCorrector(k2_tpf)
271
corrected_lc = sff_corrector.correct(polyorder=3)
272

273
# Show improvement
274
raw_lc = k2_tpf.to_lightcurve()
275
print(f"Raw CDPP: {raw_lc.estimate_cdpp():.1f} ppm")
276
print(f"Corrected CDPP: {corrected_lc.estimate_cdpp():.1f} ppm")
277
```
278

279
### Custom Design Matrix
280

281
```python
282
import pandas as pd
283
import numpy as np
284

285
# Create custom regressors
286
time = lc.time.value
287
regressors = pd.DataFrame({
288
    'time': time,
289
    'time_squared': time**2,
290
    'sin_component': np.sin(2*np.pi*time/10),
291
    'cos_component': np.cos(2*np.pi*time/10)
292
})
293

294
# Build design matrix
295
dm = lk.DesignMatrix(regressors)
296
dm = dm.standardize().append_constant()
297

298
# Apply regression correction
299
reg_corrector = lk.RegressionCorrector(lc)
300
corrected_lc = reg_corrector.correct(regressors=dm)
301
```
302

303
### Comparing Correction Methods
304

305
```python
306
# Compare different correction methods
307
raw_lc = tpf.to_lightcurve()
308
pld_lc = lk.PLDCorrector(tpf).correct()
309
sff_lc = lk.SFFCorrector(tpf).correct()
310

311
# Plot comparison
312
import matplotlib.pyplot as plt
313
fig, axes = plt.subplots(3, 1, figsize=(12, 10))
314

315
raw_lc.plot(ax=axes[0], title='Raw Light Curve')
316
pld_lc.plot(ax=axes[1], title='PLD Corrected')  
317
sff_lc.plot(ax=axes[2], title='SFF Corrected')
318

319
# Compare precision
320
print(f"Raw CDPP: {raw_lc.estimate_cdpp():.1f} ppm")
321
print(f"PLD CDPP: {pld_lc.estimate_cdpp():.1f} ppm")
322
print(f"SFF CDPP: {sff_lc.estimate_cdpp():.1f} ppm")
323
```
324

325
### Advanced PLD Options
326

327
```python
328
# High-order PLD with custom apertures
329
threshold_mask = tpf.create_threshold_mask(threshold=5)
330
custom_pld_mask = tpf.flux[0] > 100
331

332
corrector = lk.PLDCorrector(tpf)
333
corrected_lc = corrector.correct(
334
    aperture_mask=threshold_mask,
335
    pld_aperture_mask=custom_pld_mask,
336
    pld_order=2,
337
    sigma=4.0
338
)
339
```