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.
npxskills add benchflow-ai/skillsbench--skill transit-least-squaresLoading…
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.
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.
pip install transitleastsquares
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}")
# 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
)
Best Practice: Broad search first, then refine for precision.
Example workflow:
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.
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)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)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()
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)
SDE is TLS's measure of signal strength:
TLS may warn: "X of Y transits without data. The true period may be twice the given period."
This suggests:
period * 2 also shows a signalTLS 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()
When designing a transit detection pipeline, consider:
pip install transitleastsquares lightkurve numpy matplotlib
TLS is optimized for transit-shaped signals and is typically more sensitive for exoplanet detection.
Always pass flux uncertainties to TLS! Without them, TLS cannot properly weight data points.
Check for period aliasing - the true period might be double or half of what TLS reports. Also check the SDE for both periods.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).