Source code for hispecdrp.primitives.trace_fitting.traceprof_moments

"""Trace-profile moments for spectroperfection extraction.

Spatial profile (0th/2nd spatial moment) comes from a fiberflat rate map.
Iso-λ shear and spectral 2nd moment come from LFC spots: each comb peak is a
tilted 2-D PSF whose covariance encodes ``∂row/∂col`` and the line-spread
width along the dispersion axis.
"""

from __future__ import annotations

import logging
from typing import Any

import numpy as np
from scipy.interpolate import PchipInterpolator
from scipy.signal import find_peaks

from ...datamodels import hispec_config
from ...datamodels.tracepos import TracePosModel
from ...datamodels.traceprof import TraceProfModel

logger = logging.getLogger(__name__)

__all__ = [
    "spot_window_moments",
    "measure_lfc_spot_moments_along_trace",
    "measure_fiberflat_spatial_sigma",
    "interpolate_moments_to_pixels",
    "fill_traceprof_spectroperfection_moments",
]


def _n_orders_n_pix(
    spectrograph: str | None,
    *,
    n_pix: int = 4096,
    n_orders: int | None = None,
) -> tuple[int, int]:
    if n_orders is None:
        sp = str(spectrograph or "BSPEC").upper()
        n_orders = len(list(hispec_config.HISPECConfig.get_order_list(sp)))
    return int(n_orders), int(n_pix)


