- 命名规则移入 spectro_core.default_output_directory(root, stem, indices) - wavelength_calibration 默认改为 calibration_exports/<recording>_f<frame>,与 peak_exports 一致;输入为 peaks.json 时镜像其所在目录名 - 新增 3 项命名测试
876 lines
36 KiB
Python
876 lines
36 KiB
Python
#!/usr/bin/env python3
|
|
"""Shared core for the spectro tools: loading, calibration, peak detection, output.
|
|
|
|
Extracted from peak_finder.py so that wavelength_calibration.py, wavelength_player.py
|
|
and hq_average.py can call the same code instead of keeping their own copies.
|
|
|
|
No command line and no matplotlib at import time; plotting helpers stay in the
|
|
scripts that need them. Everything here is pure NumPy.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import csv
|
|
import importlib.util
|
|
import json
|
|
import math
|
|
import sys
|
|
from pathlib import Path
|
|
from typing import Optional
|
|
|
|
import numpy as np
|
|
|
|
CORE_DIR = Path(__file__).resolve().parent
|
|
GAUSS_TO_FWHM = 2.3548200450309493
|
|
|
|
|
|
def load_hq(module_dir: Optional[str] = None) -> object:
|
|
"""Import hq_spectrum.py from this folder (or ``module_dir``) by path."""
|
|
|
|
candidates = [Path(module_dir).expanduser()] if module_dir else [CORE_DIR, Path.cwd()]
|
|
for directory in candidates:
|
|
path = directory / "hq_spectrum.py"
|
|
if path.is_file():
|
|
spec = importlib.util.spec_from_file_location("hq_spectrum_shared", path)
|
|
module = importlib.util.module_from_spec(spec)
|
|
sys.modules[spec.name] = module
|
|
spec.loader.exec_module(module)
|
|
return module
|
|
try: # last resort: a normal import from sys.path
|
|
import hq_spectrum as module # type: ignore
|
|
except ImportError as exc:
|
|
raise RuntimeError("cannot find hq_spectrum.py; put it beside spectro_core.py "
|
|
"or use --module-dir") from exc
|
|
return module
|
|
|
|
|
|
def is_saturated(image: np.ndarray, roi, x_center: float, full_scale: float,
|
|
band: tuple[int, int] = (-2, 4), threshold: float = 0.01) -> bool:
|
|
"""True when a meaningful fraction of the pixels near ``x_center`` is clipped."""
|
|
|
|
x0 = max(0, min(int(x_center) + band[0], image.shape[1]))
|
|
x1 = max(0, min(int(x_center) + band[1], image.shape[1]))
|
|
block = image[roi.y0:roi.y1, x0:x1]
|
|
if block.size == 0:
|
|
return False
|
|
return float(np.mean(block >= 0.995 * full_scale)) > threshold
|
|
|
|
|
|
def _num(value, digits: int = 6) -> str:
|
|
"""Format a value for CSV output; non-finite values become empty cells."""
|
|
|
|
if value is None:
|
|
return ""
|
|
if isinstance(value, (bool, np.bool_)):
|
|
return "1" if value else "0"
|
|
if isinstance(value, str):
|
|
return value
|
|
try:
|
|
number = float(value)
|
|
except (TypeError, ValueError):
|
|
return str(value)
|
|
if not np.isfinite(number):
|
|
return ""
|
|
return f"{number:.{digits}g}"
|
|
|
|
|
|
def write_csv(path: Path, fields: list[str], rows) -> None:
|
|
with path.open("w", newline="", encoding="utf-8") as handle:
|
|
writer = csv.writer(handle)
|
|
writer.writerow(fields)
|
|
for row in rows:
|
|
writer.writerow(row)
|
|
|
|
|
|
def _jsonable(value):
|
|
"""Convert NumPy scalars/arrays and Paths into plain JSON values."""
|
|
|
|
if isinstance(value, dict):
|
|
return {str(k): _jsonable(v) for k, v in value.items()}
|
|
if isinstance(value, (list, tuple)):
|
|
return [_jsonable(v) for v in value]
|
|
if isinstance(value, np.ndarray):
|
|
return [_jsonable(v) for v in value.tolist()]
|
|
if isinstance(value, (np.floating, np.integer, np.bool_)):
|
|
return value.item()
|
|
if isinstance(value, Path):
|
|
return str(value)
|
|
return value
|
|
|
|
|
|
def write_json(path, value) -> None:
|
|
"""Write JSON with NumPy/Path values converted and a trailing newline."""
|
|
|
|
Path(path).write_text(json.dumps(_jsonable(value), indent=2) + "\n", encoding="utf-8")
|
|
|
|
|
|
class Calibration:
|
|
"""Polynomial sensor-pixel -> wavelength saved by wavelength_calibration.py."""
|
|
|
|
def __init__(self, path, offset_nm: float = 0.0):
|
|
self.path = Path(path).expanduser().resolve()
|
|
try:
|
|
self.data = json.loads(self.path.read_text(encoding="utf-8-sig"))
|
|
except OSError as exc:
|
|
raise ValueError(f"cannot read calibration {self.path}: {exc}") from exc
|
|
except json.JSONDecodeError as exc:
|
|
raise ValueError(f"calibration {self.path} is not valid JSON: {exc}") from exc
|
|
if not isinstance(self.data, dict):
|
|
raise ValueError("calibration JSON must contain an object")
|
|
coeff = np.asarray(self.data.get("coefficients_descending"), dtype=float)
|
|
if coeff.ndim != 1 or len(coeff) not in (2, 3):
|
|
raise ValueError("calibration needs 2 or 3 descending coefficients")
|
|
if not np.all(np.isfinite(coeff)) or coeff[0] == 0:
|
|
raise ValueError("calibration coefficients must be finite and the leading one nonzero")
|
|
if self.data.get("order", len(coeff) - 1) != len(coeff) - 1:
|
|
raise ValueError("calibration order does not match coefficient count")
|
|
self.coeff = coeff
|
|
span = np.asarray(self.data.get("calibrated_pixel_range"), dtype=float)
|
|
if span.shape != (2,) or not np.all(np.isfinite(span)) or span[0] >= span[1]:
|
|
raise ValueError("calibration has an invalid calibrated_pixel_range")
|
|
self.span = span
|
|
self.offset_nm = float(offset_nm)
|
|
if not np.isfinite(self.offset_nm):
|
|
raise ValueError("wavelength offset must be finite")
|
|
self.width: Optional[int] = None
|
|
self._grid_px = None
|
|
self._grid_nm = None
|
|
|
|
def __call__(self, x):
|
|
return np.polyval(self.coeff, np.asarray(x, dtype=float)) + self.offset_nm
|
|
|
|
def dispersion(self, x) -> np.ndarray:
|
|
"""Local nm per sensor pixel (never zero over a validated sensor)."""
|
|
|
|
return np.polyval(np.polyder(self.coeff), np.asarray(x, dtype=float))
|
|
|
|
def set_width(self, width: int) -> None:
|
|
self.width = int(width)
|
|
grid = np.arange(self.width, dtype=float)
|
|
values = np.asarray(self(grid), dtype=float)
|
|
order = np.argsort(values)
|
|
self._grid_px = grid[order]
|
|
self._grid_nm = values[order]
|
|
|
|
def inverse(self, wavelength):
|
|
"""Sensor pixel of a wavelength; used for the secondary plot axis only."""
|
|
|
|
if self._grid_nm is None:
|
|
raise ValueError("calibration width is unknown")
|
|
return np.interp(np.asarray(wavelength, dtype=float), self._grid_nm, self._grid_px)
|
|
|
|
@property
|
|
def nm_span(self) -> tuple[float, float]:
|
|
values = sorted(np.asarray(self(self.span), dtype=float).tolist())
|
|
return float(values[0]), float(values[1])
|
|
|
|
def describe(self) -> str:
|
|
low, high = self.nm_span
|
|
text = (f"JSON calibration ({self.data.get('wavelength_medium', 'air')}); "
|
|
f"confirmed {low:.2f}-{high:.2f} nm; outside = extrapolation")
|
|
if self.offset_nm:
|
|
text += f"; manual offset {self.offset_nm:+.3f} nm"
|
|
return text
|
|
|
|
def validate_geometry(self, source, tell=None) -> None:
|
|
"""Refuse a recording whose sensor geometry differs from the calibration."""
|
|
|
|
tell = tell or (lambda *args, **kwargs: None)
|
|
derivative = self.dispersion([0.0, float(source.full_size[0] - 1)])
|
|
if np.any(np.abs(derivative) < 1e-12) or derivative[0] * derivative[1] <= 0:
|
|
raise ValueError("calibration is not monotonic over this recording width")
|
|
reference = self.data.get("recording")
|
|
metadata = Path(reference) / "meta.json" if reference else None
|
|
if metadata is not None and metadata.is_file():
|
|
reference_meta = json.loads(metadata.read_text(encoding="utf-8-sig"))
|
|
size = (int(reference_meta["width"]), int(reference_meta["height"]))
|
|
if size != tuple(source.full_size):
|
|
raise ValueError("recording dimensions differ from the calibration recording; "
|
|
"recalibrate this sensor mode")
|
|
else:
|
|
tell("note : calibration reference recording unavailable; sensor size not checked")
|
|
if self.data.get("pattern") and self.data["pattern"] != source.pattern:
|
|
tell(f"note : calibration pattern {self.data['pattern']} differs from "
|
|
f"recording pattern {source.pattern}")
|
|
|
|
|
|
def _rank_filter(y: np.ndarray, width: int, reducer) -> np.ndarray:
|
|
"""Running min/max over the window [i - width, i + width] with edge padding."""
|
|
|
|
width = max(0, int(width))
|
|
values = np.asarray(y, dtype=float)
|
|
if width == 0 or values.size <= 1:
|
|
return values.copy()
|
|
n = values.size
|
|
padded = np.pad(values, (width, width), mode="edge")
|
|
out = padded[width:width + n].copy()
|
|
for shift in range(-width, width + 1):
|
|
start = width + shift
|
|
reducer(out, padded[start:start + n], out=out)
|
|
return out
|
|
|
|
|
|
def _min_filter(y: np.ndarray, width: int) -> np.ndarray:
|
|
return _rank_filter(y, width, np.minimum)
|
|
|
|
|
|
def _max_filter(y: np.ndarray, width: int) -> np.ndarray:
|
|
return _rank_filter(y, width, np.maximum)
|
|
|
|
|
|
def estimate_baseline(y: np.ndarray, window_samples: int, smooth) -> np.ndarray:
|
|
"""Morphological opening baseline; removes peaks narrower than the window."""
|
|
|
|
width = max(0, int(window_samples))
|
|
if width == 0 or np.size(y) <= 2:
|
|
return np.zeros_like(np.asarray(y, dtype=float))
|
|
opened = _max_filter(_min_filter(np.asarray(y, dtype=float), width), width)
|
|
return smooth(opened.astype(np.float32), max(1, width // 2)).astype(float)
|
|
|
|
|
|
def estimate_noise(net: np.ndarray) -> float:
|
|
"""Robust noise proxy from the median absolute first difference."""
|
|
|
|
if np.size(net) < 3:
|
|
return 0.0
|
|
diff = np.diff(np.asarray(net, dtype=float))
|
|
mad = float(np.median(np.abs(diff - np.median(diff))))
|
|
return mad / (0.6745 * math.sqrt(2.0))
|
|
|
|
|
|
def parabola_center(x: np.ndarray, y: np.ndarray, index: int) -> float:
|
|
"""Sub-sample vertex of the parabola through three samples (NaN if unusable)."""
|
|
|
|
if index <= 0 or index >= y.size - 1:
|
|
return float("nan")
|
|
y0, y1, y2 = float(y[index - 1]), float(y[index]), float(y[index + 1])
|
|
denominator = y0 - 2.0 * y1 + y2
|
|
if not np.isfinite(denominator) or denominator == 0.0:
|
|
return float("nan")
|
|
delta = 0.5 * (y0 - y2) / denominator
|
|
if not np.isfinite(delta) or abs(delta) > 1.0:
|
|
return float("nan")
|
|
step = float(x[index + 1] - x[index])
|
|
return float(x[index] + delta * step)
|
|
|
|
|
|
def half_max_crossings(x: np.ndarray, net: np.ndarray, index: int,
|
|
max_span: int) -> tuple[float, float]:
|
|
"""Linearly interpolated x positions where the net signal falls to half max."""
|
|
|
|
peak = float(net[index])
|
|
if not np.isfinite(peak) or peak <= 0.0:
|
|
return float("nan"), float("nan")
|
|
half = 0.5 * peak
|
|
span = max(1, int(max_span))
|
|
left = index
|
|
floor_index = max(0, index - span)
|
|
while left > floor_index and net[left] > half:
|
|
left -= 1
|
|
right = index
|
|
ceiling = min(net.size - 1, index + span)
|
|
while right < ceiling and net[right] > half:
|
|
right += 1
|
|
|
|
left_x = right_x = float("nan")
|
|
if left < index and net[left] <= half:
|
|
rise = float(net[left + 1] - net[left])
|
|
left_x = float(x[left] + (half - net[left]) / rise * (x[left + 1] - x[left])) \
|
|
if rise > 0 else float(x[left])
|
|
if right > index and net[right] <= half:
|
|
fall = float(net[right - 1] - net[right])
|
|
right_x = float(x[right] - (net[right] - half) / fall * (x[right] - x[right - 1])) \
|
|
if fall > 0 else float(x[right])
|
|
return left_x, right_x
|
|
|
|
|
|
def _core(x: np.ndarray, amplitude: float, center: float, width: float,
|
|
shape: str) -> np.ndarray:
|
|
offset = x - center
|
|
if shape == "lorentz":
|
|
return amplitude / (1.0 + (offset / width) ** 2)
|
|
return amplitude * np.exp(-0.5 * (offset / width) ** 2)
|
|
|
|
|
|
def _shape_model(x: np.ndarray, params: np.ndarray, xref: float, shape: str) -> np.ndarray:
|
|
amplitude, center, width, c0, c1 = params
|
|
return _core(x, amplitude, center, width, shape) + c0 + c1 * (x - xref)
|
|
|
|
|
|
def _multi_model(x: np.ndarray, params: np.ndarray, xref: float, shape: str,
|
|
peaks: int) -> np.ndarray:
|
|
"""1..N shape components plus a linear background; params = 3*N + 2."""
|
|
|
|
total = np.zeros_like(x, dtype=float)
|
|
for index in range(peaks):
|
|
amplitude, center, width = params[3 * index:3 * index + 3]
|
|
total = total + _core(x, amplitude, center, width, shape)
|
|
return total + params[3 * peaks] + params[3 * peaks + 1] * (x - xref)
|
|
|
|
|
|
def fit_profile(x: np.ndarray, y: np.ndarray, start: list[float], shape: str,
|
|
bounds: list[tuple[float, float]], max_iter: int = 200,
|
|
peaks: int = 1, shared_width: bool = False) -> dict:
|
|
"""Fit 1..N peak components + linear background; returns parameters and flags.
|
|
|
|
``shared_width`` fits one common line width for all components, which is the
|
|
physically sensible and numerically stable model for an unresolved doublet.
|
|
Parameter layout: per component ``A, mu(, sigma)`` then ``c0, c1``; with a
|
|
shared width the single ``sigma`` is appended before ``c0, c1``.
|
|
"""
|
|
|
|
x = np.asarray(x, dtype=float)
|
|
y = np.asarray(y, dtype=float)
|
|
peaks = int(peaks)
|
|
per_peak = 2 if shared_width else 3
|
|
background = per_peak * peaks
|
|
if x.size < background + 3 or not np.all(np.isfinite(y)):
|
|
return {"ok": False}
|
|
xref = float(np.mean(x))
|
|
lower = np.array([bound[0] for bound in bounds], dtype=float)
|
|
upper = np.array([bound[1] for bound in bounds], dtype=float)
|
|
params = np.clip(np.asarray(start, dtype=float), lower, upper)
|
|
|
|
def model(values, parameters):
|
|
shared = parameters[2 * peaks] if shared_width else None
|
|
total = np.zeros_like(values, dtype=float)
|
|
for index in range(peaks):
|
|
if shared_width:
|
|
amplitude, center = parameters[2 * index], parameters[2 * index + 1]
|
|
width = shared
|
|
else:
|
|
amplitude, center, width = parameters[3 * index:3 * index + 3]
|
|
total = total + _core(values, amplitude, center, width, shape)
|
|
return total + parameters[background] + parameters[background + 1] * (values - xref)
|
|
|
|
residual = y - model(x, params)
|
|
cost = float(np.sum(residual * residual))
|
|
if not np.isfinite(cost):
|
|
return {"ok": False}
|
|
lam = 1e-3
|
|
converged = False
|
|
for _ in range(max_iter):
|
|
base = model(x, params)
|
|
jacobian = np.empty((x.size, params.size))
|
|
for j in range(params.size):
|
|
step = 1e-6 * max(1.0, abs(params[j]))
|
|
probe = params.copy()
|
|
probe[j] += step
|
|
jacobian[:, j] = (model(x, probe) - base) / step
|
|
normal = jacobian.T @ jacobian
|
|
gradient = jacobian.T @ residual
|
|
diagonal = np.diag(np.diag(normal)) + 1e-12 * np.eye(params.size)
|
|
relative = 1.0
|
|
stepped = False
|
|
for _ in range(40):
|
|
try:
|
|
delta = np.linalg.solve(normal + lam * diagonal, gradient)
|
|
except np.linalg.LinAlgError:
|
|
lam *= 10.0
|
|
continue
|
|
trial = np.clip(params + delta, lower, upper)
|
|
trial_residual = y - model(x, trial)
|
|
trial_cost = float(np.sum(trial_residual * trial_residual))
|
|
if np.isfinite(trial_cost) and trial_cost < cost:
|
|
relative = (cost - trial_cost) / max(cost, 1e-30)
|
|
params, residual, cost = trial, trial_residual, trial_cost
|
|
lam = max(lam / 3.0, 1e-15)
|
|
stepped = True
|
|
break
|
|
lam *= 10.0
|
|
if not stepped or relative < 1e-12:
|
|
converged = True
|
|
break
|
|
|
|
rms = float(np.sqrt(cost / max(1, x.size)))
|
|
# Parameter errors from the normal matrix at the final parameters; scale the
|
|
# columns first because amplitude, centre and width differ by orders of magnitude.
|
|
try:
|
|
base = model(x, params)
|
|
jacobian = np.empty((x.size, params.size))
|
|
for j in range(params.size):
|
|
step = 1e-6 * max(1.0, abs(params[j]))
|
|
probe = params.copy()
|
|
probe[j] += step
|
|
jacobian[:, j] = (model(x, probe) - base) / step
|
|
normal = jacobian.T @ jacobian
|
|
scale = np.sqrt(np.maximum(np.diag(normal), 1e-300))
|
|
correlation = normal / np.outer(scale, scale)
|
|
try:
|
|
inverse = np.linalg.inv(correlation)
|
|
except np.linalg.LinAlgError:
|
|
inverse = np.linalg.pinv(correlation)
|
|
variance = cost / max(1, x.size - params.size)
|
|
errors = np.sqrt(np.clip(np.diag(inverse) * variance, 0.0, None)) / scale
|
|
except (np.linalg.LinAlgError, ValueError, FloatingPointError):
|
|
errors = np.full(params.size, float("nan"))
|
|
components = []
|
|
usable = bool(converged and np.isfinite(params).all())
|
|
for index in range(peaks):
|
|
if shared_width:
|
|
amplitude = float(params[2 * index])
|
|
center = float(params[2 * index + 1])
|
|
width = float(params[2 * peaks])
|
|
low, high = lower[2 * peaks], upper[2 * peaks]
|
|
amplitude_err = float(errors[2 * index])
|
|
center_err = float(errors[2 * index + 1])
|
|
width_err = float(errors[2 * peaks])
|
|
else:
|
|
amplitude = float(params[3 * index])
|
|
center = float(params[3 * index + 1])
|
|
width = float(params[3 * index + 2])
|
|
low, high = lower[3 * index + 2], upper[3 * index + 2]
|
|
amplitude_err = float(errors[3 * index])
|
|
center_err = float(errors[3 * index + 1])
|
|
width_err = float(errors[3 * index + 2])
|
|
width_at_bound = bool(width <= low * (1 + 1e-6) or width >= high * (1 - 1e-6))
|
|
if amplitude <= 0 or width <= 0 or width_at_bound:
|
|
usable = False
|
|
if not x[0] - 1.0 <= center <= x[-1] + 1.0:
|
|
usable = False
|
|
fwhm = 2.0 * width if shape == "lorentz" else GAUSS_TO_FWHM * width
|
|
components.append({"amplitude": amplitude, "center": center,
|
|
"width": width, "fwhm": float(fwhm),
|
|
"amplitude_err": amplitude_err, "center_err": center_err,
|
|
"width_err": width_err,
|
|
"width_at_bound": width_at_bound})
|
|
first = components[0]
|
|
return {
|
|
"ok": usable,
|
|
"peaks": peaks,
|
|
"params": params.tolist(),
|
|
"xref": xref,
|
|
"components": components,
|
|
"center": first["center"],
|
|
"width": first["width"],
|
|
"amplitude": first["amplitude"],
|
|
"fwhm": first["fwhm"],
|
|
"c0": float(params[background]),
|
|
"c1": float(params[background + 1]),
|
|
"rms": rms,
|
|
"converged": converged,
|
|
"at_bound": any(item["width_at_bound"] for item in components),
|
|
"n_points": int(x.size),
|
|
}
|
|
|
|
|
|
def model_values(x, params, xref: float, shape: str) -> np.ndarray:
|
|
if not params:
|
|
return np.full(np.shape(x), np.nan, dtype=float)
|
|
return _shape_model(np.asarray(x, dtype=float), np.asarray(params, dtype=float), xref, shape)
|
|
|
|
|
|
def peak_prominence(net: np.ndarray, index: int) -> tuple[float, float]:
|
|
"""True topographic prominence of a local maximum and the level it sits on.
|
|
|
|
Walk outwards until the profile rises above the peak or the array ends; the
|
|
prominence base is the higher of the two minima on the way. Unlike a fixed
|
|
window this keeps resolved doublets apart and rejects shoulders.
|
|
"""
|
|
|
|
height = float(net[index])
|
|
left = index
|
|
left_min = height
|
|
while left > 0:
|
|
left -= 1
|
|
value = float(net[left])
|
|
if value > height:
|
|
break
|
|
if value < left_min:
|
|
left_min = value
|
|
right = index
|
|
right_min = height
|
|
while right < net.size - 1:
|
|
right += 1
|
|
value = float(net[right])
|
|
if value > height:
|
|
break
|
|
if value < right_min:
|
|
right_min = value
|
|
base = max(left_min, right_min)
|
|
return height - base, base
|
|
|
|
|
|
def find_peak_candidates(net: np.ndarray, min_distance: int, min_height: float,
|
|
min_prominence: float, max_peaks: int) -> list[dict]:
|
|
"""Local maxima with plateau centring, true prominence and neighbour suppression."""
|
|
|
|
n = net.size
|
|
if n < 3 or max_peaks <= 0:
|
|
return []
|
|
candidates = []
|
|
index = 1
|
|
while index < n - 1:
|
|
if net[index] > net[index - 1]:
|
|
end = index
|
|
while end + 1 < n and net[end + 1] == net[index]:
|
|
end += 1
|
|
if end + 1 < n and net[end] > net[end + 1]:
|
|
candidates.append((index + end) // 2)
|
|
index = end + 1
|
|
else:
|
|
index += 1
|
|
if not candidates:
|
|
return []
|
|
|
|
candidates.sort(key=lambda i: float(net[i]), reverse=True)
|
|
kept: list[dict] = []
|
|
for index in candidates:
|
|
height = float(net[index])
|
|
if height < min_height:
|
|
continue
|
|
if any(abs(index - other["sample"]) < max(1, int(min_distance)) for other in kept):
|
|
continue
|
|
prominence, base = peak_prominence(net, index)
|
|
if prominence < min_prominence:
|
|
continue
|
|
kept.append({"sample": int(index), "height_adu": height,
|
|
"base_adu": base, "prominence_adu": float(prominence)})
|
|
if len(kept) >= max_peaks:
|
|
break
|
|
return kept
|
|
|
|
|
|
def refine_peak(x: np.ndarray, net: np.ndarray, raw: np.ndarray, candidate: dict,
|
|
noise: float, step_px: float, fwhm_span: int, fit_window: int,
|
|
shape: str, saturated: bool, baseline_value: float = 0.0) -> dict:
|
|
"""Measure one detected peak: centre, width, height, area and fit quality."""
|
|
|
|
index = candidate["sample"]
|
|
n = net.size
|
|
left_x, right_x = half_max_crossings(x, net, index, fwhm_span)
|
|
fwhm_measured = (right_x - left_x
|
|
if np.isfinite(left_x) and np.isfinite(right_x) else float("nan"))
|
|
|
|
if fit_window > 0:
|
|
window_px = float(fit_window) * step_px
|
|
elif np.isfinite(fwhm_measured):
|
|
window_px = float(np.clip(2.0 * fwhm_measured, 8.0 * step_px, 90.0 * step_px))
|
|
else:
|
|
window_px = 15.0 * step_px
|
|
lower = int(index)
|
|
while lower > 0 and x[index] - x[lower] < window_px:
|
|
lower -= 1
|
|
upper = int(index)
|
|
while upper < n - 1 and x[upper] - x[index] < window_px:
|
|
upper += 1
|
|
|
|
center_parabola = parabola_center(x, net, index)
|
|
|
|
start_center = center_parabola if np.isfinite(center_parabola) else float(x[index])
|
|
start_width = fwhm_measured / (2.0 if shape == "lorentz" else GAUSS_TO_FWHM)
|
|
if not np.isfinite(start_width) or start_width <= 0:
|
|
start_width = 2.0 * step_px
|
|
span_px = float(x[upper] - x[lower])
|
|
bounds = [
|
|
(0.0, 10.0 * candidate["height_adu"] + 1.0),
|
|
(x[lower] - span_px, x[upper] + span_px),
|
|
(0.4 * step_px, max(4.0 * start_width, 0.5 * span_px)),
|
|
(-5.0 * candidate["height_adu"] - 1.0, 5.0 * candidate["height_adu"] + 1.0),
|
|
(-1e4, 1e4),
|
|
]
|
|
fit = fit_profile(x[lower:upper + 1], net[lower:upper + 1],
|
|
[candidate["height_adu"], start_center, start_width, 0.0, 0.0],
|
|
shape, bounds)
|
|
if fit.get("ok") and (fit["amplitude"] < 0.25 * candidate["height_adu"]
|
|
or fit["rms"] > 0.2 * fit["amplitude"]):
|
|
# Reject a fit that misses the measured peak: keep the robust estimators.
|
|
fit["ok"] = False
|
|
|
|
if fit.get("ok"):
|
|
center, fwhm, source = fit["center"], fit["fwhm"], "fit"
|
|
elif np.isfinite(center_parabola):
|
|
# Model-free vertex of the measured maximum: still a peak position.
|
|
center, fwhm, source = center_parabola, fwhm_measured, "apex"
|
|
else:
|
|
# Flat or saturated top makes the parabola unusable; report the sample
|
|
# where the maximum was detected rather than a window-dependent moment.
|
|
center, fwhm, source = float(x[index]), fwhm_measured, "sample"
|
|
|
|
height = float(net[index])
|
|
if fit.get("ok") and fit["amplitude"] > height:
|
|
height = float(fit["amplitude"])
|
|
return {
|
|
"sample_index": int(index),
|
|
"sensor_x_px": float(x[index]),
|
|
"center_px": float(center),
|
|
"center_source": source,
|
|
"center_parabola_px": float(center_parabola) if np.isfinite(center_parabola) else float("nan"),
|
|
"center_fit_px": float(fit["center"]) if fit.get("ok") else float("nan"),
|
|
"center_err_px": float(fit["components"][0]["center_err"]) if fit.get("ok") else float("nan"),
|
|
"sigma_px": float(fit["width"]) if fit.get("ok") else float("nan"),
|
|
"fwhm_px": float(fwhm) if np.isfinite(fwhm) else float("nan"),
|
|
"fwhm_halfmax_px": float(fwhm_measured) if np.isfinite(fwhm_measured) else float("nan"),
|
|
"height_net_adu": height,
|
|
"prominence_adu": float(candidate["prominence_adu"]),
|
|
"raw_adu": float(raw[index]),
|
|
"baseline_adu": float(baseline_value),
|
|
"snr": float(height / noise) if noise > 0 else float("inf"),
|
|
"area_net_adu_px": float(np.sum(np.maximum(net[lower:upper + 1], 0.0)) * step_px),
|
|
"saturated": bool(saturated),
|
|
"fit_ok": bool(fit.get("ok")),
|
|
"fit_rms_adu": float(fit["rms"]) if fit.get("ok") else float("nan"),
|
|
"fit_shape": shape,
|
|
"fit_params": fit.get("params") if fit.get("ok") else None,
|
|
"fit_xref": fit.get("xref") if fit.get("ok") else None,
|
|
"deblended": False,
|
|
"window_lo_px": float(x[lower]),
|
|
"window_hi_px": float(x[upper]),
|
|
"window_lo_sample": int(lower),
|
|
"window_hi_sample": int(upper),
|
|
}
|
|
|
|
|
|
def _fit_pair(x: np.ndarray, net: np.ndarray, first: dict, second: dict,
|
|
shape: str, step_px: float, noise: float) -> Optional[list[dict]]:
|
|
"""Joint two-component fit of a blended pair; None if it is not trustworthy."""
|
|
|
|
lower = min(first["window_lo_sample"], second["window_lo_sample"])
|
|
upper = max(first["window_hi_sample"], second["window_hi_sample"])
|
|
xx = x[lower:upper + 1]
|
|
yy = net[lower:upper + 1]
|
|
if xx.size < 11:
|
|
return None
|
|
starts: list[float] = []
|
|
bounds: list[tuple[float, float]] = []
|
|
separation = abs(float(second["sensor_x_px"]) - float(first["sensor_x_px"]))
|
|
widths = []
|
|
for peak in (first, second):
|
|
height = max(float(peak["height_net_adu"]), 1.0)
|
|
# Start from the detected maximum, not from the biased single-peak fit.
|
|
center = float(peak["sensor_x_px"])
|
|
width = float(peak["sigma_px"]) if np.isfinite(peak["sigma_px"]) and peak["sigma_px"] > 0 \
|
|
else 2.0 * step_px
|
|
widths.append(width)
|
|
starts.extend([height, center])
|
|
bounds.extend([(0.0, 10.0 * height + 1.0),
|
|
(center - 3.5 * step_px, center + 3.5 * step_px)])
|
|
# One shared line width: two components of the same blend come from the same
|
|
# instrument, and independent widths make the fit ill-conditioned.
|
|
shared = max(0.4 * step_px, min(max(widths), 0.5 * max(separation, step_px)))
|
|
starts.append(shared)
|
|
bounds.append((0.4 * step_px, max(8.0 * max(widths), 4.0 * step_px)))
|
|
scale = max(float(first["height_net_adu"]), float(second["height_net_adu"]), 1.0)
|
|
starts.extend([0.0, 0.0])
|
|
bounds.extend([(-3.0 * scale, 3.0 * scale), (-1e4, 1e4)])
|
|
|
|
fit = fit_profile(xx, yy, starts, shape, bounds, peaks=2, shared_width=True)
|
|
if not fit.get("ok"):
|
|
return None
|
|
components = fit["components"]
|
|
if components[1]["center"] - components[0]["center"] < 0.5 * step_px:
|
|
# The two components collapsed onto each other: this is one feature.
|
|
return None
|
|
if abs(components[0]["center"] - first["sensor_x_px"]) > 3.5 * step_px:
|
|
return None
|
|
if abs(components[1]["center"] - second["sensor_x_px"]) > 3.5 * step_px:
|
|
return None
|
|
|
|
updated = []
|
|
for peak, component in zip((first, second), components):
|
|
merged = dict(peak)
|
|
merged.update({
|
|
"center_px": float(component["center"]),
|
|
"center_fit_px": float(component["center"]),
|
|
"center_err_px": float(component["center_err"]),
|
|
"center_source": "pair",
|
|
"sigma_px": float(component["width"]),
|
|
"fwhm_px": float(component["fwhm"]),
|
|
"height_net_adu": float(component["amplitude"]),
|
|
"snr": float(component["amplitude"] / noise) if noise > 0 else float("inf"),
|
|
"fit_ok": True,
|
|
"fit_rms_adu": float(fit["rms"]),
|
|
"fit_params": [component["amplitude"], component["center"],
|
|
component["width"], 0.0, 0.0],
|
|
"fit_xref": float(fit["xref"]),
|
|
"deblended": True,
|
|
})
|
|
updated.append(merged)
|
|
return updated
|
|
|
|
|
|
def deblend_close_peaks(x: np.ndarray, net: np.ndarray, peaks: list[dict], shape: str,
|
|
step_px: float, noise: float, blend_factor: float = 1.2) -> list[dict]:
|
|
"""Refit unresolved pairs jointly instead of pulling their centres together."""
|
|
|
|
ordered = sorted(peaks, key=lambda item: item["sensor_x_px"])
|
|
result: list[dict] = []
|
|
index = 0
|
|
while index < len(ordered):
|
|
current = ordered[index]
|
|
if index + 1 < len(ordered):
|
|
neighbour = ordered[index + 1]
|
|
width_a = current["fwhm_px"] if np.isfinite(current["fwhm_px"]) else 4.0 * step_px
|
|
width_b = neighbour["fwhm_px"] if np.isfinite(neighbour["fwhm_px"]) else 4.0 * step_px
|
|
# Use the detected maxima: the fitted centres of a blend can cross.
|
|
separation = float(neighbour["sensor_x_px"] - current["sensor_x_px"])
|
|
if 0.0 < separation <= blend_factor * 0.5 * (width_a + width_b):
|
|
pair = _fit_pair(x, net, current, neighbour, shape, step_px, noise)
|
|
if pair is not None:
|
|
result.extend(pair)
|
|
index += 2
|
|
continue
|
|
result.append(current)
|
|
index += 1
|
|
return result
|
|
|
|
|
|
def dedupe_channel_peaks(peaks: list[dict], min_distance_px: float) -> list[dict]:
|
|
"""Drop repeated maxima closer than the peak distance, using detection positions.
|
|
|
|
The fitted centre of a blended line is pulled towards its neighbour, so the
|
|
distance is measured between the raw local maxima (``sensor_x_px``) and not
|
|
between the refined centres; otherwise a resolved doublet can collapse.
|
|
"""
|
|
|
|
kept: list[dict] = []
|
|
for peak in sorted(peaks, key=lambda item: item["height_net_adu"], reverse=True):
|
|
if any(abs(peak["sensor_x_px"] - other["sensor_x_px"]) < min_distance_px
|
|
for other in kept):
|
|
continue
|
|
kept.append(peak)
|
|
kept.sort(key=lambda item: item["sensor_x_px"])
|
|
return kept
|
|
|
|
|
|
def summarise_line(members: dict[str, dict]) -> dict:
|
|
"""Combine the per-channel peaks of one line into a line record (no id)."""
|
|
|
|
for channel, item in members.items():
|
|
item["channel"] = channel
|
|
items = list(members.values())
|
|
strongest = max((item["height_net_adu"] for item in items), default=0.0)
|
|
weights = np.array([
|
|
max(0.0, item["height_net_adu"]) if item["height_net_adu"] >= 0.25 * strongest else 0.0
|
|
for item in items
|
|
], dtype=float)
|
|
positions = np.array([item["center_px"] for item in items], dtype=float)
|
|
center = (float(np.dot(weights, positions) / weights.sum())
|
|
if weights.sum() > 0 else float(np.mean(positions)))
|
|
primary = max(items, key=lambda item: item["snr"])
|
|
return {
|
|
"sensor_x_px": center,
|
|
"center_spread_px": float(positions.max() - positions.min()),
|
|
"channels": members,
|
|
"channel_names": "".join(c for c in ("R", "G", "B") if c in members),
|
|
"n_channels": len(members),
|
|
"primary_channel": primary["channel"],
|
|
"height_net_adu": primary["height_net_adu"],
|
|
"max_height_net_adu": float(strongest),
|
|
"snr": primary["snr"],
|
|
"fwhm_px": primary["fwhm_px"],
|
|
"area_net_adu_px": primary["area_net_adu_px"],
|
|
"saturated": any(item["saturated"] for item in items),
|
|
"sample_index": primary["sample_index"],
|
|
"sample_step_px": None,
|
|
}
|
|
|
|
|
|
def merge_coincident_lines(lines: list[dict], tolerance_px: float = 1.5) -> list[dict]:
|
|
"""Join lines that ended up at the same place in complementary channels.
|
|
|
|
Weak lines can be detected a few pixels apart in different CFA channels; if
|
|
the refined centres agree to better than one sample they are one line.
|
|
"""
|
|
|
|
merged: list[dict] = []
|
|
for line in sorted(lines, key=lambda item: item["sensor_x_px"]):
|
|
target = None
|
|
for other in merged:
|
|
if abs(line["sensor_x_px"] - other["sensor_x_px"]) < tolerance_px:
|
|
target = other
|
|
break
|
|
if target is None:
|
|
merged.append({"sensor_x_px": line["sensor_x_px"],
|
|
"channels": dict(line["channels"])})
|
|
continue
|
|
combined = dict(target["channels"])
|
|
for channel, peak in line["channels"].items():
|
|
other = combined.get(channel)
|
|
if other is None or peak["snr"] > other["snr"]:
|
|
combined[channel] = peak
|
|
target["channels"] = combined
|
|
|
|
summaries = [summarise_line(item["channels"]) for item in merged]
|
|
summaries.sort(key=lambda entry: entry["sensor_x_px"])
|
|
for index, summary in enumerate(summaries, 1):
|
|
summary["id"] = f"P{index:03d}"
|
|
return summaries
|
|
|
|
|
|
def group_channels(peaks: dict[str, list[dict]], tolerance_px: float,
|
|
merge_tolerance_px: float = 1.5) -> list[dict]:
|
|
"""Merge per-channel peaks that belong to the same spectral line."""
|
|
|
|
# Cluster on the detected local maxima, not on the fitted centres: a single
|
|
# peak fit inside a blend is pulled towards its neighbour and would wrongly
|
|
# merge two resolved lines.
|
|
flat = [(item["sensor_x_px"], channel, item)
|
|
for channel, items in peaks.items() for item in items]
|
|
flat.sort(key=lambda row: row[0])
|
|
groups: list[list[tuple[float, str, dict]]] = []
|
|
for entry in flat:
|
|
if groups and entry[0] - groups[-1][-1][0] <= tolerance_px:
|
|
groups[-1].append(entry)
|
|
else:
|
|
groups.append([entry])
|
|
|
|
lines = []
|
|
for group in groups:
|
|
members: dict[str, dict] = {}
|
|
for _, channel, item in group:
|
|
other = members.get(channel)
|
|
# One line cannot have two centres in the same CFA channel.
|
|
if other is None or item["snr"] > other["snr"]:
|
|
members[channel] = item
|
|
summary = summarise_line(dict(members))
|
|
summary["id"] = ""
|
|
lines.append(summary)
|
|
return merge_coincident_lines(lines, merge_tolerance_px)
|
|
|
|
|
|
def attach_wavelength(lines: list[dict], calibration: Optional[Calibration]) -> None:
|
|
"""Add wavelength, extrapolation flag and per-channel wavelength data."""
|
|
|
|
for line in lines:
|
|
for item in line["channels"].values():
|
|
if calibration is not None:
|
|
item["wavelength_nm"] = float(calibration(item["center_px"]))
|
|
item["extrapolated"] = bool(
|
|
item["center_px"] < calibration.span[0] or item["center_px"] > calibration.span[1])
|
|
item["dispersion_nm_per_px"] = float(calibration.dispersion(item["center_px"]))
|
|
item["fwhm_nm"] = float(abs(item["fwhm_px"] * item["dispersion_nm_per_px"]))
|
|
else:
|
|
item["wavelength_nm"] = float("nan")
|
|
item["extrapolated"] = False
|
|
item["dispersion_nm_per_px"] = float("nan")
|
|
item["fwhm_nm"] = float("nan")
|
|
if calibration is not None:
|
|
line["wavelength_nm"] = float(calibration(line["sensor_x_px"]))
|
|
line["extrapolated"] = bool(
|
|
line["sensor_x_px"] < calibration.span[0] or line["sensor_x_px"] > calibration.span[1])
|
|
line["dispersion_nm_per_px"] = float(calibration.dispersion(line["sensor_x_px"]))
|
|
line["fwhm_nm"] = float(abs(line["fwhm_px"] * line["dispersion_nm_per_px"]))
|
|
else:
|
|
line["wavelength_nm"] = float("nan")
|
|
line["extrapolated"] = False
|
|
line["dispersion_nm_per_px"] = float("nan")
|
|
line["fwhm_nm"] = float("nan")
|
|
line.update({"match_species": "", "match_nm": float("nan"),
|
|
"match_delta_nm": float("nan"), "match_label": ""})
|
|
line["x_plot"] = line["wavelength_nm"] if calibration is not None else line["sensor_x_px"]
|
|
|
|
def default_output_directory(root: str, stem: str, indices) -> Path:
|
|
"""Folders that name the analysed frame(s), shared by every tool.
|
|
|
|
`<root>/<stem>_f0007` for one frame and `<root>/<stem>_f0005-0007_avg3`
|
|
for an averaged stack, so exports of different frames never overwrite each
|
|
other.
|
|
"""
|
|
|
|
indices = list(indices)
|
|
if not indices:
|
|
raise ValueError("at least one frame index is required")
|
|
if len(indices) > 1:
|
|
return Path(root) / f"{stem}_f{indices[0]:04d}-{indices[-1]:04d}_avg{len(indices)}"
|
|
return Path(root) / f"{stem}_f{indices[0]:04d}"
|