jacscanomaly

jacscanomaly is a Python package for scan-based anomaly detection in time-series light curves.

The package is designed to detect microlensing planetary anomalies by scanning residuals after fitting a single lens model (e.g., PSPL), with low-memory C++ backends for large survey light curves and JAX-based fitters for flexible model development.

---

Features

• Scan-based anomaly detection on residuals after single-lens fitting
• C++ survey backends for the PSPL fit and anomaly grid scan
• JAX model components for flexible single-lens and higher-order models
• Candidate quality diagnostics: effective contributing points, peak-contribution fraction, and time-correlation metrics
• Built-in visualization: PSPL fit, residuals, and anomaly scan summary

---

Documentation

The full documentation is available on ReadTheDocs:

https://jacscanomaly.readthedocs.io/en/latest/

Start with:

• Installation
• Quickstart
• Examples
• Method overview
• API reference

---

Installation

pip install jacscanomaly

---

Quick Example

import numpy as np
import matplotlib.pyplot as plt
from jacscanomaly import CandidateCriteria, Finder, FinderConfig

# load data (time, flux, flux_err)
data = np.load("example_data.npy")
time, flux, ferr = data[:, 0], data[:, 1], data[:, 2]

# run anomaly finder
config = FinderConfig(
    fitter_kind="pspl",
    candidate_criteria=CandidateCriteria(min_n_eff=2.0),
)
finder = Finder(config)
result = finder.run(time, flux, ferr)

# For magnitude data, pass mag and magerr in the same positions and select it:
# result = finder.run(time, mag, magerr, data_kind="mag")

# You can still pass an explicit initial guess if desired:
# p0 = np.array([10000, 10, 0.3])
# result = finder.run(time, flux, ferr, p0)

result.print_summary()

# For the complete adopted-model anomaly workflow:
# result = finder.run_anomaly_pipeline(time, flux, ferr)
# print(result.has_anomaly_candidate)
# print(result.best_anomaly_candidate)

# In notebooks, get a one-row table:
# display(result.summary_table())

---

Visualization

finder.plot_result()
finder.plot_anomaly_window()
plt.show()

These commands produce two complementary visualizations:

1. Three-panel summary plot (finder.plot_result)

   • Top: Observed light curve with the best-fit baseline model (PSPL)
   • Middle: Residuals after baseline fitting
   • Bottom: Anomaly scan result (Δχ² vs. time), showing where localized deviations from the baseline model are detected

2. Focused anomaly window plot (finder.plot_anomaly_window)

   • A zoomed-in view around the best anomaly candidate
   • Residuals are shown together with the anomaly template and the flat model

Example notebooks are available in example/:

• template_scan_example.ipynb for the standard bell-template scan
• template_free_example.ipynb for the template-free residual chi-square scan

For a refined planetary residual, measure its peaks and dips directly:

features = signal.measure_features()
print(features.n_peaks, features.n_dips)
for feature in features.features:
    print(feature.kind, feature.time, feature.timescale, feature.strength)

This measurement does not assign a caustic shape or estimate binary-lens parameters.

---

Method Overview

The workflow of jacscanomaly is:

1. First fitting Fit a single lens model (e.g. PSPL) to the full light curve.

2. Residual analysis Compute residuals:

   residual = data − single_lens_model
   

3. Local anomaly scan For each grid point (t0, teff), compare:

   • a flat model
   • an anomaly template model within a local time window.

4. Detection statistic The improvement is measured by:

   Δχ² = χ²_flat − χ²_anomaly
   

---

Anomaly Score

To quantify how significant the best anomaly candidate is relative to others, we define a score:

score = (Δχ²_best − median(Δχ²_others)) / robust_scale(Δχ²_others)

The reference population is restricted to raw clusters from the same observing season and a comparable teff. Candidate-quality cuts are applied only after raw cluster extraction, so changing those cuts does not redefine the score background. The center and scale are estimated robustly with the median and MAD. Strong secondary candidates are removed with adaptive one-sided clipping rather than an unconditional percentile cut.

This measures how strongly the best candidate stands out from the rest of the grid.

Since v0.4.0, the score background is local to the candidate's observing season and timescale, with robust median/MAD normalization. Quality cuts do not change that background, and strong secondary clusters are removed only by adaptive one-sided clipping. In checks on four retained Roman light curves, the selected candidate and its Δχ² were unchanged while the score changed moderately, indicating that the normalization is less sensitive to unrelated seasons and timescales. Existing simscan efficiency maps using score thresholds should be recalibrated with v0.4.0 scores.

---

Candidate Quality Diagnostics

Large Δχ² values can sometimes be dominated by one or two points. To make this visible, jacscanomaly stores per-candidate support diagnostics in result.best.quality and per-grid diagnostics in result.grid_metrics_all.

For the best candidate:

q = result.best.quality
print(q.n_window)     # points in the local chi2 window
print(q.n_contrib)    # points above the per-point improvement threshold
print(q.n_eff)        # effective number of contributing points
print(q.peak_frac)    # strongest-point fraction of total positive improvement
print(q.rho1)         # lag-1 autocorrelation of per-point improvements
print(q.longest_run)  # longest consecutive run of contributing points

The effective point count is computed from positive per-point improvements using a participation-ratio style statistic:

n_eff = (sum_i u_i)^2 / sum_i u_i^2

where u_i = max(0, chi2_flat_i - chi2_anomaly_i). A one-point-dominated candidate has n_eff close to 1 and a large peak_frac.

