QuickLook

quicklook is a Python pipeline that searches for transit signals in TESS light curves. Given a target name, it downloads the light curve, estimates the stellar rotation period, searches for transiting companions using the Transit Least Squares (TLS) algorithm, and produces a publication-ready 9-panel diagnostic figure.

Although quicklook is optimized to find transiting exoplanets, it can also detect eclipsing binaries, variable stars, and other periodic signals.

Features

• Multi-pipeline support -- SPOC, TESS-SPOC, QLP, CDIPS, PATHOS, TGLC, TASOC, T16
• Flux / light-curve type -- PDCSAP or SAP for SPOC; aperture or PSF photometry for TGLC, with an automatic best-quality default
• Automated detrending -- biweight, cosine, median, GP, and other wotan methods with dynamic rotation-aware ($P_{\text{rot}}$) window tuning and adaptive spline density, plus a built-in Notch and LOCoR filter (Rizzuto et al. 2017) that preserve transit shape via a windowed BIC test / rotation-cycle combination instead of dividing it out
• Stellar rotation -- Generalized Lomb-Scargle (GLS) periodogram
• Transit detection & vetting -- Transit Least Squares (TLS) periodogram with advanced vetting flags (depth variance ratio, duration consistency, secondary eclipse SDE, and iterative multi-planet search)
• Neighbor check -- Gaia source overlay on cached archival sky images, with optional nearby SIMBAD object labels
• Batch processing -- --each-sector mode, GNU parallel support, and candidate ranking tools
• Fast CLI startup -- lazy imports keep ql --help under 200 ms
• Headless friendly -- detects missing display and aborts early, or works fully offline with --save
• Web GUI -- Flask-based interface with live progress, job queue, and gallery
• HDF5 output -- full TLS results saved for downstream filtering

Installation

Requires Python 3.10+. Choose either uv (recommended) or pip below.

# Command-line application
uv tool install quicklook-package

# Or install this repository, including development dependencies
uv sync --extra dev

# Optional extras for a repository installation
uv sync --extra gui        # Web GUI
uv sync --extra gpu        # GPU transit search (CUDA 12)
uv sync --extra notebooks  # Jupyter notebooks

# Command-line application
python -m pip install -U quicklook-package

# Optional extras
python -m pip install -U "quicklook-package[gui]"       # Web GUI
python -m pip install -U "quicklook-package[gpu]"       # GPU transit search (CUDA 12)
python -m pip install -U "quicklook-package[notebooks]" # Jupyter notebooks
python -m pip install -U "quicklook-package[dev]"       # Development tools

With the gpu extra installed, QuickLook uses GTLS when a CUDA device is visible and automatically falls back to the standard CPU TLS implementation when GTLS or a GPU is unavailable, or when GPU execution fails to initialize.

Try it on Google Colab

Usage

Command line

A single quicklook command groups every subcommand (the shorter ql alias is equivalent):

uv run quicklook --help       # show commands: run, read-tls, rank-tls, gui
uv run quicklook run --help   # full analysis options
uv run quicklook read-tls --help  # extract TLS results to CSV
uv run quicklook rank-tls --help  # filter and rank candidates
uv run quicklook gui --help   # launch the web GUI

Drop the uv run prefix once the package is installed on your PATH (e.g. quicklook run ... or ql run ...).

# Basic run on the latest TESS sector
ql run --name WASP-21 --save --verbose

# Specific sector and pipeline
ql run --name TOI-125.01 --sector 2 --pipeline qlp

# Custom detrending
ql run --name TOI-125.01 --flatten-method cosine --window-length 0.3

# Notch filter (window length in days) or LOCoR (window-length is the
# rotation period in days; leave it unset to estimate it via GLS)
ql run --name TOI-125.01 --flatten-method notch --window-length 0.5
ql run --name TOI-125.01 --flatten-method locor

# Restrict TLS period search range
ql run --name TOI-125.01 --period-limits 1 5

# Iteratively mask detected transits and re-run TLS to find additional planets.
# Stops when SDE drops below --min-sde-iterative (default 5) or --max-planets
# is reached; saves one periodogram + odd-even PNG and one TLS HDF5 per planet.
ql run --name TOI-125.01 --iterative --min-sde-iterative 6 --max-planets 3 --save

# Run on every available sector
ql run --name TOI-125.01 --each-sector --save

# Run all sectors with 4 parallel workers
ql run --name TOI-125.01 --each-sector -j 4 --save

# Run every available pipeline on the latest sector
ql run --name TOI-125.01 --each-pipeline --save

# TGLC PSF photometry with nearby SIMBAD objects overlaid
ql run --name TOI-125.01 --pipeline tglc --fluxtype psf --show-simbad --save

Note: Old-style -save / -verbose flags and the standalone read_tls / rank_tls commands still work via automatic redirect. Underscore flags (--flatten_method) are interchangeable with hyphens (--flatten-method). On headless Linux systems, --save is required (the CLI detects missing $DISPLAY and exits early unless --save is set).

Python API

from quicklook import TessQuickLook

ql = TessQuickLook(
    target_name="WASP-21",
    sector=56,
    pipeline="SPOC",
    flux_type="pdcsap",
    verbose=True,
)

fig = ql.plot_tql()

# Access results
print(f"Rotation period: {ql.Prot_ls:.2f} days")
print(f"TLS period: {ql.tls_results.period:.4f} days")
print(f"TLS SDE: {ql.tls_results.SDE:.1f}")

For SPOC, flux_type selects "pdcsap" or "sap". For TGLC, the same argument selects the photometry method -- "aperture" or "psf"; any other value (including the default) uses automatic selection of the less-contaminated, lower-scatter light curve. TGLC light curves absent from MAST are extracted locally via effective-PSF (ePSF) photometry.

Web GUI

uv run quicklook gui                       # http://127.0.0.1:5000
uv run quicklook gui --host 0.0.0.0 --port 8080

Open http://127.0.0.1:5000 in your browser. Enter a target, adjust parameters, and click Run QuickLook. Progress is streamed live via WebSocket. Supports single targets, batch submission, and each-sector mode.

Each running job streams its output log live. Finished jobs (done, error, or cancelled) keep a Log button in the queue that reloads their captured output from disk — so you can review what happened even after the job left the live queue or the server restarted.

The Flask debugger is off by default. Pass --debug (or set QUICKLOOK_DEBUG=1) to enable it and the auto-reloader while developing:

uv run quicklook gui --debug
QUICKLOOK_DEBUG=1 uv run quicklook gui

Leave it off on any host other users can reach — the Werkzeug debugger exposes an interactive console to whoever can open the port. The standalone ql-gui command remains available as an alias for quicklook gui.

Output figure

ql run --name WASP-21 --save --verbose

The 9-panel figure shows:

CLI tools

All subcommands are available under either quicklook or the shorter ql alias.

Batch processing

Process a list of TIC IDs:

# Generate batch script
cat tic_ids.txt | while read tic; do
  echo "ql run --name TIC$tic --save --outdir results | tee TIC$tic.log"
done > run_batch.sh

# Run in parallel with GNU parallel
cat run_batch.sh | parallel -j 4

# Extract and rank results
ql read-tls results/
ql rank-tls results/ --output-dir ranked

# Combine ranked plots into a PDF
pip install img2pdf
img2pdf ranked/*.png --output ranked.pdf

Documentation

Full documentation is available at quicklook.readthedocs.io.

License

See LICENSE for details.