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.
- 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
- Stellar rotation -- Generalized Lomb-Scargle (GLS) periodogram
- Transit detection -- Transit Least Squares (TLS) periodogram
- Neighbor check -- Gaia source overlay on cached archival sky images, with optional nearby SIMBAD object labels
- Batch processing --
--each-sectormode, GNU parallel support, and candidate ranking tools - Fast CLI startup -- lazy imports keep
ql --helpunder 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
Requires Python 3.10+. Choose either uv (recommended) or pip below.
uv (recommended)
# 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 notebooksRun commands from a repository installation with uv run, for example
uv run quicklook --help.
pip
# 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 toolsOnce installed, run commands directly, for example quicklook --help or
ql --help.
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.
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 GUIDrop 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
# Restrict TLS period search range
ql run --name TOI-125.01 --period-limits 1 5
# 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 --saveNote: Old-style
-save/-verboseflags and the standaloneread_tls/rank_tlscommands still work via automatic redirect. Underscore flags (--flatten_method) are interchangeable with hyphens (--flatten-method). On headless Linux systems,--saveis required (the CLI detects missing$DISPLAYand exits early unless--saveis set).
fromquicklookimportTessQuickLookql=TessQuickLook(
target_name="WASP-21",
sector=56,
pipeline="SPOC",
flux_type="pdcsap",
verbose=True,
)
fig=ql.plot_tql()
# Access resultsprint(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.
uv run quicklook gui # http://127.0.0.1:5000
uv run quicklook gui --host 0.0.0.0 --port 8080Open 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.
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 guiLeave 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.
ql run --name WASP-21 --save --verbose
The 9-panel figure shows:
| Panel | Content |
|---|---|
| 1 | Raw light curve + trend line |
| 2 | GLS periodogram (stellar rotation period) |
| 3 | Phase-folded light curve at rotation period |
| 4 | Flattened light curve + detected transits |
| 5 | TLS periodogram (orbital period) |
| 6 | TESS aperture + Gaia sources (and optional SIMBAD objects) on archival image |
| 7 | Phase-folded transit (odd/even comparison) |
| 8 | Secondary eclipse check at phase 0.5 |
| 9 | Summary of stellar and companion parameters |
All subcommands are available under either quicklook or the shorter ql alias.
| Command | Description |
|---|---|
quicklook run | Run the full QuickLook pipeline on a target |
quicklook read-tls | Extract TLS results from a directory of .h5 files into a CSV |
quicklook rank-tls | Filter and rank candidates by SDE from the CSV output |
quicklook gui | Launch the web GUI (requires [gui] extra); also available as ql-gui |
Process a list of TIC IDs:
# Generate batch script
cat tic_ids.txt |whileread tic;doecho"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.pdfFull documentation is available at quicklook.readthedocs.io.
See LICENSE for details.