Exoplanet Transit Detector

Full differential-photometry pipeline for ground-based exoplanet transit detection and variable-star monitoring — calibration, alignment, ensemble photometry, Lomb-Scargle + BLS period search, phase folding, SIMBAD/VSX identification, and AAVSO-compliant export in single or multi-band form.

1. The two modes

At the top of the dialog, pick which stage you're starting from:

Mode switching shows and hides the relevant controls. Raw mode exposes the master-dark / master-flat loaders and calibration button; aligned mode hides them because the frames are assumed already-processed.

2. Loading frames

Both modes present a multi-select file picker (FITS, FIT, XISF, TIFF, TIF supported). Files are read in parallel for header metadata, then sorted chronologically before loading pixel data. The time parsing hierarchy is:

1. UT-OBS if present (already in UTC)
2. DATE-OBS (treated as ISO-UTC; timezone offsets like -0700 are auto-normalized to -07:00)
3. DATE-END as fallback
4. MJD-OBS as the most robust final fallback

XISF files have their FITSKeywords block queried for the same keys. Any frame that fails to parse a time ends up at the end of the sort, after all time-stamped frames. The resulting ordered list drives everything downstream — the light curve x-axis, the reference frame selection, and the AAVSO JD field.

Each loaded frame also harvests two more fields:

• Exposure time from EXPOSURE or EXPTIME. Needed for AAVSO export (per-frame integration).
• Airmass from AIRMASS directly, or computed from altitude keys (OBJCTALT, ALT, ALTITUDE, EL) via X = 1/sin(h). Defaults to 1.0 if nothing is found.

3. Calibration (Raw mode)

In Raw mode, two buttons let you load Master Dark and Master Flat files. Status labels flip from ❌ to ✅ when a master is successfully loaded. The dark and flat shapes must be compatible (after binning); mismatches surface as a warning and refuse the load. Both masters are themselves 2× 2 binned on load so they align with the (binned) light frames.

Calibrate & Align Subs runs the full raw-to-aligned conversion on every loaded frame:

1. Subtract master dark (if loaded).
2. Divide by master flat (if loaded) via Numba-accelerated per-pixel division.
3. Expand mono to RGB-equivalent if the input is 2D.
4. Use the first processed frame as the reference, then astroalign-align every subsequent frame to it with an affine transform. See Stellar Alignment for the alignment engine details.

Save Aligned Frames writes the calibrated and aligned stack back to disk — useful if you want to inspect intermediate frames or feed them to a different downstream tool.

4. The Settings dialog (wrench icon)

The orange wrench button at top-right opens the full configuration panel, organized into three sections:

5. Measure & Photometry — the main pipeline

Once frames are loaded (and calibrated if raw), Measure & Photometry runs the full detection, aperture photometry, plate-solving, and ensemble normalization pipeline. In aligned mode, Load, Measure & Photometry combines the load and run into one click.

Progress updates stream in real-time. The pipeline:

1. Pass 1: SEP detection on every frame in parallel (80% of CPU cores). Measures star count, mean background, FWHM, and ellipticity per frame.
2. Picks the best reference frame by quality metric (highest star count / FWHM / background).
3. Plate-solves the reference frame to establish WCS. If a WCS already exists in the header, you're asked whether to use it or re-solve. XISF files always get re-solved because the embedded WCS is PixInsight's TPS approximation and can be off by 10-30" at frame corners.
4. Filters the reference-frame SEP catalog to the interior (dropping stars within the border fraction).
5. Pass 2: aperture + annulus photometry on every star across every frame, with per-star adaptive apertures based on each star's own FWHM in the reference.
6. Ensemble normalization — each star's light curve is divided by the median flux of its k nearest-flux companions.
7. Detrending (if configured) and 2σ outlier flagging.
8. Drops stars with fewer than 75% good frames.
9. For OSC color inputs, runs a supplementary per-channel R/G/B photometry pass.
10. Populates the star list and opens the overlay dialog.

6. The reference overlay

A second window appears showing the reference frame with every detected star circled. Click any circle to select that star in the main dialog's list. Shift-click adds to the selection. Click the main-dialog list and watch the overlay highlight update in real time (red = currently selected, yellow = flagged for dip, blue = normal).

7. The star list and light curve plot

Each detected star appears in the left-column list showing its index, x,y pixel position, median relative flux, and the reference-frame FWHM. Click one or more entries (Ctrl-click to multi-select) and the right-side plot updates with the selected light curves in distinct colors.

