sensor-modeling 0.2.0__py3-none-any.whl

sensor_modeling/models/nhpp_pelt/bspline.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+
+from .utils import type_check
+
+Array1D = np.ndarray
+Array2D = np.ndarray
+
+
+def open_uniform_knots(
+    delta: float, degree: int, n_basis: int, internal_knots: Optional[Array1D]
+) -> Array1D:
+    """
+    Construct an open (clamped) knot vector on [0, delta].
+
+    If internal_knots is provided, then:
+        n_basis == len(internal_knots) + degree + 1
+    and we place degree+1 repeats at boundaries.
+
+    Returns
+    -------
+    knots : np.ndarray, shape (n_basis + degree + 1,)
+    """
+    type_check(delta > 0, "delta must be positive.")
+    type_check(degree >= 0, "degree must be non-negative.")
+
+    if internal_knots is not None:
+        internal_knots = np.asarray(internal_knots, dtype=float)
+        type_check(
+            np.all((internal_knots > 0) & (internal_knots < delta)),
+            "internal_knots must be in (0, delta).",
+        )
+        expected = internal_knots.size + degree + 1
+        type_check(
+            n_basis == expected,
+            f"n_basis must equal len(internal_knots)+degree+1 = {expected}.",
+        )
+        breaks = np.r_[0.0, internal_knots, delta]
+    else:
+        n_internal = n_basis - degree - 1
+        type_check(n_internal >= 0, "n_basis must be at least degree+1.")
+        if n_internal > 0:
+            internal = np.linspace(0.0, delta, n_internal + 2)[1:-1]
+            breaks = np.r_[0.0, internal, delta]
+        else:
+            breaks = np.array([0.0, delta], dtype=float)
+
+    t0 = np.repeat(breaks[0], degree + 1)
+    t1 = np.repeat(breaks[-1], degree + 1)
+    return np.r_[t0, breaks[1:-1], t1]
+
+
+def _basis_at_scalar(t: float, degree: int, knots: Array1D) -> Array1D:
+    """Cox–de Boor recursion for all basis functions at a scalar t."""
+    M = knots.size
+    n_basis = M - degree - 1
+    N = np.zeros((degree + 1, n_basis), dtype=float)
+
+    # degree 0
+    for i in range(n_basis):
+        if knots[i] <= t < knots[i + 1] or (
+            t == knots[-1] and knots[i] <= t <= knots[i + 1]
+        ):
+            N[0, i] = 1.0
+
+    # recursion
+    for k in range(1, degree + 1):
+        for i in range(n_basis):
+            left_den = knots[i + k] - knots[i]
+            right_den = knots[i + k + 1] - knots[i + 1]
+            left = 0.0 if left_den <= 0 else (t - knots[i]) / left_den * N[k - 1, i]
+            right = (
+                0.0
+                if right_den <= 0
+                else (knots[i + k + 1] - t) / right_den * N[k - 1, i + 1]
+                if i + 1 < n_basis
+                else 0.0
+            )
+            N[k, i] = left + right
+
+    return N[degree, :]
+
+
+def bspline_design_matrix(ts: Array1D, degree: int, knots: Array1D) -> Array2D:
+    """
+    Evaluate B-spline basis at vector ts (shape (m,)),
+    returning matrix Psi with shape (m, n_basis).
+    """
+    ts = np.asarray(ts, dtype=float)
+    out = np.empty((ts.size, knots.size - degree - 1), dtype=float)
+    for r, t in enumerate(ts):
+        out[r, :] = _basis_at_scalar(float(t), degree, knots)
+    return out

