0
# Asteroseismology
1

2
Specialized tools for analyzing stellar oscillations and deriving fundamental stellar properties from seismic parameters. Enables the study of stellar interiors through observed frequency patterns.
3

4
## Capabilities
5

6
### Core Seismology Class
7

8
```python { .api }
9
class Seismology:
10
    """
11
    Main asteroseismology analysis class for stellar oscillations.
12
    Provides comprehensive tools for seismic analysis and parameter estimation.
13
    """
14
    
15
    def __init__(self, periodogram):
16
        """
17
        Initialize seismology analysis.
18
        
19
        Parameters:
20
        - periodogram: Periodogram - Power spectrum of stellar oscillations
21
        """
22
    
23
    def estimate_numax(self, **kwargs):
24
        """
25
        Estimate frequency of maximum oscillation power (numax).
26
        
27
        Parameters:
28
        - method: str - Estimation method ('acf2d', 'gaussian_fit')
29
        - window_width: float - Frequency window for analysis
30
        
31
        Returns:
32
        SeismologyQuantity with numax estimate and uncertainty
33
        """
34
    
35
    def estimate_deltanu(self, **kwargs):
36
        """
37
        Estimate large frequency separation (deltanu).
38
        
39
        Parameters:
40
        - method: str - Estimation method ('acf2d', 'comb_fit')
41
        - numax: float - Frequency of maximum power (auto-estimated if None)
42
        
43
        Returns:
44
        SeismologyQuantity with deltanu estimate and uncertainty
45
        """
46
    
47
    def diagnose_numax(self, **kwargs):
48
        """Generate diagnostic plots for numax estimation"""
49
    
50
    def diagnose_deltanu(self, **kwargs):
51
        """Generate diagnostic plots for deltanu estimation"""
52
```
53

54
### Seismology Quantity
55

56
```python { .api }
57
class SeismologyQuantity:
58
    """
59
    Specialized Astropy Quantity for seismology measurements.
60
    Stores value, uncertainty, and metadata for seismic parameters.
61
    """
62
    
63
    def __init__(self, value, uncertainty=None, **kwargs):
64
        """
65
        Parameters:
66
        - value: float - Parameter value  
67
        - uncertainty: float - Parameter uncertainty
68
        - method: str - Estimation method used
69
        - diagnostics: dict - Diagnostic information
70
        """
71
```
72

73
### Frequency Estimators
74

75
```python { .api }
76
def estimate_numax_acf2d(periodogram, **kwargs):
77
    """
78
    Estimate frequency of maximum oscillation power using 2D autocorrelation.
79
    
80
    Parameters:
81
    - periodogram: Periodogram - Power spectrum 
82
    - frequency_step: float - Frequency resolution for analysis
83
    - window_width: float - Analysis window width
84
    
85
    Returns:
86
    SeismologyQuantity with numax estimate
87
    """
88

89
def diagnose_numax_acf2d(periodogram, numax=None, **kwargs):
90
    """
91
    Generate diagnostic plots for numax estimation.
92
    
93
    Parameters:
94
    - periodogram: Periodogram - Power spectrum
95
    - numax: float - Numax estimate to highlight
96
    """
97

98
def estimate_deltanu_acf2d(periodogram, numax=None, **kwargs):
99
    """
100
    Estimate large frequency separation using 2D autocorrelation.
101
    
102
    Parameters:
103
    - periodogram: Periodogram - Power spectrum
104
    - numax: float - Frequency of maximum power
105
    - deltanu_min: float - Minimum deltanu to search
106
    - deltanu_max: float - Maximum deltanu to search
107
    
108
    Returns:
109
    SeismologyQuantity with deltanu estimate
110
    """
111

112
def diagnose_deltanu_acf2d(periodogram, deltanu=None, numax=None, **kwargs):
113
    """
114
    Generate diagnostic plots for deltanu estimation.
115
    
116
    Parameters:
117
    - periodogram: Periodogram - Power spectrum
118
    - deltanu: float - Deltanu estimate to highlight  
119
    - numax: float - Numax estimate for context
120
    """
121
```
122

123
### Stellar Parameter Estimators
124