The plot shows:

• Raw points (translucent, flux-colored dots) — the per-frame relative-flux measurements, with flagged frames omitted.
• Moving average line (dashed, matching color) — a 5-frame boxcar average, giving a smoothed view of the trend.

The x-axis shows hours since first observation when timestamps are available, or frame index when they aren't. Segments separated by gaps larger than one hour are plotted as separate connected regions, preventing fake "transit" shapes from being drawn across nightly gaps.

8. Detrending

The Detrend combo in the top-right offers three options:

• No Detrend — raw relative-flux curves.
• Linear — divide each curve by its best-fit line. Removes slow systematic trends from airmass change, mild transparency drift, or focus changes across the night.
• Quadratic (default) — divide each curve by its best-fit parabola. Captures the typical "frown" from early-rising + late-setting airmass trajectories across a long observing session.

Detrending happens on each star's light curve independently, after ensemble normalization. The curves are then re-centered to unit median so comparisons across stars remain apples-to-apples.

9. Dip detection — threshold and coherence

Transit detection in the main view works via two sliders working together:

Stars that pass both thresholds get highlighted yellow in both the list and the overlay. The status bar reports the count. The design catches real transits while filtering the noise-driven false positives that would otherwise swamp any amateur-sized dataset.

10. Identify Star — SIMBAD / VSX lookup

Select exactly one star, click Identify Star…. The tool projects the star's pixel position through the WCS to RA/Dec, queries SIMBAD within 15" of that position, and returns the best match. For contested regions where multiple catalog entries fall nearby, a scoring system prefers:

• Variable-star otypes (V*, Mi*, EB*, EA*, EW*, RR*, Ce*, dS*, SX*, Sr*, SR*, LP*, LPV, Ir*, Pu*, Ro*, RS*, BY*, Er*, FU*, TT*, Y*O, and more) — +100 to score
• Named catalog designations (V*, V, NSV, HD, HR, HIP, TYC, BD, CD, ASAS, ASASSN, ZTF, OGLE, GSC, PPM, SAO, WDS, WISE) — +30
• Generic Gaia designations (Gaia DR3, DR2, DR1, EDR3) — –30

Angular offset is subtracted from the score as a tiebreaker. If the best SIMBAD match still isn't flagged as variable, a VSX cone search within the same radius looks for a variable-star designation to upgrade to. The result dialog shows the ID, otype, V magnitude, and offset, with a one-click button to open the full SIMBAD page in your browser.

11. Find Star by name

The reverse operation: enter any SIMBAD-resolvable name (e.g. "V336 Aps", "HD 12345", "TYC 9256-617-1", "Gaia DR3 ...") and the tool resolves the name to RA/Dec, projects back through the WCS to detector pixel coordinates, and selects the nearest detected star in the list.

The matching tolerance adapts to the data: it's the maximum of 2× the median FWHM in detector pixels, 10 arcseconds converted to detector pixels using the WCS plate scale, and a 6-pixel floor. If no star is within tolerance, you get a specific diagnostic — "resolves to pixel (X,Y) but closest detected star is N pixels away" — so you know whether SEP dropped the star (faint, border, saturated) or the target isn't in frame at all.

12. Show Ensemble Members

Each star's light curve is normalized against its k nearest-flux comparison stars (default k=10, configurable in Settings). Show Ensemble Members highlights those comparisons in the list in light blue, letting you see which stars are being used as reference for your target. Useful for diagnosing noisy curves — if the "comparisons" are a mix of variable stars and the target itself, the normalization will drag the target toward whatever those are doing.

13. Analyze Star — the period search

Select exactly one star, click Analyze Star…. A tabbed window opens with four panels:

The window title summarizes the result: Analysis: Star #42 | P = 1.4237 d | SDE = 8.3. A detail line underneath shows duration (hours), depth (ppt), SDE, alias penalty, and number of per-night dips detected.

14. Export CSV / FITS

Standard data export of every star's light curve across every frame. The file format follows the dialog's suffix: .csv gets Pandas-formatted CSV with one row per frame, columns for MJD then STAR_i / FLAG_i / STAR_i_RA / STAR_i_DEC per detected star. .fits gets a proper multi-HDU FITS with a LIGHTCURVE table (MJD + per-star flux + flag columns) and a STARS table (index, x, y, RA, Dec per star), plus original-header metadata (OBJECT, TELESCOP, DATE-OBS, EXPTIME, FILTER) and pipeline parameters (SEP threshold, border fraction, reference frame index, median FWHM).