sensor_modeling/models/nhpp_pelt/cli.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from typing import List
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from .diagnostics import DiagConfig, plot_time_rescaling_diagnostics
+from .model import NHPPPELT, NHPPConfig
+from .plotting import (
+    HistConfig,
+    PlotConfig,
+    plot_segments_and_intensities_with_histograms,
+)
+from .utils import save_results_json
+
+Array1D = np.ndarray
+
+
+# --------------------------- I/O helpers ---------------------------
+
+
+def _parse_grid(expr: str) -> List[float]:
+    """
+    Parse a numeric grid:
+      - comma list: 0,0.001,0.01
+      - range: start:stop:step  (inclusive end within tolerance)
+    """
+    if ":" in expr:
+        a, b, c = expr.split(":")
+        start, stop, step = float(a), float(b), float(c)
+        if step <= 0:
+            raise ValueError("step must be > 0")
+        vals, x = [], start
+        while x <= stop + 1e-12:
+            vals.append(x)
+            x += step
+        return vals
+    return [float(x) for x in expr.split(",") if x.strip()]
+
+
+def _load_npz_days(path: str) -> List[Array1D]:
+    """
+    Load days from a .npz created as:
+        np.savez(path, days=np.array(list_of_arrays, dtype=object))
+    """
+    with np.load(path, allow_pickle=True) as data:
+        if "days" not in data:
+            raise ValueError("NPZ must contain array 'days' (dtype=object).")
+        arr = data["days"]
+    if arr.dtype != object:
+        raise ValueError("NPZ 'days' must be an object array of 1-D float arrays.")
+    return [np.asarray(x, float) for x in arr.tolist()]
+
+
+def _parse_betas(expr: str) -> List[float]:
+    """
+    Parse betas:
+      - Comma list: 10,20,40
+      - Range: start:stop:step  (inclusive-ish, step > 0)
+    """
+    if ":" in expr:
+        a, b, c = expr.split(":")
+        start, stop, step = float(a), float(b), float(c)
+        if step <= 0:
+            raise ValueError("step must be > 0")
+        vals = []
+        x = start
+        # include stop within tolerance
+        while x <= stop + 1e-12:
+            vals.append(x)
+            x += step
+        return vals
+    return [float(x) for x in expr.split(",") if x.strip()]
+
+
+# --------------------------- Subcommands ---------------------------
+
+
+def cmd_fit(args: argparse.Namespace) -> None:
+    days = _load_npz_days(args.input)
+    cfg = NHPPConfig(
+        delta=args.delta,
+        degree=args.degree,
+        n_basis=args.n_basis,
+        knot_strategy=args.knot_strategy,
+        min_seg_len=args.min_seg_len,
+        penalty_beta=(None if args.beta is None else float(args.beta)),
+    )
+    model = NHPPPELT(cfg).fit(days)
+    print("Changepoints:", model.changepoints_)
+    print("Segments:", model.segments_)
+
+    if args.json_out:
+        os.makedirs(os.path.dirname(args.json_out) or ".", exist_ok=True)
+        save_results_json(model, args.json_out)
+        print(f"Saved JSON to {args.json_out}")
+
+    if args.plot_out:
+        fig = plot_segments_and_intensities_with_histograms(
+            days,
+            model,
+            config=PlotConfig(grid_points=args.grid_points),
+            hist=HistConfig(bins="fd", density=True, alpha=0.4),
+            save_path=args.plot_out,
+        )
+        plt.close(fig)
+        print(f"Saved plot to {args.plot_out}")
+
+    if args.diag_out:
+        fig = plot_time_rescaling_diagnostics(
+            days,
+            model,
+            config=DiagConfig(grid_points=args.grid_points),
+            save_path=args.diag_out,
+        )
+        plt.close(fig)
+        print(f"Saved diagnostics to {args.diag_out}")
+
+
+def cmd_sweep_beta(args: argparse.Namespace) -> None:
+    from .utils import sweep_beta
+
+    days = _load_npz_days(args.input)
+    base_cfg = NHPPConfig(
+        delta=args.delta,
+        degree=args.degree,
+        n_basis=args.n_basis,
+        knot_strategy=args.knot_strategy,
+        min_seg_len=args.min_seg_len,
+        penalty_beta=None,
+    )
+    betas = _parse_betas(args.betas)
+    results = sweep_beta(days, base_cfg, betas)
+    # Print as JSON lines for easy piping
+    for beta, n_cp, total in results:
+        print(json.dumps({"beta": beta, "n_changepoints": n_cp, "total_cost": total}))
+
+
+def cmd_sweep_gamma(args: argparse.Namespace) -> None:
+    from .model import NHPPConfig
+    from .regularization import sweep_gamma
+
+    days = _load_npz_days(args.input)
+    base_cfg = NHPPConfig(
+        delta=args.delta,
+        degree=args.degree,
+        n_basis=args.n_basis,
+        knot_strategy=args.knot_strategy,
+        min_seg_len=args.min_seg_len,
+        penalty_beta=(None if args.beta is None else float(args.beta)),
+    )
+    gammas = _parse_grid(args.gammas)
+    results = sweep_gamma(days, base_cfg, gammas, order=args.order)
+    for gamma, n_cp, total in results:
+        print(json.dumps({"gamma": gamma, "n_changepoints": n_cp, "total_cost": total}))
+
+
+# --------------------------- CLI wiring ---------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="nhpp",
+        description="NHPP segmentation with B-splines & PELT (fit/plot/diagnostics).",
+    )
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    # fit
+    pf = sub.add_parser("fit", help="Fit model to days and optionally save plots/JSON.")
+    pf.add_argument(
+        "--input", required=True, help="Path to .npz with object array 'days'."
+    )
+    pf.add_argument("--delta", type=float, default=24.0)
+    pf.add_argument("--degree", type=int, default=3)
+    pf.add_argument("--n-basis", type=int, default=5, dest="n_basis")
+    pf.add_argument(
+        "--knot-strategy", choices=["quantile", "equispaced"], default="quantile"
+    )
+    pf.add_argument("--min-seg-len", type=int, default=2, dest="min_seg_len")
+    pf.add_argument("--beta", type=float, default=None, help="If omitted, uses SIC.")
+    pf.add_argument("--grid-points", type=int, default=500)
+    pf.add_argument("--json-out", default=None, help="Save fitted state JSON here.")
+    pf.add_argument("--plot-out", default=None, help="Save segmentation plot PNG here.")
+    pf.add_argument(
+        "--diag-out", default=None, help="Save time-rescaling diagnostics PNG here."
+    )
+    pf.set_defaults(func=cmd_fit)
+
+    # sweep-beta
+    ps = sub.add_parser("sweep-beta", help="Evaluate different penalties (β).")
+    ps.add_argument(
+        "--input", required=True, help="Path to .npz with object array 'days'."
+    )
+    ps.add_argument("--delta", type=float, default=24.0)
+    ps.add_argument("--degree", type=int, default=3)
+    ps.add_argument("--n-basis", type=int, default=5, dest="n_basis")
+    ps.add_argument(
+        "--knot-strategy", choices=["quantile", "equispaced"], default="quantile"
+    )
+    ps.add_argument("--min-seg-len", type=int, default=2, dest="min_seg_len")
+    ps.add_argument("--betas", required=True, help="Comma list or start:stop:step.")
+    ps.set_defaults(func=cmd_sweep_beta)
+
+    # sweep-gamma
+    pg = sub.add_parser(
+        "sweep-gamma", help="Evaluate different P-spline strengths (γ)."
+    )
+    pg.add_argument(
+        "--input", required=True, help="Path to .npz with object array 'days'."
+    )
+    pg.add_argument("--delta", type=float, default=24.0)
+    pg.add_argument("--degree", type=int, default=3)
+    pg.add_argument("--n-basis", type=int, default=5, dest="n_basis")
+    pg.add_argument(
+        "--knot-strategy", choices=["quantile", "equispaced"], default="quantile"
+    )
+    pg.add_argument("--min-seg-len", type=int, default=2, dest="min_seg_len")
+    pg.add_argument("--beta", type=float, default=None, help="If omitted, uses SIC.")
+    pg.add_argument(
+        "--gammas",
+        required=True,
+        help="Comma list or start:stop:step, e.g. 0:0.1:0.005",
+    )
+    pg.add_argument(
+        "--order", type=int, default=2, help="Difference order (usually 2)."
+    )
+    pg.set_defaults(func=cmd_sweep_gamma)
+
+    return p
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