125
```python { .api }
126
def estimate_radius(numax, deltanu, teff):
127
    """
128
    Estimate stellar radius from seismic scaling relations.
129
    
130
    Parameters:
131
    - numax: float or SeismologyQuantity - Frequency of maximum power (μHz)
132
    - deltanu: float or SeismologyQuantity - Large frequency separation (μHz)  
133
    - teff: float - Effective temperature (K)
134
    
135
    Returns:
136
    SeismologyQuantity with radius estimate in solar radii
137
    """
138

139
def estimate_mass(numax, deltanu, teff):
140
    """
141
    Estimate stellar mass from seismic scaling relations.
142
    
143
    Parameters:
144
    - numax: float or SeismologyQuantity - Frequency of maximum power (μHz)
145
    - deltanu: float or SeismologyQuantity - Large frequency separation (μHz)
146
    - teff: float - Effective temperature (K)
147
    
148
    Returns:  
149
    SeismologyQuantity with mass estimate in solar masses
150
    """
151

152
def estimate_logg(numax, deltanu, teff):
153
    """
154
    Estimate surface gravity from seismic scaling relations.
155
    
156
    Parameters:
157
    - numax: float or SeismologyQuantity - Frequency of maximum power (μHz)
158
    - deltanu: float or SeismologyQuantity - Large frequency separation (μHz)
159
    - teff: float - Effective temperature (K)
160
    
161
    Returns:
162
    SeismologyQuantity with log(g) estimate
163
    """
164
```
165

166
## Usage Examples
167

168
### Basic Asteroseismic Analysis
169

170
```python
171
import lightkurve as lk
172
import numpy as np
173

174
# Download high-quality Kepler data for asteroseismology
175
search = lk.search_lightcurve('KIC 11904151', mission='Kepler')
176
lc_collection = search.download_all()
177

178
# Stitch quarters together for long baseline
179
lc = lc_collection.stitch()
180

181
# Prepare for asteroseismology (remove trends, normalize)
182
lc = lc.normalize().remove_outliers()
183

184
# Create high-resolution periodogram for seismology
185
pg = lc.to_periodogram(method='lombscargle',
186
                      minimum_frequency=1,   # μHz
187
                      maximum_frequency=300, # μHz  
188
                      samples_per_peak=10)
189

190
# Initialize seismology analysis
191
seismo = lk.Seismology(pg)
192

193
# Estimate seismic parameters
194
numax = seismo.estimate_numax()
195
deltanu = seismo.estimate_deltanu()
196

197
print(f"Numax: {numax.value:.1f} ± {numax.uncertainty:.1f} μHz")
198
print(f"Delta nu: {deltanu.value:.2f} ± {deltanu.uncertainty:.2f} μHz")
199
```
200

201
### Diagnostic Analysis
202

203
```python
204
# Generate diagnostic plots for parameter estimates
205
seismo.diagnose_numax()
206
seismo.diagnose_deltanu()
207

208
# Or use standalone functions
209
lk.diagnose_numax_acf2d(pg, numax=numax.value)
210
lk.diagnose_deltanu_acf2d(pg, deltanu=deltanu.value, numax=numax.value)
211
```
212

213
### Stellar Parameter Estimation
214

215
```python
216
# Stellar parameters from seismology (requires effective temperature)
217
teff = 5777  # Sun-like temperature in Kelvin
218

219
# Estimate fundamental stellar properties
220
radius = lk.estimate_radius(numax, deltanu, teff)
221
mass = lk.estimate_mass(numax, deltanu, teff)  
222
logg = lk.estimate_logg(numax, deltanu, teff)
223

224
print(f"Stellar radius: {radius.value:.2f} ± {radius.uncertainty:.2f} R_sun")
225
print(f"Stellar mass: {mass.value:.2f} ± {mass.uncertainty:.2f} M_sun")
226
print(f"Surface gravity: {logg.value:.2f} ± {logg.uncertainty:.2f} dex")
227
```
228

229
### Advanced Seismic Analysis
230

