jacscanomaly 0.1.0__tar.gz

jacscanomaly-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KansukeNunota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jacscanomaly-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: jacscanomaly
+Version: 0.1.0
+Summary: JAX-based scan anomaly detection for time-series residuals
+Author: Kansuke Nunota
+License: MIT
+Project-URL: Homepage, https://github.com/NunotaKansuke/jacscanomaly
+Project-URL: Repository, https://github.com/NunotaKansuke/jacscanomaly
+Project-URL: Issues, https://github.com/NunotaKansuke/jacscanomaly/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: jax
+Requires-Dist: jaxopt
+Requires-Dist: matplotlib
+Dynamic: license-file
+
+# jacscanomaly
+
+**jacscanomaly** is a JAX-based framework for scan-based anomaly detection
+in time-series data.
+
+The package is designed to detect **localized, transient anomalies** by
+scanning residuals after fitting a baseline model (e.g. PSPL in microlensing),
+while remaining fast and differentiable thanks to JAX.
+
+---
+
+## Features
+
+*  **JAX-powered**: fast, vectorized grid scans with JIT compilation
+*  **Scan-based anomaly detection** on residuals
+*  **Model-agnostic design**: anomaly scan works on residuals of any baseline model
+*  **Built-in visualization**: PSPL fit, residuals, and anomaly scan summary
+*  Designed for **research-grade workflows** (clear statistics & reproducibility)
+
+---
+
+## Installation
+
+```bash
+pip install jacscanomaly
+```
+
+> For local development (without pip), see the example notebook.
+
+---
+
+## Quick Example
+
+```python
+import numpy as np
+from jacscanomaly import Finder, FinderConfig
+
+# load data (time, flux, flux_err)
+data = np.load("example_data.npy")
+time, flux, ferr = data[:, 0], data[:, 1], data[:, 2]
+
+# initial guess for PSPL parameters
+p0 = np.array([9826.56, 8.61, 0.353])
+
+# run anomaly finder
+config = FinderConfig()
+finder = Finder(config)
+result = finder.run(time, flux, ferr, p0)
+
+print("=== PSPL fit ===")
+
+t0_pspl, tE_pspl, u0_pspl = result.fit.params
+print(f"  t0          = {float(t0_pspl):.3f}")
+print(f"  tE          = {float(tE_pspl):.3f}")
+print(f"  u0          = {float(u0_pspl):.3f}")
+print(f"  chi2 / dof  = {result.chi2_dof:.3f}\n")
+
+b = result.best
+print("=== Anomaly candidate ===")
+print(f"  t0          = {b.t0:.3f}")
+print(f"  teff        = {b.teff:.3f}")
+print(f"  dchi2       = {b.dchi2:.3e}")
+print(f"  score       = {b.score:.2f}")
+```
+
+---
+
+## Visualization
+
+```python
+finder.plot_result()
+plt.show()
+
+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
+
+---
+
+## Method Overview
+
+The workflow of `jacscanomaly` is:
+
+1. **Baseline fitting**
+   Fit a global model (e.g. PSPL) to the full light curve.
+
+2. **Residual analysis**
+   Compute residuals:
+
+   ```
+   residual = data − baseline_model
+   ```
+
+3. **Local anomaly scan**
+   For each grid point `(t0, teff)`, compare:
+
+   * a null (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)) / std(Δχ²_others)
+```
+
+This measures how strongly the best candidate stands out from the rest of the grid.
+
+---
+
+## Configuration
+
+Key parameters are controlled via `FinderConfig`:
+
+```python
+from jacscanomaly import FinderConfig
+
+config = FinderConfig(
+    gap=100.0,          # season gap
+    teff_init=0.3,      # initial anomaly timescale
+    teff_grid_n=5,      # number of teff grid points
+    sigma=3.0,          # threshold for outlier counting
+)
+```
+
+See `FinderConfig` for the full list of options.
+
+---
+
+## Requirements
+
+* Python ≥ 3.9
+* numpy
+* jax
+* jaxopt
+* matplotlib
+
+---

