transit-least-squares
Transit Least Squares (TLS) algorithm for detecting exoplanet transits in light curves. Use when searching for transiting exoplanets specifically, as TLS is more sensitive than Lomb-Scargle for transit-shaped signals. Based on the transitleastsquares Python package.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- transit-least-squares
- description
- Transit Least Squares (TLS) algorithm for detecting exoplanet transits in light curves. Use when searching for transiting exoplanets specifically, as TLS is more sensitive than Lomb-Scargle for transit-shaped signals. Based on the transitleastsquares Python package.
03 SKILL.md 正文
Transit Least Squares (TLS)
Transit Least Squares is a specialized algorithm optimized for detecting exoplanet transits in light curves. It's more sensitive than Lomb-Scargle for transit-shaped signals because it fits actual transit models.
Overview
TLS searches for periodic transit-like dips in brightness by fitting transit models at different periods, durations, and epochs. It's the preferred method for exoplanet transit detection.
Installation
pip install transitleastsquares
Basic Usage
CRITICAL: Always include flux_err (flux uncertainties) for best results!
import transitleastsquares as tls
import lightkurve as lk
import numpy as np
# Example 1: Using Lightkurve (recommended)
lc = lk.LightCurve(time=time, flux=flux, flux_err=error)
lc_clean = lc.remove_outliers(sigma=3)
lc_flat = lc_clean.flatten()
# Create TLS object - MUST include flux_err!
pg_tls = tls.transitleastsquares(
lc_flat.time.value, # Time array
lc_flat.flux.value, # Flux array
lc_flat.flux_err.value # Flux uncertainties (REQUIRED!)
)
# Search for transits (uses default period range if not specified)
out_tls = pg_tls.power(
show_progress_bar=False, # Set True for progress tracking
verbose=False
)
# Extract results
best_period = out_tls.period
period_uncertainty = out_tls.period_uncertainty
t0 = out_tls.T0 # Transit epoch
depth = out_tls.depth # Transit depth
snr = out_tls.snr # Signal-to-noise ratio
sde = out_tls.SDE # Signal Detection Efficiency
print(f"Best period: {best_period:.5f} ± {period_uncertainty:.5f} days")
print(f"Transit epoch (T0): {t0:.5f}")
print(f"Depth: {depth:.5f}")
print(f"SNR: {snr:.2f}")
print(f"SDE: {sde:.2f}")
Example 2: With explicit period range
# Search specific period range
out_tls = pg_tls.power(
period_min=2.0, # Minimum period (days)
period_max=7.0, # Maximum period (days)
show_progress_bar=True,
verbose=True
)
Period Refinement Strategy
Best Practice: Broad search first, then refine for precision.
Example workflow:
- Initial search finds candidate at ~3.2 days
- Refine by searching narrower range (e.g., 3.0-3.4 days)
- Narrower range → finer grid → better precision
Why? Initial searches use coarse grids (fast). Refinement uses dense grid in small range (precise).
# After initial search finds a candidate, narrow the search:
results_refined = pg_tls.power(
period_min=X, # e.g., 90% of candidate
period_max=Y # e.g., 110% of candidate
)
Typical refinement window: ±2% to ±10% around candidate period.
Advanced Options
For very precise measurements, you can adjust:
oversampling_factor: Finer period grid (default: 1, higher = slower but more precise)duration_grid_step: Transit duration sampling (default: 1.1)T0_fit_margin: Mid-transit time fitting margin (default: 5)
Advanced Parameters
oversampling_factor: Higher values give finer period resolution (slower)duration_grid_step: Step size for transit duration grid (1.01 = 1% steps)T0_fit_margin: Margin for fitting transit epoch (0 = no margin, faster)
Phase-Folding
Once you have a period, TLS automatically computes phase-folded data:
# Phase-folded data is automatically computed
folded_phase = out_tls.folded_phase # Phase (0-1)
folded_y = out_tls.folded_y # Flux values
model_phase = out_tls.model_folded_phase # Model phase
model_flux = out_tls.model_folded_model # Model flux
# Plot phase-folded light curve
import matplotlib.pyplot as plt
plt.plot(folded_phase, folded_y, '.', label='Data')
plt.plot(model_phase, model_flux, '-', label='Model')
plt.xlabel('Phase')
plt.ylabel('Flux')
plt.legend()
plt.show()
Transit Masking
After finding a transit, mask it to search for additional planets:
from transitleastsquares import transit_mask
# Create transit mask
mask = transit_mask(time, period, duration, t0)
lc_masked = lc[~mask] # Remove transit points
# Search for second planet
pg_tls2 = tls.transitleastsquares(
lc_masked.time,
lc_masked.flux,
lc_masked.flux_err
)
out_tls2 = pg_tls2.power(period_min=2, period_max=7)
Interpreting Results
Signal Detection Efficiency (SDE)
SDE is TLS's measure of signal strength:
- SDE > 6: Strong candidate
- SDE > 9: Very strong candidate
- SDE < 6: Weak signal, may be false positive
Signal-to-Noise Ratio (SNR)
- SNR > 7: Generally considered reliable
- SNR < 7: May need additional validation
Common Warnings
TLS may warn: "X of Y transits without data. The true period may be twice the given period."
This suggests:
- Data gaps may cause period aliasing
- Check if
period * 2also shows a signal - The true period might be longer
Model Light Curve
TLS provides the best-fit transit model:
# Model over full time range
model_time = out_tls.model_lightcurve_time
model_flux = out_tls.model_lightcurve_model
# Plot with data
import matplotlib.pyplot as plt
plt.plot(time, flux, '.', label='Data')
plt.plot(model_time, model_flux, '-', label='Model')
plt.xlabel('Time [days]')
plt.ylabel('Flux')
plt.legend()
plt.show()
Workflow Considerations
When designing a transit detection pipeline, consider:
- Data quality: Filter by quality flags before analysis
- Preprocessing order: Remove outliers → flatten/detrend → search for transits
- Initial search: Use broad period range to find candidates
- Refinement: Narrow search around candidates for better precision
- Validation: Check SDE, SNR, and visual inspection of phase-folded data
Typical Parameter Ranges
- Outlier removal: sigma=3-5 (lower = more aggressive)
- Period search: Match expected orbital periods for your target
- Refinement window: ±2-10% around candidate period
- SDE threshold: >6 for candidates, >9 for strong detections
Multiple Planet Search Strategy
- Initial broad search: Use TLS with default or wide period range
- Identify candidate: Find period with highest SDE
- Refine period: Narrow search around candidate period (±5%)
- Mask transits: Remove data points during transits
- Search for additional planets: Repeat TLS on masked data
Dependencies
pip install transitleastsquares lightkurve numpy matplotlib
References
When to Use TLS vs. Lomb-Scargle
- Use TLS: When specifically searching for exoplanet transits
- Use Lomb-Scargle: For general periodic signals (rotation, pulsation, eclipsing binaries)
TLS is optimized for transit-shaped signals and is typically more sensitive for exoplanet detection.
Common Issues
"flux_err is required"
Always pass flux uncertainties to TLS! Without them, TLS cannot properly weight data points.
Period is 2x or 0.5x expected
Check for period aliasing - the true period might be double or half of what TLS reports. Also check the SDE for both periods.
Low SDE (<6)
- Signal may be too weak
- Try different preprocessing (less aggressive flattening)
- Check if there's a data gap during transits
Robust TESS Input and Activity-Removal Workflow
For an activity-dominated TESS light curve, never run TLS on the raw oscillatory flux. Read the four columns as MJD time, normalized flux, quality flag, and flux uncertainty. Sort by time, retain only quality==0 rows with finite time/flux/uncertainty and strictly positive finite uncertainties, and apply the identical retained-row mask to all three arrays. MJD differences are in days: either pass the MJD values consistently or subtract one reference MJD from time before TLS; do not mix time units or confuse the returned T0 with the orbital period.
Remove isolated instrumental outliers conservatively, then detrend the flux with a robust, transit-preserving baseline whose timescale is longer than the expected transit duration. Do not use a filter so short that it removes transit dips, and avoid fitting obvious candidate dips into the baseline; iterative masking of candidate transit windows is useful. Normalize the detrended flux and propagate the baseline consistently to flux_err. Repeat TLS with several modestly different detrending windows or robust baseline methods, since a stellar-activity peak may disappear or move while a transit period remains stable.
Derive period_min and period_max from the post-filter cadence and observing baseline rather than relying blindly on defaults. The lower bound must be compatible with the sampling and not be implausibly short; the upper bound should generally allow multiple possible events within the baseline. Search a physically plausible duration grid resolved by the cadence and broad enough for the target and searched periods; reject durations shorter than the effective sampling or implausibly large relative to the period. Use a broad search followed by a denser refinement around each promising period.
Candidate Selection and Validation for Active Stars
Treat the highest TLS peak as a candidate, not as an accepted period. Inspect the top several distinct peaks or rerun/refine neighborhoods around them, recording period, SDE, snr, depth, duration, and T0. For each candidate, count separated observed transit events and verify that they have consistent depths, durations, and timing in the unmasked detrended light curve. Phase-fold the data and inspect the morphology and residuals: a valid candidate should show repeated coherent dips rather than a smooth activity waveform, a single edge event, or a gap artifact.
Explicitly compare the candidate with P/2 and 2P (and relevant nearby harmonics), checking odd/even event depths and the number of covered events. Check whether the period is close to a stellar-activity period or its harmonic. Repeat the search under the modest detrending alternatives described above and, when justified, after masking the candidate transit windows; accept only a period whose repeated dips and approximate depth/duration remain stable. Refine the surviving period with a narrow TLS interval, and write that validated orbital period in days rounded to exactly five decimal places, not the transit epoch or an activity period.
04 同仓库更多 Skills
video-frame-extraction
Extract frames from video files and save them as images using OpenCV
openai-vision
Analyze images and multi-frame sequences using OpenAI GPT vision models
image-ocr
Extract text content from images using Tesseract OCR via Python, including structured field extraction from receipts and forms
video-frame-extraction
Extract frames from video files and save them as images using OpenCV
openai-vision
Analyze images and multi-frame sequences using OpenAI GPT vision models
image-ocr
Extract text content from images using Tesseract OCR via Python, including structured field extraction from receipts and forms