231
```python
232
# Custom frequency analysis for detailed mode identification
233
# Focus on p-mode region around numax
234
freq_min = numax.value - 5 * deltanu.value
235
freq_max = numax.value + 5 * deltunu.value
236

237
pg_focused = lc.to_periodogram(
238
    minimum_frequency=freq_min,
239
    maximum_frequency=freq_max,
240
    samples_per_peak=20  # High resolution
241
)
242

243
# Look for individual oscillation modes
244
# Solar-like oscillations have regular frequency spacing
245
mode_frequencies = []
246
for n in range(-10, 11):  # Radial order range
247
    freq = numax.value + n * deltanu.value
248
    if freq_min <= freq <= freq_max:
249
        mode_frequencies.append(freq)
250

251
# Plot periodogram with predicted mode frequencies
252
import matplotlib.pyplot as plt
253
pg_focused.plot()
254
for freq in mode_frequencies:
255
    plt.axvline(freq, color='red', alpha=0.5, linestyle='--')
256
plt.xlabel('Frequency (μHz)')
257
plt.ylabel('Power')
258
plt.title('Predicted Solar-like Oscillation Modes')
259
```
260

261
### Multi-Target Seismic Survey
262

263
```python
264
# Analyze multiple stars for population study
265
targets = ['KIC 11904151', 'KIC 9139151', 'KIC 10068307']
266
seismic_results = []
267

268
for target in targets:
269
    try:
270
        # Download and process
271
        search = lk.search_lightcurve(target, mission='Kepler')
272
        lc = search.download_all().stitch().normalize()
273
        
274
        # Create periodogram
275
        pg = lc.to_periodogram(minimum_frequency=1, maximum_frequency=300)
276
        
277
        # Seismic analysis
278
        seismo = lk.Seismology(pg)
279
        numax = seismo.estimate_numax()
280
        deltanu = seismo.estimate_deltanu()
281
        
282
        # Store results
283
        seismic_results.append({
284
            'target': target,
285
            'numax': numax.value,
286
            'numax_err': numax.uncertainty,
287
            'deltanu': deltanu.value,
288
            'deltanu_err': deltanu.uncertainty
289
        })
290
        
291
        print(f"{target}: numax={numax.value:.1f}±{numax.uncertainty:.1f} μHz, "
292
              f"Δν={deltanu.value:.2f}±{deltanu.uncertainty:.2f} μHz")
293
              
294
    except Exception as e:
295
        print(f"Failed to analyze {target}: {e}")
296

297
# Convert to table for analysis
298
import pandas as pd
299
results_df = pd.DataFrame(seismic_results)
300
print(results_df)
301
```
302

303
### Custom Parameter Estimation
304

305
```python
306
# Use custom scaling relations or literature values
307
def custom_radius_estimate(numax, deltanu, teff, numax_sun=3100, deltanu_sun=135):
308
    """Custom radius scaling relation with different solar reference values"""
309
    radius_ratio = (numax / numax_sun) * (deltanu_sun / deltanu) * np.sqrt(teff / 5777)
310
    return radius_ratio  # in solar units
311

312
# Apply custom scaling
313
custom_radius = custom_radius_estimate(numax.value, deltanu.value, teff)
314
print(f"Custom radius estimate: {custom_radius:.2f} R_sun")
315
```
316

317
### Quality Assessment
318

319
```python
320
# Assess quality of seismic detection
321
def assess_seismic_quality(seismo_result):
322
    """Assess quality of seismic parameter estimation"""
323
    quality_metrics = {}
324
    
325
    # Signal-to-noise ratio
326
    if hasattr(seismo_result, 'snr'):
327
        quality_metrics['snr'] = seismo_result.snr
328
    
329
    # Relative uncertainty
330
    rel_uncertainty = seismo_result.uncertainty / seismo_result.value
331
    quality_metrics['relative_uncertainty'] = rel_uncertainty
332
    
333
    # Quality flag based on uncertainty
334
    if rel_uncertainty < 0.05:
335
        quality_metrics['quality'] = 'Excellent'
336
    elif rel_uncertainty < 0.10:
337
        quality_metrics['quality'] = 'Good'
338
    elif rel_uncertainty < 0.20:
339
        quality_metrics['quality'] = 'Fair'
340
    else:
341
        quality_metrics['quality'] = 'Poor'
342
    
343
    return quality_metrics
344

345
# Assess parameter quality
346
numax_quality = assess_seismic_quality(numax)
347
deltanu_quality = assess_seismic_quality(deltanu)
348

349
print(f"Numax quality: {numax_quality['quality']} "
350
      f"(σ/μ = {numax_quality['relative_uncertainty']:.1%})")
351
print(f"Deltanu quality: {deltanu_quality['quality']} "
352
      f"(σ/μ = {deltanu_quality['relative_uncertainty']:.1%})")
353
```