15. Export → AAVSO — the real deliverable

Produces an AAVSO Extended Format text file ready for WebObs submission. This is where the tool stops being an analysis plaything and starts producing data someone else can use. Two export paths:

Single-band export

For mono data or when you want one filter at a time. The flow:

1. Select one target star in the list.
2. Target name auto-resolved via SIMBAD/VSX (editable).
3. AAVSO observer code (persisted across sessions).
4. Submission format (Variable-Star Photometry or Exoplanet Report).
5. Check star auto-identified from the target's ensemble members (first with a known SIMBAD V magnitude). Fallback to manual entry if auto-ID fails.
6. Filter code chosen from the full AAVSO band list (Johnson-Cousins, DSLR, unfiltered CCD, Sloan, Near-IR, narrowband).

Multi-band export (OSC color data)

When OSC per-channel photometry is available, you're offered a one-click option to export all three channels interleaved in a single AAVSO Extended file: TB (Blue), TG (Green standardized to V), TR (Red). This is the biggest workflow win for DSLR / OSC observers: one upload, three bands, standardized against catalog B / V / R magnitudes.

For each band, the calibration pipeline tries three tiers in order:

1. Ensemble zero point (preferred) — requires ≥3 comparison stars with catalog magnitudes in that band. Computes ZP(t) = median_i(V_cat,i + 2.5 log₁₀ F_i(t)) per frame with MAD-based 3σ clipping. Delivers a proper AAVSO ENSEMBLE entry.
2. Single-comparison — when only 1-2 catalog comparisons are available in that band. Picks the brightest of them for best SNR and does classic differential photometry.
3. Check-star fallback — last resort when no catalog comparisons exist in that band. The check star doubles as the comparison; AAVSO can still accept the row but the CMAG and KMAG fields reflect that compromise.