[docs] def spot_window_moments( rate: np.ndarray, row: float, col: float, *, half_win: int = 6, ) -> dict[str, float]: """ Flux-weighted 1st/2nd moments of a 2-D window about ``(row, col)``. Oriented detector: spectral axis is ``row``, cross-dispersion is ``col``. Shear is ``cov(row, col) / var(col)`` = ``∂row/∂col`` of the iso-λ ridge. """ rate = np.asarray(rate, dtype=np.float64) ny, nx = rate.shape r0 = int(np.rint(row)) c0 = int(np.rint(col)) hw = int(half_win) rlo, rhi = max(0, r0 - hw), min(ny, r0 + hw + 1) clo, chi = max(0, c0 - hw), min(nx, c0 + hw + 1) stamp = np.maximum(rate[rlo:rhi, clo:chi], 0.0) total = float(np.sum(stamp)) nan = { "row": float("nan"), "col": float("nan"), "shear": float("nan"), "sigma_spec": float("nan"), "sigma_spat": float("nan"), "mom2_cross": float("nan"), "flux": total, "n_pix": int(stamp.size), } if not np.isfinite(total) or total <= 0.0 or stamp.size < 9: return nan rr = np.arange(rlo, rhi, dtype=np.float64)[:, None] cc = np.arange(clo, chi, dtype=np.float64)[None, :] mu_r = float(np.sum(stamp * rr) / total) mu_c = float(np.sum(stamp * cc) / total) var_r = float(np.sum(stamp * (rr - mu_r) ** 2) / total) var_c = float(np.sum(stamp * (cc - mu_c) ** 2) / total) cov_rc = float(np.sum(stamp * (rr - mu_r) * (cc - mu_c)) / total) if not (np.isfinite(var_c) and var_c > 1.0e-8): shear = float("nan") sig_spec = float(np.sqrt(max(var_r, 0.0))) else: shear = cov_rc / var_c # Spectral width at fixed cross-disp (residual after the tilt). sig_spec = float(np.sqrt(max(var_r - shear * shear * var_c, 0.0))) sig_spat = float(np.sqrt(max(var_c, 0.0))) return { "row": mu_r, "col": mu_c, "shear": float(shear), "sigma_spec": sig_spec, "sigma_spat": sig_spat, "mom2_cross": cov_rc, "flux": total, "n_pix": int(stamp.size), }
[docs] def measure_lfc_spot_moments_along_trace( rate: np.ndarray, trace_y: np.ndarray, *, extraction_aperture: float = 8.0, half_win: int = 6, min_prominence_frac: float = 0.05, min_separation_pix: int = 8, expected_xy: list[tuple[float, float]] | None = None, ) -> list[dict[str, Any]]: """ Measure LFC spot moments along one order's trace. If ``expected_xy`` is given (deposit ``(row, col)`` pairs), those centers are used. Otherwise peaks are found on the aperture-summed spectral profile. """ rate = np.asarray(rate, dtype=np.float64) ty = np.asarray(trace_y, dtype=np.float64) ny, nx = rate.shape spots: list[tuple[float, float]] = [] if expected_xy: spots = [(float(r), float(c)) for r, c in expected_xy] else: collapsed = np.zeros(ny, dtype=np.float64) half = 0.5 * float(extraction_aperture) for x in range(ny): yc = ty[x] if not np.isfinite(yc): continue y0 = max(0, int(np.floor(yc - half))) y1 = min(nx, int(np.ceil(yc + half)) + 1) collapsed[x] = float(np.sum(np.maximum(rate[x, y0:y1], 0.0))) peak = float(np.nanmax(collapsed)) if collapsed.size else 0.0 if not np.isfinite(peak) or peak <= 0.0: return [] idx, _props = find_peaks( collapsed, prominence=float(min_prominence_frac) * peak, distance=max(1, int(min_separation_pix)), ) for x in idx: yc = ty[int(x)] if np.isfinite(yc): spots.append((float(x), float(yc))) out: list[dict[str, Any]] = [] for row, col in spots: mom = spot_window_moments(rate, row, col, half_win=half_win) mom["row_seed"] = float(row) mom["col_seed"] = float(col) out.append(mom) return out
[docs] def measure_fiberflat_spatial_sigma( rate: np.ndarray, trace_y: np.ndarray, *, extraction_aperture: float = 8.0, ) -> np.ndarray: """Per-spectral-row spatial Gaussian σ from a fiberflat rate map.""" rate = np.asarray(rate, dtype=np.float64) ty = np.asarray(trace_y, dtype=np.float64) ny, nx = rate.shape sig = np.full(ny, np.nan, dtype=np.float64) half = 0.5 * float(extraction_aperture) for x in range(ny): yc = ty[x] if not np.isfinite(yc): continue y0 = max(0, int(np.floor(yc - half))) y1 = min(nx, int(np.ceil(yc + half)) + 1) if y1 - y0 < 3: continue yy = np.arange(y0, y1, dtype=np.float64) w = np.maximum(rate[x, y0:y1], 0.0) tot = float(np.sum(w)) if tot <= 0.0: continue mu = float(np.sum(w * yy) / tot) var = float(np.sum(w * (yy - mu) ** 2) / tot) sig[x] = float(np.sqrt(max(var, 0.0))) return sig
[docs] def interpolate_moments_to_pixels( spot_rows: np.ndarray, values: np.ndarray, n_pix: int, ) -> np.ndarray: """PCHIP-interpolate finite spot samples onto ``0 .. n_pix-1``.""" x = np.asarray(spot_rows, dtype=np.float64) y = np.asarray(values, dtype=np.float64) ok = np.isfinite(x) & np.isfinite(y) out = np.full(int(n_pix), np.nan, dtype=np.float64) if int(np.sum(ok)) < 1: return out x, y = x[ok], y[ok] order = np.argsort(x) x, y = x[order], y[order] ux, inv = np.unique(x, return_inverse=True) uy = np.bincount(inv, weights=y) / np.maximum(np.bincount(inv), 1) pix = np.arange(int(n_pix), dtype=np.float64) if ux.size == 1: out[:] = float(uy[0]) return out f = PchipInterpolator(ux, uy, extrapolate=True) out[:] = np.asarray(f(pix), dtype=np.float64) med = float(np.nanmedian(out)) if np.isfinite(med): out[~np.isfinite(out)] = med return out
[docs] def fill_traceprof_spectroperfection_moments( traceprof: TraceProfModel, *, fiberflat_rate: np.ndarray, lfc_rate: np.ndarray, tracepos: TracePosModel, spectrograph: str, fiber: int, orders: list[int] | None = None, extraction_aperture: float = 8.0, half_win: int = 6, expected_xy_by_order: dict[int, list[tuple[float, float]]] | None = None, ) -> TraceProfModel: """ Write shear / σ_spec (LFC) and σ_spat (fiberflat) into ``traceprof``. ``PROF_FIB`` is left unchanged (fiberflat image). Moment HDUs are ``(n_orders, n_pix)`` on the same spectral-row grid as ``TracePos``. """ spectrograph = str(spectrograph).upper() fiber = int(fiber) order_list = list( orders if orders is not None else hispec_config.HISPECConfig.get_order_list(spectrograph) ) ty_all = np.asarray(getattr(tracepos, f"pos_fib{fiber}"), dtype=np.float64) n_orders, n_pix = ty_all.shape ff = np.asarray(fiberflat_rate, dtype=np.float64) lfc = np.asarray(lfc_rate, dtype=np.float64) shear = np.full((n_orders, n_pix), np.nan, dtype=np.float64) sig_spec = np.full((n_orders, n_pix), np.nan, dtype=np.float64) sig_spat = np.full((n_orders, n_pix), np.nan, dtype=np.float64) mom2 = np.full((n_orders, n_pix), np.nan, dtype=np.float64) ost = int(hispec_config.HISPECConfig.echelle_orders[spectrograph]["order_start"]) for od in order_list: j = int(od) - ost if j < 0 or j >= n_orders: continue ty = ty_all[j] expected = None if expected_xy_by_order is not None: expected = expected_xy_by_order.get(int(od)) spots = measure_lfc_spot_moments_along_trace( lfc, ty, extraction_aperture=extraction_aperture, half_win=half_win, expected_xy=expected, ) if spots: rows = np.array([s["row"] for s in spots], dtype=np.float64) shear[j] = interpolate_moments_to_pixels( rows, np.array([s["shear"] for s in spots]), n_pix ) sig_spec[j] = interpolate_moments_to_pixels( rows, np.array([s["sigma_spec"] for s in spots]), n_pix ) mom2[j] = interpolate_moments_to_pixels( rows, np.array([s["mom2_cross"] for s in spots]), n_pix ) logger.info( "LFC moments fiber %s order %s: n_spots=%s median shear=%.4f " "sigma_spec=%.3f", fiber, od, len(spots), float(np.nanmedian(shear[j])), float(np.nanmedian(sig_spec[j])), ) sig_spat[j] = measure_fiberflat_spatial_sigma( ff, ty, extraction_aperture=extraction_aperture ) setattr(traceprof, f"shear_fib{fiber}", shear) setattr(traceprof, f"sigma_spec_fib{fiber}", sig_spec) setattr(traceprof, f"sigma_spat_fib{fiber}", sig_spat) setattr(traceprof, f"mom2_cross_fib{fiber}", mom2) return traceprof