pimf 0.1.0__py3-none-any.whl

pimf/__init__.py

@@ -0,0 +1,23 @@
+"""Intrinsic multiscale filtering (IMF) for 1-D signals."""
+
+from .contrasts import Contrast, Quadratic, SmoothAbs
+from .decompose import IMFResult, StageInfo, imf, linear_imf, robust_imf
+from .kernels import Kernel, SquaredTriangle
+from .schedule import make_window_schedule
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Contrast",
+    "IMFResult",
+    "Kernel",
+    "Quadratic",
+    "SmoothAbs",
+    "SquaredTriangle",
+    "StageInfo",
+    "__version__",
+    "imf",
+    "linear_imf",
+    "make_window_schedule",
+    "robust_imf",
+]

pimf/_erf.py

@@ -0,0 +1,28 @@
+"""Error function approximation shared by the contrast functions.
+
+Abramowitz & Stegun formula 7.1.26 (max abs error ~1.5e-7), kept instead of
+scipy.special.erf so results match the IMF research notebooks bit-for-bit.
+"""
+
+import numpy as np
+
+SQRT_2 = np.sqrt(2.0)
+SQRT_2_OVER_PI = np.sqrt(2.0 / np.pi)
+
+
+def erf_approx(x):
+    """Vectorized Abramowitz-Stegun approximation to erf(x)."""
+    x = np.asarray(x, dtype=float)
+    sign = np.sign(x)
+    ax = np.abs(x)
+
+    p = 0.3275911
+    a1 = 0.254829592
+    a2 = -0.284496736
+    a3 = 1.421413741
+    a4 = -1.453152027
+    a5 = 1.061405429
+
+    z = 1.0 / (1.0 + p * ax)
+    poly = ((((a5 * z + a4) * z + a3) * z + a2) * z + a1) * z
+    return sign * (1.0 - poly * np.exp(-(ax**2)))

pimf/contrasts.py

@@ -0,0 +1,71 @@
+"""Contrast functions for the local location fits.
+
+A contrast supplies the loss rho (via __call__), its derivative psi (the
+score), and an upper bound on rho'' (curvature) that sets a stable gradient
+step. A contrast with a closed-form minimizer may also provide
+solve(windows, weights); the decomposition then skips gradient descent.
+"""
+
+import numpy as np
+
+from ._erf import SQRT_2, SQRT_2_OVER_PI, erf_approx
+
+
+class Contrast:
+    """Base contrast. Subclass and implement __call__, psi, and curvature."""
+
+    def __call__(self, r):
+        """Loss rho(r), vectorized."""
+        raise NotImplementedError
+
+    def psi(self, r):
+        """Score rho'(r), vectorized; drives the gradient-descent update."""
+        raise NotImplementedError
+
+    def curvature(self):
+        """Upper bound on rho''; the gradient step size is 0.95 / curvature()."""
+        raise NotImplementedError
+
+
+class Quadratic(Contrast):
+    """rho(r) = r^2 / 2: the local weighted mean, i.e. the linear IMF."""
+
+    def __call__(self, r):
+        return 0.5 * np.asarray(r, dtype=float) ** 2
+
+    def psi(self, r):
+        return np.asarray(r, dtype=float)
+
+    def curvature(self):
+        return 1.0
+
+    def solve(self, windows, weights):
+        """Closed-form minimizer: the weighted mean of each window row."""
+        return windows @ weights
+
+
+class SmoothAbs(Contrast):
+    """Smoothed absolute value: |r| convolved with a N(0, h^2) density.
+
+    rho_h(r) = r * erf(r / (sqrt(2) h)) + sqrt(2 / pi) * h * exp(-r^2 / (2 h^2))
+    psi_h(r) = erf(r / (sqrt(2) h)), bounded in [-1, 1].
+
+    h > 0 controls the transition from quadratic near zero to |r| in the
+    tails: smaller h is more median-like, larger h closer to the local mean.
+    h ~ 2 * noise sigma is the research-validated default choice.
+    """
+
+    def __init__(self, h):
+        if h <= 0:
+            raise ValueError("h must be positive")
+        self.h = float(h)
+
+    def __call__(self, r):
+        r = np.asarray(r, dtype=float)
+        return r * self.psi(r) + SQRT_2_OVER_PI * self.h * np.exp(-0.5 * (r / self.h) ** 2)
+
+    def psi(self, r):
+        return erf_approx(np.asarray(r, dtype=float) / (SQRT_2 * self.h))
+
+    def curvature(self):
+        return SQRT_2_OVER_PI / self.h