jacscanomaly-0.1.0/README.md

@@ -0,0 +1,162 @@
+# jacscanomaly
+
+**jacscanomaly** is a JAX-based framework for scan-based anomaly detection
+in time-series data.
+
+The package is designed to detect **localized, transient anomalies** by
+scanning residuals after fitting a baseline model (e.g. PSPL in microlensing),
+while remaining fast and differentiable thanks to JAX.
+
+---
+
+## Features
+
+*  **JAX-powered**: fast, vectorized grid scans with JIT compilation
+*  **Scan-based anomaly detection** on residuals
+*  **Model-agnostic design**: anomaly scan works on residuals of any baseline model
+*  **Built-in visualization**: PSPL fit, residuals, and anomaly scan summary
+*  Designed for **research-grade workflows** (clear statistics & reproducibility)
+
+---
+
+## Installation
+
+```bash
+pip install jacscanomaly
+```
+
+> For local development (without pip), see the example notebook.
+
+---
+
+## Quick Example
+
+```python
+import numpy as np
+from jacscanomaly import Finder, FinderConfig
+
+# load data (time, flux, flux_err)
+data = np.load("example_data.npy")
+time, flux, ferr = data[:, 0], data[:, 1], data[:, 2]
+
+# initial guess for PSPL parameters
+p0 = np.array([9826.56, 8.61, 0.353])
+
+# run anomaly finder
+config = FinderConfig()
+finder = Finder(config)
+result = finder.run(time, flux, ferr, p0)
+
+print("=== PSPL fit ===")
+
+t0_pspl, tE_pspl, u0_pspl = result.fit.params
+print(f"  t0          = {float(t0_pspl):.3f}")
+print(f"  tE          = {float(tE_pspl):.3f}")
+print(f"  u0          = {float(u0_pspl):.3f}")
+print(f"  chi2 / dof  = {result.chi2_dof:.3f}\n")
+
+b = result.best
+print("=== Anomaly candidate ===")
+print(f"  t0          = {b.t0:.3f}")
+print(f"  teff        = {b.teff:.3f}")
+print(f"  dchi2       = {b.dchi2:.3e}")
+print(f"  score       = {b.score:.2f}")
+```
+
+---
+
+## Visualization
+
+```python
+finder.plot_result()
+plt.show()
+
+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
+
+---
+
+## Method Overview
+
+The workflow of `jacscanomaly` is:
+
+1. **Baseline fitting**
+   Fit a global model (e.g. PSPL) to the full light curve.
+
+2. **Residual analysis**
+   Compute residuals:
+
+   ```
+   residual = data − baseline_model
+   ```
+
+3. **Local anomaly scan**
+   For each grid point `(t0, teff)`, compare:
+
+   * a null (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)) / std(Δχ²_others)
+```
+
+This measures how strongly the best candidate stands out from the rest of the grid.
+
+---
+
+## Configuration
+
+Key parameters are controlled via `FinderConfig`:
+
+```python
+from jacscanomaly import FinderConfig
+
+config = FinderConfig(
+    gap=100.0,          # season gap
+    teff_init=0.3,      # initial anomaly timescale
+    teff_grid_n=5,      # number of teff grid points
+    sigma=3.0,          # threshold for outlier counting
+)
+```
+
+See `FinderConfig` for the full list of options.
+
+---
+
+## Requirements
+
+* Python ≥ 3.9
+* numpy
+* jax
+* jaxopt
+* matplotlib
+
+---

jacscanomaly-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jacscanomaly"
+version = "0.1.0"
+description = "JAX-based scan anomaly detection for time-series residuals"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Kansuke Nunota" }]
+dependencies = [
+  "numpy",
+  "jax",
+  "jaxopt",
+  "matplotlib",
+]
+
+[project.urls]
+Homepage = "https://github.com/NunotaKansuke/jacscanomaly"
+Repository = "https://github.com/NunotaKansuke/jacscanomaly"
+Issues = "https://github.com/NunotaKansuke/jacscanomaly/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["jacscanomaly.test_tool*"]
+