Catalogs are tried in order: MagTool cache (if available from a prior Magnitude Tool session on this frame), APASS DR9 (Johnson V/B + Sloan r'), UCAC4 (same with slightly different coverage). When Sloan r' is used as the R anchor, the NOTES field includes "R anchor = Sloan r' (APASS/UCAC)" so a reviewer knows exactly what was done.

16. Query TESScut

If TESS has observed your target during one of its sectors, click Query TESScut after selecting a star. The tool downloads the target pixel file (10 arcminute cutout centered on the selected RA/Dec), builds a 2.5-pixel-radius circular aperture, extracts the light curve, clips extreme outliers, and shows the normalized flux via Lightkurve. Results are cached locally so re-querying the same target skips the download.

Useful for cross-checking ground-based variability against the much higher-cadence TESS data — if your 20-ppt dip shows up in TESS at the same period, that's independent confirmation; if TESS shows a flat line, your "candidate" is probably your own systematics.

17. Workflow recipes

18. Technical details

Star detection, aperture photometry, ensemble normalization, the period search algorithms, the AAVSO calibration tiers, and the plate-solve integration.

18.1 SEP detection pipeline

Every frame is run through SEP (Barbary 2016, port of SExtractor by Bertin & Arnouts 1996) in parallel across a thread pool sized to 80% of available CPU cores. Per frame:

1. Sigma-clipped background estimation via sigma_clipped_stats on the gray plane.
2. Background subtraction, then SEP background map and RMS map computation.
3. Source extraction with the user's σ threshold (default 5.0), minarea 16, deblending threshold 32.
4. Per-source FWHM via FWHM = 2.3548 · √(a·b) from SEP's semi-axis measurements:

And ellipticity:

Per-frame stats recorded: star count, mean background, median FWHM, median ellipticity.

18.2 Reference frame selection

The best reference frame is chosen by a quality metric:

which rewards frames with many detections, small PSFs, and low background. The frame with highest Q becomes the detection template for the rest of the pipeline — its SEP catalog defines which stars get photometered, its WCS gets plate-solved, and all other frames compute photometry at the positions found here.

18.3 Plate-solving integration

The reference frame goes to the plate solver. Three paths:

• Existing WCS in header, non-XISF, not forcing → user asked whether to use the header WCS (fast) or re-solve (fresh). Default is "yes, use it".
• XISF source → always re-solve. The XISF format embeds a TPS (thin-plate spline) WCS approximation computed by PixInsight that can be off by 10-30 arcseconds at frame corners — too imprecise for star-matching tolerances. SIP and CD/CDELT headers are stripped from the seed, keeping only CRVAL / OBJCTRA / OBJCTDEC / FOCALLEN / XPIXSZ as hints.
• Force blind solve enabled or no existing WCS → straight plate solve from scratch.

The _wcs_bin_factor is tracked throughout: header WCS is full-resolution (so bin_factor = 2 when applied to our binned coordinates), solver WCS is already in binned coordinates (so bin_factor = 1). Every pixel-to-sky conversion downstream respects this.

18.4 Adaptive aperture photometry

Per-star aperture radii adapt to each star's actual FWHM in the reference frame rather than using a global constant. The three radii:

r_ap at 1.5·FWHM captures ~95% of a Gaussian PSF — close to the SNR-optimal aperture (which sits around 1.4·FWHM for a Gaussian + flat sky). r_in at 3·FWHM puts the inner annulus edge well beyond the PSF wings. r_out at 5·FWHM gives enough annulus pixels for a stable median sky estimate.

Per-star FWHM is clamped to [0.5× median, 3× median] to prevent any single bad detection from producing wildly out-of-range apertures.

18.5 Annulus sky subtraction with error propagation

For each (star, frame) pair:

1. sep.sum_circle gives the aperture flux F_ap and uncertainty σ_ap.
2. sep.sum_circann gives the annulus flux F_ann and uncertainty σ_ann.
3. Compute sky-per-pixel from the annulus (median behavior via SEP's robust mode).
4. Subtract the implied sky total from the aperture:

Propagate the uncertainties in quadrature with the aperture-area ratio:

If annulus extraction fails (star near edge, insufficient annulus pixels), the pipeline falls back to the global-background-subtracted aperture flux rather than failing the measurement outright.

18.6 Ensemble normalization

For each target star T, find its k nearest-flux companions (default k=10) based on median flux:

Then divide:

Error propagation per frame:

Finally the whole curve is renormalized to unit median so curves across stars are directly comparable. This is the standard differential-photometry workflow — any multiplicative systematic that affects target and ensemble members similarly (airmass, transparency, mild clouds, focus) cancels in the ratio, leaving astrophysical variability.

18.7 Detrending

Linear or quadratic polynomial fit per curve to the time-indexed flux (after ensemble normalization), then divide out:

The fit respects per-point validity (finite + positive). After detrending, each curve is re-centered to unit median.

18.8 Outlier flagging and star rejection

Per-curve 2σ-MAD outlier flagging:

Flagged points are excluded from downstream plots and period search but kept in the data arrays. Stars with fewer than 75% unflagged frames are dropped entirely from the list — too noisy to be useful.

After dropping, the ensemble_map is remapped from pre-filter to post-filter indices so every downstream reference to "star #N" still points at the right curve.

18.9 Moving average dip detection

A 5-frame boxcar moving average smooths the curve:

The peak excursion from unit median (converted to parts per thousand):

Must exceed the user's dip threshold. Then the coherence check:

Must exceed the Temporal SNR min. Only stars passing both get flagged. The temporal SNR requirement is what makes dip detection useful on real amateur data where per-point scatter is often comparable to the dip magnitudes you're hunting.

18.10 Lomb-Scargle periodogram

Frequency grid from 1/baseline to Nyquist:

Via astropy's LombScargle.autopower with configurable samples-per-peak density (default 10). Peak period marked on the display. Best for sinusoidal variability — pulsators, eclipsing binaries at frequency-doubled signatures, rotational signals.

18.11 BLS pipeline with whitening and alias penalties

Box Least Squares is where the real transit search happens. The pipeline:

1. Clean light curve: sort, positive-only, median-normalize, 6σ upper-outlier clip, re-normalize.
2. Duration grid: linear spacing between min and max duration fractions of the minimum period:

3. BLS with SNR objective, 10× oversampling, min_n_transit = 2.
4. Whiten the raw power spectrum by subtracting a running median:

This removes slow trends in the periodogram baseline that would otherwise dominate SDE calculations.

5. Find the top 12 local maxima in the whitened spectrum. Peaks within 1% of each other in period are merged (same signal at different grid points).
6. For each candidate peak, do a local refinement BLS on a dense grid ±20% around that peak, picking the best SNR point.
7. Compute SDE for each refined candidate:

8. Compute the alias penalty — downweighting periods near 0.5, 1.0, 2.0, 3.0 days (the diurnal cadence aliases that plague ground-based observing):

with tolerance τ = 0.02 (within 2% of an alias).

9. Final adjusted SDE:

The best SDE_adj across all candidates wins. This is the design that prevents the "every ground-based BLS peaks at 1.0 day" problem — a true planetary signal at some real period beats a 1-day sidereal alias even if the raw BLS power at 1.0 day happens to be slightly higher.

18.12 Phase folding and binned curves

At the chosen period P and epoch t₀, fold to [-0.5, +0.5]:

Raw folded points are plotted as grey dots. A sigma-clipped binned curve (adaptive bin width ≈ transit_duration/3) overlays with error bars from MAD-based SEM. A box-model prediction (constant flux outside transit duration, constant depth inside) overlays in red for visual comparison. The transit duration half-phase determines the box width.

18.13 Night dip event detection

Independent of BLS, a per-night dip detector segments the light curve by observational gaps (default > 0.2 days):

where OOT is out-of-transit (segment median of the smoothed curve). Required to be > max(2σ_segment, 0.0008). Transit-shaped dips (down then up) get event entries. Reports per-event center time, depth, SNR, and duration. The summary line in the Analyze window reports the count — if your "candidate" shows 0 night-dip events but has a strong BLS peak, that peak is probably an alias; if it shows 5 events across 5 nights at consistent timing, you've got something real.

18.14 Multi-band R/G/B photometry (OSC inputs)

For color inputs, a secondary photometry pass runs the same aperture math (fixed global aperture from median FWHM, no per-star adaptation needed for color consistency) on each R, G, B channel separately. The result is a 3D array raw_flux_rgb shaped (3, n_stars, n_frames) with corresponding errors. Both are set to None when the input is mono, and the AAVSO exporter falls through to single-band mode.

18.15 AAVSO calibration — ensemble zero point

When ≥3 comparison stars have catalog magnitudes in the target band, compute a per-frame ensemble zero point:

Target magnitude:

The comparison set is first MAD-clipped (robust 3σ on each star's run-median ZP, with a 0.05 mag floor to prevent over-clipping tight ensembles): comparison stars with discrepant catalog magnitudes get dropped before the per-frame ZP is computed. SEM per frame:

Final MERR combines target instrumental uncertainty, ZP SEM, and a systematic floor:

Default floor is 0.10 magnitudes — a defensive estimate of unmodeled systematics (color terms, atmospheric variations, aperture scatter). Can be reduced to 0.05 or 0.0 if you've characterized your rig and know your actual systematic contribution. The ensemble zero point approach is standard practice for professional transit surveys and gives photometric accuracy within 0.01-0.03 magnitudes under good conditions, limited mainly by catalog magnitude accuracy.

18.16 AAVSO calibration — single-comparison fallback

When only 1-2 comparison stars have catalog magnitudes, pick the brightest (highest median flux — best SNR, most stable anchor):

Error propagated through both flux measurements plus systematic floor. The AAVSO row's CNAME field points at the chosen comparison; KMAG field holds the independent check-star value for post-upload sanity checking.

18.17 AAVSO calibration — check-star fallback

Last resort when no comparison stars have catalog magnitudes in the target band. The check star doubles as the comparison. CNAME points at the check star, KMAG field is "na" because there's no independent check anymore. The NOTES field documents the tier used so a reviewer can see exactly what was done.

18.18 SIMBAD / VSX name resolution scoring

Variable-star otype prefixes get +100 to the match score:

Named catalog designations get +30:

Generic Gaia designations get -30:

Angular offset is subtracted (closer wins). This solves a real problem: without scoring, SIMBAD's "nearest match" would often return a Gaia DR3 identifier for a star that's actually catalogued as, say, V336 Aps — Gaia has an entry for literally everything, and a plain nearest-neighbor return pollutes the exported #NAME field. The scoring plus the VSX fallback produces the right answer (the variable-star designation) when one exists.

18.19 Thread parallelism

Both SEP detection (pass 1) and aperture photometry (pass 2) run in parallel across a thread pool sized to 80% of available CPU cores. SEP itself is single-threaded internally so this gives real linear speedup. Per-frame tasks are completely independent (no shared state), so there's no lock contention. On an 8-core machine, a 200-frame session processes in roughly the time it takes one frame × 32 — a 6× speedup over serial execution.