pimf/decompose.py

@@ -0,0 +1,138 @@
+"""Intrinsic multiscale filtering: the decomposition driver."""
+
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.lib.stride_tricks import sliding_window_view
+
+from .contrasts import Quadratic, SmoothAbs
+from .kernels import SquaredTriangle
+from .schedule import make_window_schedule
+
+
+@dataclass(frozen=True)
+class StageInfo:
+    """Per-stage diagnostics; the closed-form path reports iterations=1 and
+    final_max_delta=nan."""
+
+    stage: int
+    window_size: int
+    iterations: int
+    final_max_delta: float
+
+
+@dataclass
+class IMFResult:
+    """Decomposition output; y == imfs.sum(axis=0) + residual up to float rounding."""
+
+    imfs: np.ndarray
+    residual: np.ndarray
+    stages: list[StageInfo]
+    window_sizes: list[int]
+
+    @property
+    def reconstruction(self):
+        return self.imfs.sum(axis=0) + self.residual
+
+
+def _gd_fit_windows(windows, weights, contrast, max_iter, tol):
+    """Minimize sum_u w_u * rho(window_u - x) per row by clipped gradient descent.
+
+    Port of robust_gd_fit_windows from the research notebooks, generalized to
+    any contrast via psi and curvature. Returns (x, iterations, max_delta).
+    """
+    weights = weights / weights.sum()
+    row_weights = weights.reshape(1, -1)
+
+    x = np.median(windows, axis=1)
+    lower = windows.min(axis=1)
+    upper = windows.max(axis=1)
+
+    # The weighted score is Lipschitz with constant curvature() because the
+    # weights are normalized, so this step size keeps the iteration stable.
+    step = 0.95 / contrast.curvature()
+
+    iterations = 0
+    max_delta = float("nan")
+    for _ in range(max_iter):
+        local_score = np.sum(row_weights * contrast.psi(windows - x[:, None]), axis=1)
+        x_next = np.clip(x + step * local_score, lower, upper)
+        max_delta = float(np.max(np.abs(x_next - x)))
+        x = x_next
+        iterations += 1
+        if max_delta <= tol * (1.0 + float(np.max(np.abs(x)))):
+            break
+
+    return x, iterations, max_delta
+
+
+def _smooth_stage(residual, window_size, kernel, contrast, boundary, max_iter, tol):
+    """One smoothing pass: fit the local location at every position."""
+    weights = kernel.weights(window_size)
+    radius = window_size // 2
+    padded = np.pad(residual, pad_width=radius, mode=boundary)
+    windows = sliding_window_view(padded, window_size)
+
+    solve = getattr(contrast, "solve", None)
+    if callable(solve):
+        return solve(windows, weights), 1, float("nan")
+    return _gd_fit_windows(windows, weights, contrast, max_iter, tol)
+
+
+def imf(y, window_sizes=None, contrast=None, kernel=None, boundary="wrap", max_iter=60, tol=1e-6):
+    """Decompose a 1-D signal into multiscale components plus a residual.
+
+    At each stage the current residual is smoothed by a local M-estimator
+    defined by kernel and contrast; the smooth becomes that stage's component
+    and the recursion continues on what is left:
+    r_1 = y, S_k = smooth(r_k), r_{k+1} = r_k - S_k.
+
+    Defaults: window_sizes = make_window_schedule(len(y)), contrast =
+    Quadratic() (the linear IMF), kernel = SquaredTriangle(). boundary is
+    passed to np.pad ("wrap", "reflect", "edge", ...). max_iter and tol apply
+    only when the contrast has no closed-form solve.
+    """
+    y = np.asarray(y, dtype=float)
+    if y.ndim != 1:
+        raise ValueError("y must be one-dimensional")
+    if len(y) == 0:
+        raise ValueError("y must not be empty")
+
+    if window_sizes is None:
+        window_sizes = make_window_schedule(len(y))
+    window_sizes = [int(size) for size in window_sizes]
+    if contrast is None:
+        contrast = Quadratic()
+    if kernel is None:
+        kernel = SquaredTriangle()
+
+    residual = y.copy()
+    imfs = []
+    stages = []
+    for stage, window_size in enumerate(window_sizes, start=1):
+        component, iterations, final_max_delta = _smooth_stage(
+            residual, window_size, kernel, contrast, boundary, max_iter, tol
+        )
+        imfs.append(component)
+        residual = residual - component
+        stages.append(StageInfo(stage, window_size, iterations, final_max_delta))
+
+    return IMFResult(np.array(imfs), residual, stages, window_sizes)
+
+
+def linear_imf(y, window_sizes=None, kernel=None, boundary="wrap"):
+    """imf() with the Quadratic contrast: the linear (weighted local mean) IMF."""
+    return imf(y, window_sizes=window_sizes, contrast=Quadratic(), kernel=kernel, boundary=boundary)
+
+
+def robust_imf(y, h, window_sizes=None, kernel=None, boundary="wrap", max_iter=60, tol=1e-6):
+    """imf() with the SmoothAbs(h) contrast; h ~ 2 * noise sigma works well."""
+    return imf(
+        y,
+        window_sizes=window_sizes,
+        contrast=SmoothAbs(h),
+        kernel=kernel,
+        boundary=boundary,
+        max_iter=max_iter,
+        tol=tol,
+    )

