AGENT SKILL

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:

  1. Initial search finds candidate at ~3.2 days
  2. Refine by searching narrower range (e.g., 3.0-3.4 days)
  3. 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 * 2 also 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:

  1. Data quality: Filter by quality flags before analysis
  2. Preprocessing order: Remove outliers → flatten/detrend → search for transits
  3. Initial search: Use broad period range to find candidates
  4. Refinement: Narrow search around candidates for better precision
  5. 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

  1. Initial broad search: Use TLS with default or wide period range
  2. Identify candidate: Find period with highest SDE
  3. Refine period: Narrow search around candidate period (±5%)
  4. Mask transits: Remove data points during transits
  5. 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