result.grid_metrics_all is a NumPy array with columns:

[t0, teff, dchi2, n_window, n_contrib, n_eff, peak_frac, rho1, longest_run]

---

Result Summaries

AnomalyResult provides both CLI-friendly and notebook-friendly summaries:

result.print_summary()       # print formatted text
text = result.summary_text() # return formatted text
row = result.summary_dict()  # return a plain dictionary
table = result.summary_table()  # pandas.DataFrame when pandas is installed

print(result) also shows the formatted summary text.

---

Configuration

Key parameters are controlled via FinderConfig:

from jacscanomaly import CandidateCriteria, FinderConfig

config = FinderConfig(
    grid_backend="cpp",  # default for PSPL survey scans
    single_fit_backend="cpp",
    teff_init=0.03,      # initial anomaly timescale
    teff_grid_n=20,      # number of teff grid points
    sigma=3.0,           # per-point improvement threshold for n_contrib
    candidate_criteria=CandidateCriteria(min_n_eff=2.0),
    best_score_teff_ratio=2.0,
    best_score_upper_clip_sigma=5.0,
)

See FinderConfig for the full list of options.

For finite-source single-lens baselines without JAX autodiff, use the VBMicrolensing finite-difference fitters:

config = FinderConfig(
    fitter_kind="fspl_vbm_fd",
    grid_backend="cpp",
)

For GULLS-convention spacecraft parallax, use the standard native model and select the coordinate convention explicitly:

config = FinderConfig(
    fitter_kind="fspl_space_parallax",
    grid_backend="cpp",
    ra_deg=267.3,
    dec_deg=-29.9,
    tref=2461504.0,
    satellite_ephemeris_path="gulls_orbit5_heliocentric.dat",
    parallax_observer_convention="gulls",
    parallax_time_scale="hjd",
)

Parallax fitters evaluate the trajectory and finite-source magnification in the compiled C++/VBMicrolensing backend and optimize nonlinear parameters with SciPy trust-region least squares.

---

Example Data

The light curves used as examples in this repository are drawn from an original set of 2,371 simulated Roman light curves generated by the Roman Galactic Exoplanet Survey Project Infrastructure Team (RGES PIT), WG07 Survey Simulations and Pipeline Validation (Farzaneh Zohrabi, Matthew Penny, Macy Huston, Ali Crisp, et al).

This representative sample of 2,371 light curves was selected assuming the Cassan exoplanet mass function and consists of simulated Roman light curves of planetary microlensing events, including higher-order effects such as parallax and orbital motion.

---

Algorithmic Background

The anomaly scan implemented in jacscanomaly is inspired by the systematic anomaly search methodology developed for microlensing surveys (e.g., the KMTNet AnomalyFinder series). In particular, the approach of scanning residual light curves over a grid of anomaly times and durations is based on key ideas presented in:

Zang, W., Jung, Y., Yee, J., et al. (2021). Systematic KMTNet Planetary Anomaly Search, Paper I: OGLE-2019-BLG-1053Lb, A Buried Terrestrial Planet. The Astronomical Journal, 162, 163.
DOI: 10.3847/1538-3881/ac12d4 :contentReference[oaicite:3]{index=3}

This work described a semi-automated search algorithm that iteratively scans events for localized deviations relative to a baseline model and quantifies the significance of detected signals — an idea that is central to the grid-scan and Δχ² evaluation in jacscanomaly.

---

Finite-source magnification (FSPL)

jacscanomaly provides a standard FSPL fitter and a CPU/VBMicrolensing variant. All annual and space-parallax FSPL models use the compiled native trajectory/VBMicrolensing backend.

VBMicrolensing is installed as a required dependency because the native FSPL and parallax extensions are part of the standard build. The historical extra remains an accepted no-op:

pip install -e ".[vbm]"

The VBM fitters keep the anomaly grid scan in the compiled C++ backend when grid_backend="cpp" is selected.

For the JAX/microjax FSPL fitters, finite-source magnifications are computed using an external JAX-based implementation.

The original FFT-based extended-source algorithm is from: https://github.com/git-sunao/fft-extended-source

This algorithm is provided in JAX form by: https://github.com/ShotaMiyazaki94/microjax

Specifically, jacscanomaly uses the FFT disk-integration implementation available through:

from microjax.fastlens import fspl_disk

Note: jacscanomaly currently requires the GitHub source version of microjax. The PyPI package microjaxx==0.1.1 may not expose microjax.fastlens.fspl_disk.

Install microjax from source before using FSPL functionality:

git clone https://github.com/ShotaMiyazaki94/microjax.git
cd microjax
python -m pip install -e .

You can verify the installation with:

from microjax.fastlens import fspl_disk

Citation

If you use jacscanomaly in academic work, including journal articles, conference proceedings, or theses, please cite the software.

Citation metadata is provided in the citation.cff file in this repository, which can be used directly by GitHub and reference managers.

---

Requirements

• Python ≥ 3.9
• numpy
• jax
• scipy
• matplotlib

VBMicrolensing ≥ 5.5 is also required to build the native C++ extensions.

---

Development

Install the package with development dependencies:

pip install -e ".[dev]"

Run the unit tests:

pytest

Run the tests with coverage:

coverage run -m pytest
coverage report

Build the Sphinx documentation locally:

sphinx-build -W -b html docs docs/_build/html