pimf/kernels.py

@@ -0,0 +1,54 @@
+"""Kernel window weights for the local fits.
+
+A kernel is defined by its profile k(u) on [-1, 1]; the base class turns the
+profile into a normalized, symmetric weight vector for an odd window size.
+"""
+
+import numpy as np
+
+
+class Kernel:
+    """Base kernel. Subclass and implement profile(u).
+
+    profile(u) must be vectorized and nonnegative on [-1, 1]; any constant
+    factor cancels under normalization.
+    """
+
+    def profile(self, u):
+        """Unnormalized kernel profile k(u) on [-1, 1]."""
+        raise NotImplementedError
+
+    def weights(self, window_size):
+        """Normalized weight vector for an odd window size."""
+        if window_size % 2 == 0:
+            raise ValueError("window_size must be odd")
+
+        radius = window_size // 2
+        if radius == 0:
+            return np.array([1.0])
+
+        offsets = np.arange(-radius, radius + 1)
+        u = offsets / radius
+        weights = np.asarray(self.profile(u), dtype=float)
+        if np.any(weights < 0):
+            raise ValueError("kernel profile must be nonnegative")
+        total = weights.sum()
+        if total <= 0:
+            raise ValueError("kernel weights must have positive sum")
+        return weights / total
+
+    __call__ = weights
+
+
+class SquaredTriangle(Kernel):
+    """Squared triangular profile k(u) = 0.75 * (1 - |u|)^2.
+
+    The default kernel of the IMF research project, where it is called
+    "Epanechnikov" — a misnomer: the classical Epanechnikov kernel is
+    (3/4)(1 - u^2). The 0.75 factor cancels under normalization and is kept
+    for parity with the research code. The endpoint weights (|u| = 1) are
+    exactly zero.
+    """
+
+    def profile(self, u):
+        return 0.75 * np.maximum(0.0, 1.0 - np.abs(u)) ** 2

pimf/schedule.py

@@ -0,0 +1,65 @@
+"""Geometric window-size schedule for the IMF decomposition.
+
+Faithful port of make_window_schedule from the IMF research notebooks:
+odd, strictly decreasing sizes from about n/2 down to min_window_size,
+shrinking by factor each stage.
+"""
+
+import numpy as np
+
+from ._erf import SQRT_2
+
+
+def odd_ceiling(value):
+    """Smallest odd integer >= ceil(value), at least 1."""
+    size = int(np.ceil(value))
+    if size % 2 == 0:
+        size += 1
+    return max(1, size)
+
+
+def nearest_odd(value):
+    """Odd integer nearest to value (ties round down), at least 1."""
+    rounded = int(np.round(value))
+    if rounded % 2 == 1:
+        return max(1, rounded)
+
+    lower = max(1, rounded - 1)
+    upper = rounded + 1
+    if abs(value - lower) <= abs(upper - value):
+        return lower
+    return upper
+
+
+def make_window_schedule(n, factor=SQRT_2, min_window_size=31):
+    """Window sizes for a length-n signal: first = odd_ceiling(n / 2), then
+    geometric shrink by factor, all odd, strictly decreasing, floored at
+    min_window_size."""
+    if n <= 0:
+        raise ValueError("n must be positive")
+    if factor <= 1:
+        raise ValueError("factor must be larger than 1")
+
+    first = odd_ceiling(n / 2)
+    if first > n:
+        first = n if n % 2 == 1 else n - 1
+
+    min_size = nearest_odd(min_window_size)
+    if min_size > first:
+        return [first]
+
+    sizes = [first]
+    current = first
+
+    while current > min_size:
+        candidate = nearest_odd(current / factor)
+        candidate = min(candidate, current - 2)
+        if candidate % 2 == 0:
+            candidate -= 1
+        if candidate < min_size:
+            candidate = min_size
+
+        sizes.append(candidate)
+        current = candidate
+
+    return sizes