jacscanomaly-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jacscanomaly-0.1.0/src/jacscanomaly/__init__.py

@@ -0,0 +1,20 @@
+# scanomaly/__init__.py
+from __future__ import annotations
+
+from jax import config as jax_config
+jax_config.update("jax_enable_x64", True)
+
+from .config import FinderConfig
+from .finder import Finder
+from .plot import AnomalyPlotter
+from .pspl import PSPLFitter, PSPLFitResult
+
+__all__ = [
+    "FinderConfig",
+    "Finder",
+    "AnomalyPlotter",
+    "PSPLFitter",
+    "PSPLFitResult",
+]
+
+__version__ = "0.1.0"

jacscanomaly-0.1.0/src/jacscanomaly/config.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class FinderConfig:
+    """
+    Configuration for :class:`scanomaly.finder.Finder`.
+
+    This dataclass contains *only* hyperparameters that control the behavior of the
+    anomaly search. It is intentionally dependency-free (no NumPy/JAX imports) and
+    frozen for reproducibility.
+
+    Parameter groups
+    ----------------
+    1) Season splitting:
+       Split the time series into seasons based on large time gaps.
+
+    2) Grid construction:
+       Build a (t0, teff) grid per season.
+
+    3) Grid scan:
+       Evaluate delta-chi2 on the grid within a local window.
+
+    4) Cluster extraction:
+       Group overlapping candidates and pick the best per cluster.
+    """
+
+    # ==================================================
+    # 1) Season splitting
+    # ==================================================
+    gap: float = 100.0
+    """Time gap threshold for splitting seasons. A new season starts when dt > gap."""
+
+    # ==================================================
+    # 2) Grid construction (t0, teff)
+    # ==================================================
+    teff_init: float = 0.03
+    """Initial teff value for the grid (first element of the geometric series)."""
+
+    common_ratio: float = 4.0 / 3.0
+    """Common ratio for the geometric series of teff values."""
+
+    teff_grid_n: int = 5
+    """Number of teff values in the grid."""
+
+    dt0_coeff: float = 0.17
+    """
+    Grid spacing coefficient for t0:
+        dt0 = dt0_coeff * teff
+    """
+
+    # ==================================================
+    # 3) Grid scan (local evaluation window)
+    # ==================================================
+    sigma: float = 3.0
+    """
+    Threshold parameter used in counting per-point chi2 improvement.
+    (Kept for compatibility with your original `n_out` logic.)
+    """
+
+    teff_coeff: float = 3.0
+    """
+    Window half-width multiplier in units of teff:
+        window = [t0 - teff_coeff*teff, t0 + teff_coeff*teff]
+    """
+
+    min_pts_in_window: int = 4
+    """Minimum number of data points required inside the window to evaluate a grid point."""
+
+    # ==================================================
+    # 4) Cluster extraction
+    # ==================================================
+    overlap_sigma: float = 3.0
+    """
+    Overlap threshold multiplier used to group nearby grid points into clusters:
+        |t0_i - t0_j| < overlap_sigma * (teff_i + teff_j)
+    """
+
+    min_cluster_points: int = 3
+    """
+    Stop extracting clusters when the number of remaining grid points becomes
+    smaller than this value.
+    """