sensor_modeling/models/nhpp_pelt/diagnostics.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, List, Optional, Tuple
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+Array1D = np.ndarray
+
+
+def _check(cond: bool, msg: str) -> None:
+    if not cond:
+        raise ValueError(msg)
+
+
+@dataclass(frozen=True)
+class DiagConfig:
+    """
+    Configuration for time-rescaling diagnostics.
+
+    Attributes
+    ----------
+    grid_points : int
+        Uniform grid resolution for λ(t) and Λ(t) approximation.
+    figsize : tuple[float, float]
+        Matplotlib figure size.
+    dpi : int
+        Figure DPI.
+    hist_bins : int
+        Number of bins for U-histogram (Uniform(0,1) check).
+    alpha : float
+        Transparency for histograms and fills.
+    """
+
+    grid_points: int = 2000
+    figsize: Tuple[float, float] = (12.0, 7.0)
+    dpi: int = 110
+    hist_bins: int = 20
+    alpha: float = 0.5
+
+
+def _lambda_grid(
+    model: Any, seg_index: int, grid_points: int
+) -> Tuple[Array1D, Array1D]:
+    """Compute λ̂_k(t) on a uniform grid for segment k."""
+    delta: float = float(model.delta_)
+    grid = np.linspace(0.0, delta, grid_points)
+    lam = np.asarray(model.intensity_on_grid(seg_index, grid), float)
+    _check(lam.shape == grid.shape, "intensity_on_grid must match grid shape.")
+    return grid, lam
+
+
+def _cumulative_int(grid: Array1D, lam: Array1D) -> Array1D:
+    """
+    Cumulative integral Λ(t) via the trapezoidal rule on a uniform grid.
+    Returns array of same length as grid with Λ(0)=0.
+    """
+    # Guard
+    _check(
+        grid.ndim == 1 and lam.ndim == 1 and grid.size == lam.size,
+        "grid/lam shape mismatch.",
+    )
+    d = np.diff(grid)
+    # trapezoid increments: ∫ lam ~ 0.5*(lam_i + lam_{i+1})*Δ
+    incr = 0.5 * (lam[:-1] + lam[1:]) * d
+    return np.r_[0.0, np.cumsum(incr)]
+
+
+def _interp_cumint(t: Array1D, grid: Array1D, Lambda: Array1D) -> Array1D:
+    """
+    Interpolate Λ(t) for arbitrary event times using linear interpolation
+    over the precomputed (grid, Λ(grid)).
+    """
+    t = np.asarray(t, float)
+    t = np.clip(t, grid[0], grid[-1])
+    return np.interp(t, grid, Lambda)
+
+
+def time_rescale_events_for_segment(
+    model: Any,
+    seg_index: int,
+    events_per_day: Sequence[Array1D],
+    grid_points: int = 2000,
+) -> Tuple[List[Array1D], List[Array1D]]:
+    """
+    Apply the time-rescaling theorem *within a fitted segment*:
+      ΔΛ_j  should be i.i.d. Exp(1);
+      U_j = 1 - exp(-ΔΛ_j) should be i.i.d. Uniform(0,1).
+
+    Parameters
+    ----------
+    model : fitted NHPPPELT-like object
+    seg_index : int
+        Segment index in 0..K-1.
+    events_per_day : list of 1-D arrays
+        Only the days that belong to this segment.
+    grid_points : int
+        Resolution for Λ approximation.
+
+    Returns
+    -------
+    delta_L_list : list[np.ndarray]
+        For each day, the Exp(1)-should-be inter-arrival ΔΛ sequence.
+    U_list : list[np.ndarray]
+        Uniform(0,1)-should-be values 1 - exp(-ΔΛ).
+    """
+    grid, lam = _lambda_grid(model, seg_index, grid_points)
+    Lambda = _cumulative_int(grid, lam)
+
+    delta_L_list: List[Array1D] = []
+    U_list: List[Array1D] = []
+
+    for ev in events_per_day:
+        ev = np.asarray(ev, float)
+        if ev.size == 0:
+            delta_L_list.append(np.array([], float))
+            U_list.append(np.array([], float))
+            continue
+        # Rescaled event times Λ(t_j)
+        L_times = _interp_cumint(ev, grid, Lambda)
+        # Inter-arrival increments; include leading gap from 0 to first event
+        L_with0 = np.r_[0.0, L_times]
+        dL = np.diff(L_with0)
+        U = 1.0 - np.exp(-dL)
+        delta_L_list.append(dL)
+        U_list.append(U)
+
+    return delta_L_list, U_list
+
+
+def ks_stat_uniform(u: Array1D) -> float:
+    """
+    Kolmogorov-Smirnov statistic for Uniform(0,1).
+    (Asymptotic p-value can be added if needed; we return only D.)
+    """
+    u = np.sort(np.asarray(u, float))
+    n = u.size
+    if n == 0:
+        return np.nan
+    # D+ = max_i i/n - u_i ; D- = max_i u_i - (i-1)/n
+    i = np.arange(1, n + 1, dtype=float)
+    d_plus = np.max(i / n - u)
+    d_minus = np.max(u - (i - 1.0) / n)
+    return float(max(d_plus, d_minus))
+
+
+def plot_time_rescaling_diagnostics(
+    days: Sequence[Array1D],
+    model: Any,
+    config: DiagConfig = DiagConfig(),
+    *,
+    save_path: Optional[str] = None,
+) -> plt.Figure:
+    """
+    Build a 2-row diagnostics figure per segment:
+      Row 1 (left-to-right over segments): histogram of U with Uniform(0,1) reference line.
+      Row 2: exponential QQ plot for ΔΛ vs Exp(1) quantiles.
+
+    Notes
+    -----
+    - No external stats deps; uniform line and exponential quantiles are computed analytically.
+    - Uses Matplotlib defaults for colors.
+    """
+    _check(
+        hasattr(model, "segments_") and hasattr(model, "delta_"),
+        "Model missing required attributes.",
+    )
+    segments: List[Tuple[int, int]] = list(model.segments_)
+    n_segments = len(segments)
+    _check(n_segments >= 1, "No segments found.")
+
+    # Group events per segment
+    seg_days: List[List[Array1D]] = []
+    for i_start, i_end in segments:
+        seg_days.append([np.asarray(d, float) for d in days[i_start - 1 : i_end]])
+
+    # Precompute transformed values
+    all_U: List[Array1D] = []
+    all_dL: List[Array1D] = []
+    for k, evs in enumerate(seg_days):
+        dL_list, U_list = time_rescale_events_for_segment(
+            model, k, evs, grid_points=config.grid_points
+        )
+        all_U.append(np.concatenate(U_list) if U_list else np.array([], float))
+        all_dL.append(np.concatenate(dL_list) if dL_list else np.array([], float))
+
+    # Figure layout: 2 rows × K columns
+    fig = plt.figure(figsize=config.figsize, dpi=config.dpi)
+    gs = fig.add_gridspec(nrows=2, ncols=n_segments, hspace=0.35, wspace=0.2)
+
+    # Row 1: U histograms
+    for k in range(n_segments):
+        ax = fig.add_subplot(gs[0, k])
+        u = all_U[k]
+        # Histogram (counts normalized to density); no explicit color
+        ax.hist(
+            u, bins=config.hist_bins, range=(0.0, 1.0), density=True, alpha=config.alpha
+        )
+        # Uniform(0,1) reference density = 1 on [0,1]
+        ax.plot([0.0, 1.0], [1.0, 1.0])  # default color/style
+        D = ks_stat_uniform(u)
+        ax.set_title(f"Seg {k+1} — U histogram (KS D={D:.3f})", fontsize=10)
+        ax.set_xlim(0.0, 1.0)
+        ax.set_xlabel("U = 1 - exp(-ΔΛ)")
+        if k == 0:
+            ax.set_ylabel("Density")
+        ax.grid(True, linestyle="--", linewidth=0.5, alpha=0.5)
+
+    # Row 2: Exponential QQ (ΔΛ vs Exp(1))
+    for k in range(n_segments):
+        ax = fig.add_subplot(gs[1, k])
+        dL = np.sort(all_dL[k])
+        n = dL.size
+        if n >= 2:
+            # Theoretical Exp(1) quantiles for p_i = (i-0.5)/n
+            p = (np.arange(1, n + 1) - 0.5) / n
+            q = -np.log(1.0 - p)
+            ax.plot(q, dL, linestyle="None", marker="o", markersize=3, alpha=0.8)
+            # y=x reference
+            lim = float(max(q[-1], dL[-1])) if n > 0 else 1.0
+            ax.plot([0.0, lim], [0.0, lim])
+        ax.set_title(f"Seg {k+1} — QQ: ΔΛ vs Exp(1)", fontsize=10)
+        ax.set_xlabel("Theoretical Exp(1) quantiles")
+        if k == 0:
+            ax.set_ylabel("Observed ΔΛ")
+        ax.grid(True, linestyle="--", linewidth=0.5, alpha=0.5)
+
+    fig.suptitle("Time-rescaling diagnostics per segment", y=0.99, fontsize=12)
+    fig.tight_layout()
+    if save_path:
+        fig.savefig(save_path, dpi=config.dpi, bbox_inches="tight")
+    return fig

