#!/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 fitted centres: if two channels put the line more than # `tolerance_px` apart they are not the same feature, and the user can still # join them by hand in the picker (m). flat = [(item.get("center_px", 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. `/_f0007` for one frame and `/_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}"