jacscanomaly-0.1.0/src/jacscanomaly/extract.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Tuple
+
+import numpy as np
+
+
+@dataclass
+class ResultExtractor:
+    """
+    Cluster extractor for grid-scan candidates.
+
+    Given arrays of (t0, teff, delta_chi2) evaluated on a grid,
+    this class groups overlapping candidates and returns one representative
+    (the maximum delta_chi2 point) per cluster.
+
+    Overlap definition
+    ------------------
+    Two candidates i and j are considered overlapping if:
+
+        |t0_i - t0_j| < sigma_overlap * (teff_i + teff_j)
+
+    Notes
+    -----
+    - This operates on CPU / NumPy arrays (no JAX).
+    - Returned `clusters` has shape (K, 3) with rows [t0_best, teff_best, dchi2_best].
+    """
+
+    sigma_overlap: float = 3.0
+    min_points: int = 3
+
+    def _overlap_with_max(
+        self,
+        t0: np.ndarray,
+        teff: np.ndarray,
+        dchi2: np.ndarray,
+    ) -> Tuple[np.ndarray, int]:
+        """
+        Compute the overlap mask around the current maximum dchi2 point.
+
+        Returns
+        -------
+        overlap_mask : np.ndarray of bool, shape (N,)
+            Mask selecting points overlapping with the maximum point.
+        i_max : int
+            Index of the maximum point within the provided arrays.
+        """
+        i_max = int(np.nanargmax(dchi2))
+        t0_max = t0[i_max]
+        teff_max = teff[i_max]
+        overlap_mask = np.abs(t0 - t0_max) < self.sigma_overlap * (teff + teff_max)
+        return overlap_mask, i_max
+
+    def iterative_anomaly_extraction(
+        self,
+        t0_list,
+        teff_list,
+        dchi2_list,
+    ) -> np.ndarray:
+        """
+        Iteratively extract non-overlapping clusters from grid results.
+
+        Parameters
+        ----------
+        t0_list, teff_list, dchi2_list
+            1D arrays (or array-like) of equal length.
+
+        Returns
+        -------
+        clusters : np.ndarray, shape (K, 3)
+            Each row is [t0, teff, dchi2] for the best (max dchi2) point
+            in each extracted cluster.
+            Returns an empty array with shape (0, 3) if nothing is extractable.
+
+        Stopping conditions
+        -------------------
+        - No remaining candidates.
+        - The best remaining candidate is non-finite.
+        - Remaining candidate count drops below `min_points`.
+        """
+        t0 = np.asarray(t0_list, dtype=float)
+        teff = np.asarray(teff_list, dtype=float)
+        dchi2 = np.asarray(dchi2_list, dtype=float)
+
+        if t0.size == 0:
+            return np.zeros((0, 3), dtype=float)
+
+        if not (t0.shape == teff.shape == dchi2.shape):
+            raise ValueError(
+                f"Input arrays must have the same shape, got "
+                f"t0={t0.shape}, teff={teff.shape}, dchi2={dchi2.shape}"
+            )
+
+        clusters: List[List[float]] = []
+        remaining = np.ones_like(dchi2, dtype=bool)
+
+        while True:
+            if not np.any(remaining):
+                break
+
+            # pick the best remaining point
+            dchi2_rem = np.where(remaining, dchi2, -np.inf)
+            i_max_global = int(np.argmax(dchi2_rem))
+
+            if not np.isfinite(dchi2[i_max_global]):
+                break
+
+            # overlap mask in the "compressed" remaining arrays
+            overlap_mask, _ = self._overlap_with_max(
+                t0[remaining], teff[remaining], dchi2[remaining]
+            )
+
+            # expand to full mask
+            full_mask = np.zeros_like(remaining)
+            full_mask[np.where(remaining)[0][overlap_mask]] = True
+
+            # choose the best representative in this cluster
+            cluster_dchi2 = dchi2[full_mask]
+            cluster_t0 = t0[full_mask]
+            cluster_teff = teff[full_mask]
+
+            i_local_max = int(np.argmax(cluster_dchi2))
+            clusters.append(
+                [float(cluster_t0[i_local_max]), float(cluster_teff[i_local_max]), float(cluster_dchi2[i_local_max])]
+            )
+
+            # remove this cluster from remaining
+            remaining &= ~full_mask
+
+            if int(np.sum(remaining)) < self.min_points:
+                break
+
+        return np.asarray(clusters, dtype=float)