sensor_modeling/models/nhpp_pelt/io.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import csv
+import glob
+import os
+from collections.abc import Sequence
+from typing import List
+
+import numpy as np
+
+Array1D = np.ndarray
+
+
+def load_days_from_npy_folder(folder: str) -> List[Array1D]:
+    """
+    Load days from a folder of .npy files.
+    Each .npy must contain a 1-D float array of event times in [0, delta].
+    Files are sorted by filename to define day order.
+    """
+    paths = sorted(glob.glob(os.path.join(folder, "*.npy")))
+    days: List[Array1D] = []
+    for p in paths:
+        arr = np.load(p)
+        if arr.ndim != 1:
+            raise ValueError(f"{p}: expected 1-D array.")
+        days.append(arr.astype(float, copy=False))
+    return days
+
+
+def load_days_from_csv_folder(folder: str, column: str = "time") -> List[Array1D]:
+    """
+    Load days from a folder of .csv files (one file per day).
+    The CSV must have a header row including `column` with event times (floats).
+    Files are sorted by filename to define day order.
+    """
+    paths = sorted(glob.glob(os.path.join(folder, "*.csv")))
+    days: List[Array1D] = []
+    for p in paths:
+        vals: List[float] = []
+        with open(p, newline="") as f:
+            reader = csv.DictReader(f)
+            if reader.fieldnames is None or column not in reader.fieldnames:
+                raise ValueError(f"{p}: missing '{column}' column.")
+            for row in reader:
+                try:
+                    vals.append(float(row[column]))
+                except (TypeError, ValueError):
+                    continue  # skip malformed rows
+        days.append(np.asarray(vals, float))
+    return days
+
+
+def save_days_npz(days: Sequence[Array1D], path: str) -> None:
+    """
+    Save list of days to an .npz that works with nhpp.cli (--input).
+    """
+    obj = np.array([np.asarray(d, float) for d in days], dtype=object)
+    np.savez(path, days=obj)