Spaces:
Running on Zero
Running on Zero
File size: 9,837 Bytes
ed519a7 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 | """Statistics of a phase-scan error table (pure NumPy).
Input: an error table ``E`` of shape (K, W). Row k holds the per-frame reconstruction
error (RGB MSE in [-1, 1]) of the W-frame window that starts at offset k. The paper's
default is K = 24 (divisible by 2, 3, 4, 6, 8 and 12) and W = 13.
Main statistics (paper Sec. 3.1) are computed on the per-frame baseline residual
r(k) = 1 / ((W - 1) * Ebar) * sum_{j=1}^{W-1} [ e(k, j) - ebar(k + j) ],
where ebar(t) is the mean error of absolute frame t over every window that covers it
(window position j = 0 is excluded because a causal VAE encodes the first frame of a
window on its own) and Ebar is the mean of the whole table.
C{p} fraction of the residual variance in the period-p harmonic comb
(fundamental plus harmonics; C4 uses the bins of periods 4 and 2)
P{p} fraction in the fundamental bin of period p only
X8 C8 - C4, the part that only a period of 8 explains
Ppk period-agnostic score: the largest normalised periodogram bin after 4x zero
padding, restricted to periods [2.5, 9]; ppk is the period of that bin
dE4/8 alignment gain (mean residual off the lattice minus on it) / Ebar
phase4/8 offset class with the lowest mean residual (a descriptive quantity)
Suffix ``_raw``: the same comb statistics on the raw curve E(k) = mean_j E[k, j]
(kept as a reference; the paper uses the residual versions).
"""
from __future__ import annotations
import math
from typing import Iterable
import numpy as np
PERIODS = (2, 3, 4, 6, 8, 12)
def periodogram_fraction(x) -> dict[int, float]:
"""Mean-removed sequence (K,) -> share of variance per positive frequency bin j = 1..K//2."""
K = len(x)
x = np.asarray(x, dtype=np.float64) - np.mean(x)
tot = float((x ** 2).sum())
if tot <= 0:
return {j: 0.0 for j in range(1, K // 2 + 1)}
X = np.fft.fft(x)
out = {}
for j in range(1, K // 2 + 1):
w = 1.0 if 2 * j == K else 2.0 # the Nyquist bin has no conjugate partner
out[j] = float(w * abs(X[j]) ** 2 / (K * tot))
return out
def comb_fraction(frac: dict[int, float], K: int, p: int) -> float:
"""Harmonic comb of period p: bins j = m*K/p, m = 1..p//2 (requires K % p == 0)."""
if K % p != 0:
return float("nan")
return float(sum(frac[m * K // p] for m in range(1, p // 2 + 1)))
def padded_peak(x, pad: int = 4, pmin: float = 2.5, pmax: float = 9.0) -> tuple[float, float]:
"""Period-agnostic peak: zero-pad the mean-removed sequence by ``pad`` and return
(largest normalised periodogram bin with period in [pmin, pmax], its period).
Zero padding only refines the frequency grid (periods such as 5 or 7 that do not
divide K become reachable); it adds no information. The upper bound 9 avoids periods
with fewer than ~3 cycles in K = 24 offsets, where slow drift leaks in; the lower
bound 2.5 excludes period-2 patterns from frame dropping or codec pyramids.
"""
K = len(x)
x = np.asarray(x, dtype=np.float64) - np.mean(x)
tot = float((x ** 2).sum())
if tot <= 0:
return 0.0, 0.0
N = K * pad
X = np.abs(np.fft.rfft(x, n=N)) ** 2 / (K * tot) * 2.0
j = np.arange(1, N // 2 + 1)
per = N / j
band = (per >= pmin) & (per <= pmax)
jb = j[band]
if len(jb) == 0:
return 0.0, 0.0
k = int(jb[np.argmax(X[jb])])
return float(X[k]), float(N / k)
def frame_baseline_residual(E, j0: int = 1) -> np.ndarray:
"""E (K, W) -> E' (K, W - j0): subtract the mean error of each absolute frame t = k + j
(estimated from the observations with j >= j0 only)."""
E = np.asarray(E, dtype=np.float64)
K, W = E.shape
T = K - 1 + W
F, n = np.zeros(T), np.zeros(T)
for k in range(K):
F[k + j0:k + W] += E[k, j0:]
n[k + j0:k + W] += 1
F = F / np.maximum(n, 1)
R = np.empty((K, W - j0))
for k in range(K):
R[k] = E[k, j0:] - F[k + j0:k + W]
return R
def _align_gain(x, p: int) -> float:
x = np.asarray(x, dtype=np.float64)
k = np.arange(len(x))
m = x.mean()
if m <= 0:
return 0.0
return float((x[k % p != 0].mean() - x[k % p == 0].mean()) / m)
def _best_phase(x, p: int) -> int:
x = np.asarray(x, dtype=np.float64)
k = np.arange(len(x))
return int(np.argmin([x[k % p == r].mean() for r in range(p)]))
def curve_stats(Ek, suffix: str = "") -> dict:
"""Comb statistics of a raw curve E(k) (used for the ``_raw`` reference values)."""
Ek = np.asarray(Ek, dtype=np.float64)
K = len(Ek)
frac = periodogram_fraction(Ek)
out = {}
for p in PERIODS:
out[f"P{p}{suffix}"] = frac.get(K // p, float("nan")) if K % p == 0 else float("nan")
out[f"C{p}{suffix}"] = comb_fraction(frac, K, p)
out[f"X8{suffix}"] = out[f"C8{suffix}"] - out[f"C4{suffix}"]
out[f"dE4{suffix}"] = _align_gain(Ek, 4)
out[f"dE8{suffix}"] = _align_gain(Ek, 8)
out[f"phase4{suffix}"] = _best_phase(Ek, 4)
out[f"phase8{suffix}"] = _best_phase(Ek, 8)
out[f"E0{suffix}"] = float(Ek[0])
out[f"Emean{suffix}"] = float(Ek.mean())
return out
def residual_stats(R, Emean: float, suffix: str = "") -> dict:
"""Statistics of the residual table R (K, W-1); alignment gains are normalised by the
mean raw error so they keep the meaning of a relative error."""
rk = np.asarray(R, dtype=np.float64).mean(1)
K = len(rk)
frac = periodogram_fraction(rk)
out = {}
for p in PERIODS:
out[f"P{p}{suffix}"] = frac.get(K // p, float("nan")) if K % p == 0 else float("nan")
out[f"C{p}{suffix}"] = comb_fraction(frac, K, p)
out[f"X8{suffix}"] = out[f"C8{suffix}"] - out[f"C4{suffix}"]
k = np.arange(K)
for p in (4, 8):
out[f"dE{p}{suffix}"] = float((rk[k % p != 0].mean() - rk[k % p == 0].mean()) / Emean) if Emean > 0 else 0.0
out[f"phase{p}{suffix}"] = int(np.argmin([rk[k % p == r].mean() for r in range(p)]))
out[f"amp4{suffix}"] = float(rk[k % 4 != 0].mean() - rk[k % 4 == 0].mean())
jbest = max((j for j in frac if j >= 2), key=lambda j: frac[j]) if len(frac) > 1 else 1
out[f"pmax{suffix}"] = float(K / jbest)
out[f"Pmax{suffix}"] = float(frac[jbest]) if jbest in frac else 0.0
# alignment gain without assuming the aligned phase is 0 (min over the four classes)
m4 = np.array([rk[k % 4 == r].mean() for r in range(4)])
b = int(np.argmin(m4))
out[f"dE4x{suffix}"] = float((np.delete(m4, b).mean() - m4[b]) / Emean) if Emean > 0 else 0.0
out[f"Ppk{suffix}"], out[f"ppk{suffix}"] = padded_peak(rk)
return out
def phase_stats(E) -> dict:
"""Error table E (K, W) -> dict of statistics. Unsuffixed keys use the per-frame
baseline residual (the paper's definitions); ``_raw`` keys use the raw curve."""
E = np.asarray(E, dtype=np.float64)
Ek = E.mean(1)
Emean = float(Ek.mean())
s = residual_stats(frame_baseline_residual(E, 1), Emean) if E.shape[1] > 2 else {}
s.update(curve_stats(Ek, "_raw"))
s["E0"] = float(Ek[0])
s["Emean"] = Emean
return s
def residual_curve(E) -> np.ndarray:
"""The dimensionless residual profile r(k) of paper Eq. (1), centred to zero mean."""
E = np.asarray(E, dtype=np.float64)
if E.ndim != 2 or not np.all(np.isfinite(E)) or np.any(E < 0):
raise ValueError("Expected a finite non-negative (K, W) error table.")
r = frame_baseline_residual(E, 1).mean(1) / (E.mean() + 1e-12)
return r - r.mean()
def phase_angle(curve, period: int = 4) -> float:
"""Argument of the period-``period`` Fourier coefficient of a curve (radians)."""
x = np.asarray(curve, dtype=np.float64)
x = x - x.mean()
k = np.arange(len(x))
return float(np.angle(np.sum(x * np.exp(-2j * np.pi * k / period))))
def phase_concentration(angles: Iterable[float]) -> float:
"""R = |mean_i exp(i * phi_i)| in [0, 1]: 0 for dispersed phases, 1 for identical ones."""
a = np.asarray(list(angles), dtype=np.float64)
if len(a) == 0:
return float("nan")
return float(abs(np.mean(np.exp(1j * a))))
def spectrum(curve, pmin: float = 2.5, pmax: float = 12.0) -> dict:
"""Normalised power of a curve over periods [pmin, pmax] (4x zero padding), for plots."""
x = np.asarray(curve, dtype=np.float64)
x = x - x.mean()
total = float(np.square(x).sum())
size = 4 * len(x)
power = np.zeros(size // 2 + 1) if total <= 1e-24 else 2 * np.abs(np.fft.rfft(x, n=size)) ** 2 / (len(x) * total)
periods = size / np.arange(1, len(power))
band = (periods >= pmin) & (periods <= pmax)
periods, power = periods[band], power[1:][band]
order = np.argsort(periods)
return {"periods": periods[order].tolist(), "power": power[order].tolist()}
__all__ = [
"PERIODS", "periodogram_fraction", "comb_fraction", "padded_peak", "frame_baseline_residual",
"curve_stats", "residual_stats", "phase_stats", "residual_curve", "phase_angle",
"phase_concentration", "spectrum",
]
def _self_test() -> None: # pragma: no cover - exercised by tests/test_stats.py
rng = np.random.default_rng(0)
K, W = 24, 33
D = 1.0 + 0.5 * rng.random(K - 1 + W) + 0.02 * np.arange(K - 1 + W)
Ef = np.array([[D[k + j] * (0.8 if k % 4 == 0 else 1.0) for j in range(W)] for k in range(K)])
sf = phase_stats(Ef + 0.005 * rng.standard_normal((K, W)))
assert sf["C4"] > 0.9 and sf["dE4"] > 0.1 and sf["phase4"] == 0
Er = np.array([[D[k + j] for j in range(W)] for k in range(K)])
sr = phase_stats(Er + 0.005 * rng.standard_normal((K, W)))
assert sr["C4"] < 0.5 and abs(sr["dE4"]) < 0.02
assert math.isclose(sum(periodogram_fraction(rng.standard_normal(K)).values()), 1.0, abs_tol=1e-9)
if __name__ == "__main__": # pragma: no cover
_self_test()
print("stats self-test ok")
|