Python framework for asteroseismic analysis of rapidly oscillating Ap (roAp) stars using NASA's TESS mission data. It combines stellar parameters from the TESS Input Catalog with frequency-domain analysis to characterize the physical properties of these rare, magnetically-active A-type pulsators. A Gaia DR3 parallax cross-match is included as an experimental component (see Roadmap).
roAp stars are valuable laboratories for stellar physics:
- Rapid pulsations (5–20 minute periods, 100–5000 µHz) probe deep into stellar interiors
- Strong magnetic fields (1–30 kG) modify oscillation properties and drive mass loss
- A-type classification spans the transition between radiative and convective envelopes
- TESS precision improves detection sensitivity compared to ground-based observations
| Feature | Details |
|---|---|
| Data Access | Automated TESS light curve download & preprocessing (lightkurve) |
| Frequency Analysis | Professional Lomb-Scargle periodogram with SNR > 4 peak detection |
| Seismic Parameters | Large frequency separation (Δν), mode identification, amplitude statistics |
| Stellar Characterization | TIC stellar parameters (T_eff, log g) with uncertainties; experimental Gaia DR3 parallax cross-match |
| Visualization | Publication-quality HR diagrams, periodograms, and light curves |
| Architecture | Modular Python package for reproducibility and collaboration |
roAp-Analysis/
├── README.md
├── LICENSE
├── requirements.txt # Python dependencies
├── environment.yml # Conda environment
├── setup.cfg # Package configuration
│
├── src/roap_analysis/ # Main analysis package
│ ├── __init__.py
│ ├── config.py # Configuration
│ ├── frequency_analysis.py # Frequency analysis, peak detection
│ ├── stellar_params.py # Stellar catalog queries (TIC, Gaia)
│ └── plotting.py # Visualization
│
├── notebooks/
│ └── main.ipynb # Complete analysis pipeline
│
├── scripts/
│ └── download_lightcurves.py # Data download automation
│
├── sequences/ # MESA evolutionary tracks (1.5–2.5 M☉) — in git
│ └── ms0*z019a.dat
│
├── data/ # INPUT DATA (not in git, downloaded separately)
│ └── lightcurves/ # TESS light curves (~70 MB)
│ └── TIC_*.csv
│
├── results/ # OUTPUT (generated by analysis, not in git)
│ ├── tables/
│ │ ├── stellar_catalog.csv
│ │ └── analysis_results.csv
│ └── figures/
│ ├── hr_diagram/
│ ├── periodograms/
│ └── lightcurves/
│
├── docs/
│ └── METHODS.md # Scientific methods documentation
│
├── conftest.py # Makes src/ importable for tests
└── tests/
└── test_frequency_analysis.py
# Clone repository
git clone https://github.com/ak3sit0/roAp-oscilation-analysis.git
cd roAp-oscilation-analysis
# Create environment & install
conda env create -f environment.yml
conda activate roap-analysis
pip install -e .Large data files are not stored in git. Download them automatically:
python scripts/download_lightcurves.pyThis fetches TESS light curves (~70 MB) from MAST and verifies evolutionary models. Creates data/ directory (ignored by git).
jupyter notebook notebooks/main.ipynbThis pipeline generates stellar catalogs, seismic parameters, and visualization plots. First run may take 15–20 minutes (includes data download); subsequent runs are faster (~5 min).
After running the analysis, you'll get these outputs:
Observed targets plotted against MESA evolutionary tracks (masses 1.5–2.5 M☉, solar metallicity). Error bars come from the TESS Input Catalog. The targets fall near the main sequence, consistent with their late-A / early-F effective temperatures and mass estimates.
Power spectrum from Lomb-Scargle periodogram showing significant peaks detected above the SNR > 4 threshold (red peaks). For TIC 101624823 the highest-amplitude peak sits at ~1442 µHz (124.6 d⁻¹); the mean spacing of the significant peaks yields a large frequency separation of Δν ≈ 46 µHz, a characteristic asteroseismic parameter linked to mean stellar density.
Light curve from TESS showing ~100 days of continuous photometry. TESS noise floor is ~20–100 ppm (depending on stellar magnitude and observing sector). Oscillation amplitudes for roAp stars range 0.5–5 ppm, requiring sensitive space-based photometry.
Superimposed amplitude spectra of all analyzed targets, highlighting the frequency ranges where significant peaks are detected across the sample.
| TIC ID | N peaks | ν_dom (µHz) | Δν (µHz) | T_eff (K) | log g |
|---|---|---|---|---|---|
| 101624823 | 544 | 1442 | 45.7 | 6776±132 | 3.83±0.09 |
| 165052884 | 155 | 2177 | 26.4 | 6898±127 | 4.18±0.08 |
| 233200244 | 153 | 1437 | 25.9 | 8218±152 | 4.07±0.07 |
| 158271090 | 147 | 973 | 27.3 | 7387±141 | 3.73±0.09 |
| 298052991 | 185 | 2291 | 21.8 | 7596±125 | 4.31±0.08 |
| 435263600 | 164 | 1097 | 24.8 | — | — |
ν_domis the highest-amplitude peak in the periodogram (may include low-frequency / rotational signal);Δνis the mean spacing of the significant (SNR > 4) peaks.T_effandlog gare from the TESS Input Catalog. Gaia DR3 parallax/luminosity integration is pending (see Roadmap), so those columns are not yet populated.
Generated outputs: results/tables/stellar_catalog.csv and results/tables/analysis_results.csv
from roap_analysis import periodogram_analysis, calculate_large_separation
import lightkurve as lk
# Download and analyze
lc = lk.read("TIC 101624823", mission="TESS").remove_nans().flatten()
pg, peaks, snr = periodogram_analysis(lc, oversample_factor=5)
delta_nu, _ = calculate_large_separation(pg.frequency.value[peaks])
print(f"Large Separation: Δν = {delta_nu:.5f} d⁻¹")
print(f"Detected {len(peaks)} significant modes")Detailed documentation of all methods is in docs/METHODS.md. Below is a summary:
-
Lomb-Scargle Periodogram: Frequency analysis for unevenly-sampled TESS data
- Amplitude normalization in ppm
- 5-fold oversampling for resolution
- See Kjeldsen & Bedding (1995)
-
SNR Peak Detection: Robust noise estimation using Median Absolute Deviation (MAD)
- Threshold: SNR > 4 (>99.99% confidence)
- Filters instrumental artifacts
-
Large Frequency Separation (Δν): Average spacing between consecutive radial modes
- Links directly to mean stellar density
- Typical roAp range: 30–100 µHz
- Calculated from autocorrelation (see METHODS.md for details)
-
Stellar Parameters: Effective temperature and surface gravity with uncertainties
- TIC: T_eff, log g and their catalog errors (primary source)
- Gaia DR3: parallax cross-match for distance/luminosity — experimental, not yet validated for these targets (see Roadmap)
For complete technical documentation: see docs/METHODS.md
- Automated TESS light curve download and preprocessing via lightkurve
- Frequency analysis: Lomb-Scargle periodogram with SNR > 4 peak detection
- Seismic parameter extraction: large frequency separation (Δν) from peak spacing
- Stellar characterization: TIC parameters (T_eff, log g) with errors; experimental Gaia DR3 parallax cross-match
- Visualization: HR diagrams with evolutionary tracks and error bars
- Modular architecture: reproducible, testable Python package
# Conda (recommended)
conda env create -f environment.yml
conda activate roap-analysis
# or with pip
pip install -r requirements.txt- Kurtz (1982) - roAp star discovery - MNRAS 200(4), 807–859
- Kjeldsen & Bedding (1995) - Periodogram methods - A&A 293, 87–106
- Cunha et al. (2007) - Asteroseismic characterization - A&A 474, 901–924
- Ricker et al. (2015) - TESS Mission - J. Astron. Telesc. Instrum. Syst. 1, 014003
- Zwintz et al. (2019) - TESS roAp observations - A&A 627, A28
- Gaia Collaboration (2023) - Gaia DR3 - A&A 674, A1
See notebooks/main.ipynb for complete interactive examples.
from roap_analysis import get_star_params_professional, periodogram_analysis
targets = ["TIC 101624823", "TIC 165052884", "TIC 233200244"]
for tic_id in targets:
lc = lk.read(tic_id, mission="TESS").remove_nans().flatten()
pg, peaks, snr = periodogram_analysis(lc)
params = get_star_params_professional(tic_id, include_gaia=True)
# Process results...Known limitations and planned work:
- Robust TIC → Gaia DR3 cross-match. The current parallax query matches on a
designation LIKEstring and does not reliably resolve Gaia sources, so parallax/luminosity columns are not yet populated. Planned: proper cross-match via the Gaiatic_dr3/tmass_best_neighbourtables or a coordinate cone search, then parallax-based luminosities on the HR diagram. - Mode identification.
Δνis currently the mean spacing of significant peaks; a full échelle-diagram mode identification (l, n) is planned to firm up the roAp classification. - Dominant-frequency filtering.
ν_dommay pick up low-frequency rotational/instrumental signal; a pre-whitening / high-pass step targeting the roAp band (100–5000 µHz) is planned. - Test coverage. Expand beyond the current smoke tests to cover the periodogram and catalog paths.
Contributions are welcome. Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/my-analysis) - Add tests for new functionality
- Submit a pull request with clear description
Run the test suite with:
pip install -e ".[test]"
pytestIf you use this code, please cite:
@software{ake_roap_2026,
author = {Ake, Jos\'e},
title = {roAp-oscilation-analysis: Asteroseismic Analysis Framework for Rapidly Oscillating Ap Stars},
year = {2026},
url = {https://github.com/ak3sit0/roAp-oscilation-analysis},
version = {1.0.0}
}This project is licensed under the MIT License — see LICENSE file.
For questions or suggestions:
- Email: akejja@estudiantes.fisica.unam.mx
- Issues: GitHub Issues
Status: Research codebase (actively maintained)
Last Updated: July 2026