Feature-based Light-curve Aggregated Ranking Ensemble
A physics-features + gradient-boosted-trees classifier for ZTF photometric transients, with class-conditional conformal uncertainty and an anomaly layer for what falls outside the taxonomy. Calibrated probabilities, guaranteed per-class coverage, interpretable decisions, CPU-minutes to train, plain model files to deploy.
How it works
Engineered physics features plus tree-based ranking, with honest calibration on top.
160 physically-motivated features
Variability statistics, Bazin transient fits, colour evolution and cadence from each multi-band light curve, optionally joined with context available at alert time: Pan-STARRS host photometry, a Legacy-Surveys photo-z pseudo-absolute magnitude, Gaia DR3 and AllWISE point-source context.
LightGBM, six classes
SN Ia · SN CC · SLSN · AGN · TDE · CV as a 5-way top level plus an SLSN head, with versions trained on the first 5, 10 and 20 days of a light curve. External blocks are randomly blanked in training, so a hostless or uncovered object degrades gracefully instead of being misread.
Mondrian conformal sets + anomaly energy
Per object, the set of classes guaranteed to contain the truth with probability ≥ 1−α, per class. Easy objects get one label; genuinely ambiguous ones get a short list for spectroscopic follow-up. An anomaly layer scores what is out of taxonomy, with the base rate that probability assumes.
How it reports
Renderings of genuine per-alert output on real ZTF objects. No invented values anywhere.
FLARE alert console
A triage queue plus the full per-object case: probabilities, the conformal set and the error it admits, anomaly probability with its base rate, and the context that drove the decision. This is how we would want a deployment to report.
Open the console →FLARE inside BOOM
The same content rendered inside BOOM's own design system, as a concrete integration proposal for the broker team. Every token, tile rule and band colour is read from the boom-astro/boom frontend source.
Open the BOOM panel →Example report
What flare report writes: a self-contained HTML page for a handful of
object ids, built from BOOM or public ALeRCE photometry plus per-position context.
Performance
bts6 scheme, five-fold out of fold, 10,497 Bright Transient Survey objects. Each column adds a context block.
| Metric | light curve only | + host | + Gaia/WISE | + PS1 counterpart |
|---|---|---|---|---|
| accuracy | 0.899 ± 0.005 | 0.918 ± 0.005 | 0.922 ± 0.005 | 0.924 ± 0.001 |
| balanced accuracy | 0.713 ± 0.034 | 0.799 ± 0.021 | 0.811 ± 0.026 | 0.826 ± 0.033 |
| macro F1 | 0.723 ± 0.034 | 0.804 ± 0.012 | 0.820 ± 0.017 | 0.832 ± 0.016 |
Per-class F1, adopted configuration
SN Ia 0.96 SN CC 0.85 SLSN 0.53 AGN 0.90 TDE 0.81 CV 0.94
Coverage and detection
- Conformal sets hold the 90% target: marginal 0.910; the 68-object TDE class sits at 0.853, within binomial noise. SLSN averages ≈ 2.1 labels per set rather than a silent misclassification.
- Rare-class detection reaches 94% (TDE) and 86% (novae) at a 1% false-alarm budget.
- The anomaly layer reads a narrower context (features + host + Gaia/WISE): M_pseudo and the counterpart block help classification but harm blind detection.
Install and use
Requires light-curve, lightgbm, and the numpy / pandas / scipy / scikit-learn stack.
Install
git clone https://github.com/applecider-ml/flare.git
cd flare
pip install -e . # or: pip install -r requirements.txtCommand line
flare report ZTF19acbzgog ZTF22abkfhua -o report.html # console page
flare predict ZTF19acbzgog # same as JSONPhotometry comes from BOOM when
BOOM_URL and credentials are set, and from ALeRCE otherwise. Anything
unavailable stays missing; never impute the external columns, pass NaN.
Python
import flare
clf = flare.load_classifier() # bts6 by default
labels = clf.predict_from_files(["ZTF21abcdxyz.npz"])
sets = clf.prediction_sets_from_files(["ZTF21abcdxyz.npz"])
energy = clf.anomaly_energy(clf.features_from_files([...]))
# everything from an object id:
from flare.fetch import fetch_events
from flare.context import context_featuresRust crate for brokers
The same model as a Rust crate in
rust/:
an exact LightGBM text-model evaluator, the 160 features, conformal sets and anomaly
energy. No Python, no ONNX runtime. An ONNX export is also provided under
models/bts6/onnx.
Learn
Executable, student-level lessons with exercises and baked outputs.
FLARE tutorial
From raw light curves to features, trees, calibration, conformal prediction and interpretability.
flare_tutorial.ipynb →Similarity search
The FLARE features as an interpretable embedding: k-NN retrieval, a 2-D map of the transient sky, k-NN classification, anomaly detection via neighbour distance, approximate NN.
similarity_search.ipynb →Why FLARE works
SHAP attribution on the trees recovers textbook transient physics: TDEs by a blue, near-constant g−r colour and a smooth decline; AGN by stochastic variability; SNe by rise/fade shape and reddening.
why_flare_works.ipynb →ZTF summer school
A full session: the FLARE pipeline from light curve to conformal sets and anomaly detection, and a deep sequence model built from scratch.
notebooks/ztf_summer_school_v2 →Repository layout
models/ pretrained weights for both schemes (+ ONNX)
rust/ the Rust crate for alert brokers
benchmark/ the BTS benchmark: splits, features, external context
scripts/ train, evaluate, predict, ONNX export
notebooks/ tutorials and the ZTF summer-school session
docs/ this page and the report renderings
Citation
If you use FLARE, please cite the accompanying paper (in prep.). FLARE is the light-curve module of AppleCiDEr.
License
MIT. See LICENSE.