# Plan: do flare and artifact controls improve TESS self-lensing recovery at the same false-alarm rate?

Registered before any light curve of the study's sector was read. The code in `code/` and the environment in `env/` beside this plan are the analysis, run as registered; anything that departs from them will be listed in the bundle's `deviations.json`.

## Question

A searcher looking for self-lensing pulses in TESS light curves (short, symmetric brightenings when a compact companion passes in front of its star) can stop at a lensing-template matched filter, or add explicit controls that throw out candidates looking like stellar flares or instrumental artifacts. Do those controls recover more injected pulses when both methods are held to the same false-alarm rate, and what do they cost?

This answers the idea `idea:5bf7902b740e65b9cd679de4432f8397c0c443482d3bd5aee4916a0bccc5e9e4` and its swarm.

## Data

- **Sector, cadence, product:** TESS sector 2, two-minute cadence, SPOC light curves (PDCSAP flux), as MAST serves them.
- **Population:** stars on the TESS sector 2 two-minute target list (`all_targets_S002_v1.csv`) with 8 ≤ Tmag < 12.
- **Eligibility:** MAST's sector 2 light-curve download script lists the star's SPOC light curve, the file reads with consecutive cadences, and at least half its cadences are good (quality flag 0 and finite PDCSAP flux).
- **Sampling:** rank the population by the SHA-256 of `tess-selflensing-sample:<TIC>`; in rank order, the first 150 eligible stars are the **tuning** stars and the next 150 the **held-out** stars. The idea asked for a 100-light-curve pilot; 300 narrows the intervals at small cost.
- **Flare stars:** stars with at least 3 flares in sector 2 in Günther et al. (2020, AJ 159, 60; VizieR J/AJ/159/60), on the sector 2 target list and not in the random sample, ranked by the SHA-256 of `tess-selflensing-flares:<TIC>`; the first 40 eligible. They test the controls on catalogued, public flares and are used for nothing else.
- `code/select_sample.py fetch` makes the selection once; `verify`, run first by `code/run`, rebuilds it from the target list, MAST's script, the catalogue and the light curves of every star chosen or passed over, and stops if it differs.

## Injections

Each star gets 50 trials, each one copy of its light curve with one synthetic pulse multiplied into the normalized PDCSAP flux **before any preprocessing**, so the whole analysis is tested. Trial parameters come from a generator seeded by the star's TIC:

- **Shape:** a self-lensing pulse of a lens much smaller than its source: the excess flux follows the limb-darkened surface brightness under the lens (quadratic limb darkening, u1 = 0.40, u2 = 0.20), across a chord with impact parameter b uniform on [0, 0.9].
- **Duration:** log-uniform from 2 to 24 hours.
- **Strength:** expected white-noise matched-filter S/N, against the star's own robust scatter, log-uniform from 4 to 60, amplitude capped at 4%.
- **Time:** uniform over the light curve's good span, drawn again until at least half the pulse's cadences are good.
- **Photocentre:** the shift the brightening would bring, s × CROWDSAP × (target position − median centroid), with that offset capped at (1 − CROWDSAP) × 3 pixels, since the rest of it is the PSF's own asymmetry, which a brightening doesn't move.

Each star is also searched as observed (its **null run**). Real self-lensing pulses are rare enough that every null-run candidate counts as a false alarm.

## The two methods

Both share the same preprocessing and search (`code/selflens.py`):

1. Normalize PDCSAP flux; keep cadences with quality flag 0; split into chunks at gaps over 0.2 days; detrend each chunk by a centred 2-day running median (as Yamaguchi & El-Badry 2024 did).
2. Matched-filter the residuals with limb-darkened pulse templates of 2, 3, 4.5, 7, 10.5, 16 and 24 hours, needing half a template's weight on good cadences; divide each duration's S/N series by its own robust spread, so correlated noise counts.
3. Candidates are peaks of the best S/N over durations, strongest first, each masking one duration on either side, kept down to S/N 3.

An injection is **recovered** when a candidate that survives the method lies within max(duration / 2, 1 hour) of the injected centre and reaches the method's threshold.

- **Baseline:** the lensing-template matched filter alone: every candidate counts.
- **With controls:** the same candidates, less those any control vetoes:
  - **Flare shape:** the best flare template (Davenport et al. 2014; half widths from 2 to 240 minutes) fits the event better than the best pulse template by more than Δχ² (equal parameter counts, so Δχ² = S/N²_flare − S/N²_pulse in white-noise units).
  - **Momentum dumps:** the peak lies within h hours of a cadence flagged as a reaction-wheel desaturation.
  - **Chunk edges:** the peak lies within h hours of a chunk's start or end.
  - **Centroid:** the photocentre's matched-filter S/N at the event's time and duration, renormalized as above, exceeds a limit.
  - **Background:** the same for the SAP background, in absolute value.
  - **Common mode:** at least m tuning stars on the same camera (never the star itself) have a null-run candidate of S/N ≥ 6 overlapping the event.

## Tuning (tuning stars only)

The grid is in `code/analyze.py` (6,144 combinations, each control possibly off). For every combination the threshold at each false-alarm rate of 0.05, 0.1 and 0.2 per light curve is set on the tuning stars' null runs (the lowest S/N whose false alarms per light curve don't exceed the rate, never below 3), and tuning picks the combination with the highest mean recovery of tuning injections across the three; ties go to fewer controls on, then to the earlier value in each list. The baseline has nothing to tune.

## Outcomes (held-out stars)

**Primary:** the difference in recovery of held-out injections, controls minus baseline, with each method's threshold set on the held-out stars' null runs at **0.1 false alarms per light curve (one sector)**, the two methods so held to the same false-alarm rate. Its 95% interval comes from a star-level bootstrap (2,000 draws, seed 20261023): stars are resampled with replacement, each keeping its null run and all 50 of its injections, and both thresholds are set again in every draw, so the interval allows for repeated injections in one light curve and for the thresholds' own uncertainty.

- An interval above zero: the controls improve recovery at that rate.
- Below zero: they cost recovery at that rate.
- Spanning zero: no difference this sample can detect; we report the interval as the bounds.

**Secondary,** all on held-out stars unless said:

1. The thresholds the tuning stars set at 0.1, applied unchanged (as a search would run): each method's realized false-alarm rate and recovery, with bootstrap intervals.
2. Recovery of each method across false-alarm rates of 0.02, 0.05, 0.1, 0.2, 0.5 and 1 per light curve, and at 0.1 by injected S/N (4–7, 7–10, 10–15, 15–25, 25–40, 40–60) and duration (2–4, 4–8, 8–16, 16–24 hours).
3. What each chosen control does alone at the baseline's matched threshold (null candidates removed, recovered injections lost), and flare-only and artifact-only versions at the matched rate.
4. On the flare stars at the tuning thresholds: of the catalogued sector 2 flares, how many each method keeps as a candidate, and the share of baseline flare candidates the controls reject; each method's false alarms per light curve and recovery of injections there.
5. The controls at values fixed now, before any data (flare Δχ² 30, dumps 1 h, edges 6 h, centroid 6, background 6, common mode 2), against the baseline at the matched rate, with a bootstrap interval, in case tuning on 150 stars misleads.

## Limits, stated in advance

- Injecting into PDCSAP flux tests our preprocessing and search, not SPOC's own systematics correction.
- One sector and 300 stars: a pilot comparison, not a survey-wide false-alarm rate or a limit on how common self-lensing binaries are.
- Any candidate surviving in the null runs stays unconfirmed: we make no claim that it is astrophysical.