pimf-0.1.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: pimf
+Version: 0.1.0
+Summary: Intrinsic multiscale filtering (IMF) for 1-D signals: linear and robust decompositions.
+Project-URL: Homepage, https://github.com/mkuziuk/pimf
+Project-URL: Source, https://github.com/mkuziuk/pimf
+Project-URL: Issues, https://github.com/mkuziuk/pimf/issues
+Author: Mikhail Kuziuk
+License-Expression: MIT
+License-File: LICENSE
+Keywords: decomposition,m-estimator,robust-statistics,signal-processing,smoothing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.22
+Description-Content-Type: text/markdown
+
+# pimf
+
+Intrinsic multiscale filtering (IMF) for one-dimensional signals: a **linear**
+decomposition (local weighted mean) and a **robust** variant that replaces the
+mean with a smooth robust location fit solved by gradient descent.
+
+Both are the same algorithm. Starting from `r_1 = y`, each stage smooths the
+current residual with a local M-estimator and passes on what is left:
+
+```
+S_k = argmin_x  sum_u  w_{t,u} * rho(r_k(u) - x)        (per position t)
+r_{k+1} = r_k - S_k
+```
+
+The signal decomposes exactly: `y = S_1 + ... + S_K + r_{K+1}`. The only
+difference between the variants is the contrast `rho`:
+
+- **Quadratic** `rho(r) = r^2/2` — closed form, the kernel-weighted local mean
+  (the linear IMF).
+- **SmoothAbs** `rho_h(r) = r*erf(r/(sqrt(2)h)) + sqrt(2/pi)*h*exp(-r^2/(2h^2))`
+  — a smoothed absolute value with bounded score `psi_h(r) = erf(r/(sqrt(2)h))`,
+  solved by clipped gradient descent (the robust IMF). Large contaminated
+  observations have bounded influence.
+
+The library packages the algorithms validated in the IMF research project
+(`Projects/imf`) and reproduces its numerics — the robust decomposition is
+bit-identical to the reference notebook on the research example.
+
+## Install
+
+```bash
+pip install pimf
+```
+
+Requires Python >= 3.10. NumPy is the only dependency.
+
+For development, clone the repo and install in editable mode:
+
+```bash
+pip install -e .
+```
+
+## Quickstart
+
+```python
+import numpy as np
+import pimf
+
+t = np.linspace(0.0, 1.0, 1000)
+y = (
+    np.sin(2 * np.pi * t)
+    + 0.25 * np.sin(12 * np.pi * t)
+    + np.random.default_rng(0).normal(0, 0.1, 1000)
+)
+
+linear = pimf.linear_imf(y)  # quadratic contrast, closed form
+robust = pimf.robust_imf(y, h=0.2)  # smooth-abs contrast, h ~ 2 * noise sigma
+
+robust.imfs  # (K, n) array of components, coarsest first
+robust.residual  # (n,) final residual
+robust.stages  # per-stage diagnostics (window size, GD iterations, ...)
+robust.reconstruction  # imfs.sum(axis=0) + residual == y to ~1e-15
+```
+
+The general entry point is `pimf.imf(y, window_sizes=..., contrast=..., kernel=...,
+boundary=...)`; `linear_imf` and `robust_imf` are one-line wrappers around it.
+
+## Concepts
+
+**Window schedule.** `make_window_schedule(n)` generates the per-stage window
+sizes: odd, strictly decreasing, starting at about `n/2` and shrinking
+geometrically by `sqrt(2)` down to a floor of 31. Pass `window_sizes=` to
+override. Windows must be odd.
+
+**Kernel.** The window weights come from a kernel profile `k(u)` on `[-1, 1]`.
+The default `SquaredTriangle` uses `k(u) = 0.75 * (1 - |u|)^2` — the square of
+the triangular kernel. (The research project and IMF.pdf call this kernel
+"Epanechnikov"; that is a misnomer — the classical Epanechnikov kernel is
+`(3/4)(1 - u^2)` — so this library names it for what it is.) Endpoint weights
+are exactly zero, and weights are normalized to sum to one.
+
+**Contrast.** A contrast supplies the loss `rho` (via `__call__`), its
+derivative `psi` (the score), and `curvature()` — an upper bound on `rho''`
+that sets the stable gradient step `0.95 / curvature()`. A contrast with a
+closed-form minimizer can provide `solve(windows, weights)`, which the driver
+uses instead of gradient descent (that is what makes `Quadratic` the fast
+linear path). For `SmoothAbs(h)`, `h ~ 2 * sigma` of the Gaussian noise is the
+research-validated choice: smaller `h` behaves like a running median, larger
+`h` like the local mean.
+
+**Boundary.** `boundary="wrap"` (circular) is the default and the setting the
+linear-operator theory of the research project assumes; it is passed straight
+to `np.pad`, so `"reflect"` and `"edge"` also work.
+
+## Extending
+
+Custom contrast — one small class:
+
+```python
+import numpy as np
+import pimf
+
+
+class Huber(pimf.Contrast):
+    def __init__(self, delta):
+        self.delta = delta
+
+    def __call__(self, r):
+        a = np.abs(r)
+        return np.where(a <= self.delta, 0.5 * r**2, self.delta * (a - 0.5 * self.delta))
+
+    def psi(self, r):
+        return np.clip(r, -self.delta, self.delta)
+
+    def curvature(self):
+        return 1.0
+
+
+result = pimf.imf(y, contrast=Huber(0.3))
+```
+
+Custom kernel — one line:
+
+```python
+class Triangle(pimf.Kernel):
+    def profile(self, u):
+        return 1.0 - np.abs(u)
+
+
+result = pimf.imf(y, kernel=Triangle())
+```
+
+## Numerical guarantees
+
+- Exact reconstruction: `imfs.sum(axis=0) + residual` matches the input to
+  ~1e-15 (float rounding only).
+- Deterministic: no threading, no hidden state; the same input always gives
+  the same output.
+- Research parity (verified by cross-check against the reference notebook on
+  the seed-777 example): kernel weights, the erf approximation
+  (Abramowitz–Stegun 7.1.26 — deliberately kept instead of SciPy), signal
+  generation, and the full robust decomposition are bit-identical; the linear
+  path matches the loop-based notebook to ~2e-15 (float summation order — it
+  is bit-identical to the vectorized `windows @ weights` notebooks).
+
+## Development
+
+```bash
+uv sync                  # or: pip install -e . && pip install pytest ruff
+python -m pytest
+ruff check . && ruff format --check .
+```
+
+See [AGENTS.md](AGENTS.md) for the project's code style and hard rules.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pimf-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pimf/__init__.py,sha256=PoaP3c__2ImyPZrMbtiiTOewLsmsUmlRNY8GT78Np38,529
+pimf/_erf.py,sha256=Af-8ML2eUHUpgHFtXIwB1r6Uui5ySyU9XM3EgRerRl4,732
+pimf/contrasts.py,sha256=AItiF3W8m_MaIqI5Iv4LrYuGV3sLJjZJR2Xex3XdCQ4,2239
+pimf/decompose.py,sha256=D1N3ugJo9EseKSou5cIs7PAgV2xBZLSj4WK5OeWFi5Y,4781
+pimf/kernels.py,sha256=CTz5DMOh2Fif6hjakWFZnDJuVoifDSQxfuan59C-j_c,1736
+pimf/schedule.py,sha256=AbKnXFwr09pmS9celGBY-vZu94Zv0m2tVydzrdFq4Sk,1734
+pimf-0.1.0.dist-info/METADATA,sha256=ZqQY5GeeCLstSOb479-M5uTpTCrFgitdlxjHAWhbZDU,6220
+pimf-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+pimf-0.1.0.dist-info/licenses/LICENSE,sha256=rS68B5Bud03naAkRCKHRRuCiwtzQt0ydaeSxpvDKlIY,1071
+pimf-0.1.0.dist-info/RECORD,,

pimf-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pimf-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Kuziuk
+
+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.