microlensing event finder pipeline

Works with any dataset that has time, magnitude, and magnitude-error columns — column names are fully configurable. File format detection, season splitting, filter handling, and candidate classification all run automatically. (Assumes you already have light curve data downloaded)

---

What it does

Each object's lightcurve is processed through a sequence of stages:

1. Season splitting — gaps larger than SEASON_GAP_DAYS days separate observing seasons
2. Per-season scan — bump detection (rolling SNR) and flatness test (χ²) on every season
3. Best season selection — the season with the highest bump SNR is chosen as the candidate event
4. Veto checks — three independent vetoes remove variable stars:
   • Periodic veto — Lomb-Scargle periodicity in off-event seasons
   • Recurrent veto — significant bumps in multiple seasons (intrinsic variability)
   • Chromatic veto — event is wavelength-dependent (not a true lensing event)
5. PSPL fit — a Point Source Point Lens model is fit to surviving candidates to estimate t₀, u₀, tE, and χ²
6. FFP flag — candidates with tE < FFP_TE_MAX days are flagged as free-floating planet candidates

---

Supported input formats

INPUT_PATH value	How it is handled
"data.parquet"	Single parquet file (may contain many objects via GROUP_COL)
"data.csv" / "data.fits" / "data.txt"	Single table file
"lc/*.txt"	One lightcurve per matched file, no filter pairing
("lc/*_W149.txt", "lc/*_Z087.txt")	Paired per-filter files, matched by filename stem
pd.DataFrame	Already-loaded table passed directly

---

Installation

pip install numpy pandas scipy astropy pyarrow

Clone the repo and place eventfinder.py in your working directory (or on your Python path).

---

Quickstart

from pipeline import load_and_run

config = {
    "time_col":  "bjd",
    "mag_col":   "mag",
    "err_col":   "mag_err",
    "group_col": "name",          # column that identifies each object; None = single object
    "filter_col": "filt",         # None → skip achromatic test
    "target_filter":   "F146",
    "primary_filter":  "F146",
    "secondary_filters": ["F087", "F213"],
}

results_df = load_and_run("data.parquet", config)
print(results_df[results_df["is_candidate"]])

See example_run.ipynb for the full configuration reference, and run cell.

---

Configuration reference

Required

Parameter	Type	Description
time_col	str	Column name for time (e.g. "bjd")
mag_col	str	Column name for magnitude
err_col	str	Column name for magnitude uncertainty

Input / grouping

Parameter	Default	Description
group_col	None	Column identifying each source. None = treat the whole DataFrame as one object
columns	None	Column names for headerless text files. None = file has a header row
sep	r"\s+"	Column separator regex for text files. Use "," for CSV
header	None	None = no header row; 0 = first row is header

Filter options

Parameter	Default	Description
filter_col	None	Column name for filter labels. None → achromatic test is skipped
target_filter	"F146"	Filter used for event detection (primary band)
primary_filter	"F146"	Primary filter for achromatic test
secondary_filters	[]	One band ("F087") or a list (["F087", "F213"]) for achromatic test

Pipeline tuning

Parameter	Default	Description
min_points	10	Minimum data points per season to run analysis
fap_threshold	0.01	False-alarm probability threshold for the periodicity veto
season_gap_days	100	Day gap that separates observing seasons
ffp_tE_max	2.0	Max tE (days) to flag an event as a free-floating planet candidate
good_pspl_chi2	2.5	Reduced χ² threshold for an acceptable PSPL fit
chromatic_min_points	5	Minimum points per filter band for the achromatic test

---

Output columns

Column	Description
name	Object identifier
is_candidate	Passed bump test and all three vetoes
is_ffp_candidate	Candidate with tE < ffp_tE_max days
is_variable_star	Passed bump test but rejected by at least one veto
veto_periodic	Rejected by periodicity veto
veto_recurrent	Rejected by recurrent bump veto
veto_chromatic	Rejected by chromatic veto
is_achromatic	Result of achromatic test (nan = inconclusive)
best_season	Season ID with the highest bump SNR
is_flat	Lightcurve is consistent with a flat baseline
chi2_flat	χ² of flat model fit
dof_flat	Degrees of freedom
chi2_red_flat	Reduced χ² of flat model
bump_flag	Rolling-SNR bump detected
bump_snr	Peak bump SNR
t0_fit	PSPL best-fit peak time (HJD − 2450000)
u0_fit	PSPL best-fit impact parameter
tE_fit	PSPL best-fit Einstein crossing time (days)
chi2_red_pspl	Reduced χ² of PSPL fit
baseline_mag	Median baseline magnitude
peak_mag	Peak (brightest) magnitude

---

File structure

microlensing-pipeline/
├── README.md
├── pipeline.py          ← all functions; import from here
├── example_run.ipynb    ← configuration, run cell, and diagnostics
└── requirements.txt

---