Source code for hispecdrp.primitives.line_fitting.fit_lfc_lines_primitive

from ..base_primitive import BasePrimitive
from ... import datamodels

from .fit_lines import fit_lines_gauss
from .find_lines import find_emission_lines
from ..utils.spectral_utils import delta_pix_to_delta_wave

import numpy as np
import scipy.constants
import plotly.graph_objects as go
import matplotlib.pyplot as plt

from logging import getLogger
logger = getLogger(__name__)

__all__ = ['FitLFCLinesPrimitive']


[docs] class FitLFCLinesPrimitive(BasePrimitive): """ NOTE: *Under development* Fit each laser frequency comb (LFC) line with a Gaussian profile. This is useful for calculating the wavelength solution and the the line spread function (LSF). Each LFC line is first identified with `scipy.signal.find_peaks <https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.find_peaks.html>`_ then refined with a centroid. Then each line is fit with a Gaussian profile using `scipy.optimize.least_squares <https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.least_squares.html>`_. The fit parameters are stored in a table in the output data model's attribute ``lfc_fitparams_fib#``. Parameters ---------- input A level 1 or 2 data product. fwhm_bounds : Sequence[float, float] The bounds for the FWHM of the fit. Default is (0.2, 8) pixels. mu_bounds : Sequence[float, float] The bounds for the mean of the fit (in pixels) relative the centroid. Default is (-1, 1) pixels. max_fit_window : float The maximum number of pixels to fit for a mode. Default is 14 pixels. do_orders : Sequence[int] | None Which order(s) to fit. If None, fit all available orders. do_fibers : Sequence[int] | None Which fiber(s) to fit. If None, fit all available fibers. lfc_nu0 : float The central frequency (pump line) of the LFC in GHz. lfc_delta_nu : float The frequency spacing of the LFC modes in GHz. line_source : str The source of the lines to fit. Options: - 'peaks' : Use only the lines found by `find_emission_lines`. - 'wavesol' : Use all lines that fall within the valid wavelength range. min_line_spacing : int Minimum spacing between lines in pixels. Default is 10 pixels. background_filter_width : int | None Number of pixels to use for background estimation. If None, no background subtraction is performed. Returns ------- output : LFCFitParamsModel A data model containing the fit parameters for each LFC line. """ PARAMETERS = { 'fwhm_bounds' : (1.5, 7.0), 'mu_bounds' : (-1.0, 1.0), 'max_fit_window' : 20, 'do_fibers' : None, 'do_orders' : None, 'lfc_nu0' : None, 'lfc_delta_nu' : None, 'background_poly_deg' : 0, 'line_source' : 'peaks', # 'wavesol' (all lines) or 'peaks' (only lines found by find_peaks) 'min_line_spacing' : 10, # Minimum number of pixels between lines 'background_filter_width' : 31, # Pixels 'preview_n_lines_per_order' : 25, # Max lines shown per order in the preview slider. None = show all. } def _perform(self): input_model = datamodels.open(self.dataset) output_model = datamodels.LFCFitParamsModel.from_datamodels( input_model, include_data=True, primitive=self ) # Which traces to process do_fibers, do_orders = self.get_do_traces(input_model, self.do_fibers, self.do_orders) # LFC parameters lfc_nu0 = self.lfc_nu0 if self.lfc_nu0 is not None else input_model.meta.lfc_nu0 lfc_delta_nu = self.lfc_delta_nu if self.lfc_delta_nu is not None else input_model.meta.lfc_delta_nu fit_results = {fiber : [] for fiber in do_fibers} for fiber in do_fibers: # Get extensions for this fiber (blaze-corrected preferred when present) wave = input_model[fiber].wave if input_model.has_extension(f'spec_fib{fiber}'): spec = input_model[fiber].spec spec_err = input_model[fiber].spec_err spec_dq = input_model[fiber].spec_dq else: spec = input_model[fiber].spec_uncal spec_err = input_model[fiber].spec_uncal_err spec_dq = input_model[fiber].spec_uncal_dq for order in do_orders: # Relative order index oi = np.abs(order - input_model.meta.order_start) # Good pixels for this order good = np.where(spec_dq[oi, :] == 0)[0] if len(good) == 0: logger.warning(f"No good pixels found in order {order} for fiber {fiber}. Skipping.") continue _wave = wave[oi, :] _spec = spec[oi, :] _spec_err = spec_err[oi, :] _spec_dq = spec_dq[oi, :] line_spacing_um = (1E-6 * np.mean(_wave[good]))**2 * lfc_delta_nu / scipy.constants.c * 1E6 line_spacing_pix = line_spacing_um / np.max(np.abs(np.gradient(_wave))) adaptive_spacing = float(line_spacing_pix) * 0.8 configured_spacing = float(self.min_line_spacing) # Prefer the tighter of adaptive vs configured spacing so both # LFC densification and explicit test/config floors work; # find_peaks requires distance >= 1. candidates = [ s for s in (adaptive_spacing, configured_spacing) if np.isfinite(s) and s > 0.0 ] min_line_spacing = max(1.0, min(candidates) if candidates else 1.0) # Pixel array along the spectral axis (not spec.size, which is 2-D) pix_arr = np.arange(spec.shape[-1]) # Find the initial lines if self.line_source.lower() == 'peaks': line_centers, _ = find_emission_lines( _spec, _spec_dq, min_line_spacing=min_line_spacing, background_filter_width=self.background_filter_width, centroid_num_pixels=3, drop_first_last=True, refine_with_centroid=True, ) elif self.line_source.lower() == 'wavesol': # Get the wavelength range for this order # and the LFC lines that fall within it wi, wf = np.min(wave[oi, good]), np.max(wave[oi, good]) line_centers_um, _, _ = gen_lfc_modes( lfc_nu0, lfc_delta_nu, wave_min=wi, wave_max=wf ) line_centers = np.interp(line_centers_um, wave[oi, good], pix_arr[good]) line_centers = line_centers[1:-1] # Drop first and last lines to avoid edge effects else: logger.error(f"Invalid line_source '{self.line_source}'. Must be 'peaks' or 'wavesol'.") # Gaussian fit to lines _fit_results = fit_lines_gauss( pix_arr, _spec, _spec_err, _spec_dq, line_centers=line_centers, fwhm_bounds=self.fwhm_bounds, mu_bounds=self.mu_bounds, max_fit_window=self.max_fit_window, ) fit_results[fiber].append(_fit_results) # Store results in the model params_table = output_model[fiber].lfc_fitparams if order in params_table['ORDER']: input_model[fiber].lfc_fitparams.remove_rows( np.where(input_model[fiber].lfc_fitparams['ORDER'] == order)[0] ) n_lines = len(_fit_results) n_pix = spec.shape[-1] for i in range(n_lines): mu_pix = _fit_results[i].mu skip_reason = _unusable_lfc_line_fit_reason( _fit_results[i], fwhm_bounds=self.fwhm_bounds ) if skip_reason is not None: logger.warning( "Skipping failed LFC line fit in order %s fiber %s (%s).", order, fiber, skip_reason, ) continue pix_idx = int(np.round(mu_pix)) if pix_idx < 0 or pix_idx >= n_pix: logger.warning( "Skipping LFC line fit in order %s fiber %s " "(MU_PIX=%s outside 0..%s).", order, fiber, mu_pix, n_pix - 1, ) continue r = { 'ORDER' : order, 'AMPLITUDE' : _fit_results[i].amplitude, 'AMPLITUDE_ERR' : _fit_results[i].amplitude_err, 'MU_PIX' : mu_pix, 'MU_ERR_PIX' : _fit_results[i].mu_err, 'FWHM_PIX' : _fit_results[i].fwhm, 'FWHM_ERR_PIX' : _fit_results[i].fwhm_err, } wave_closest = wave[oi, pix_idx] if not np.isfinite(wave_closest): logger.warning( "Skipping LFC line fit in order %s fiber %s " "(WAVE at MU_PIX=%s is not finite).", order, fiber, mu_pix, ) continue line_wave, _, line_num = _get_closest_lfc_mode( lfc_nu0, lfc_delta_nu, wave_closest ) r['WAVE'] = line_wave r['MODE_NUM'] = line_num # WAVE can decrease along the detector; FWHM / errors are widths. r['FWHM_WAVE'] = abs(delta_pix_to_delta_wave(r['FWHM_PIX'], r['MU_PIX'], wave[oi, :])) r['FWHM_ERR_WAVE'] = abs(delta_pix_to_delta_wave(r['FWHM_ERR_PIX'], r['MU_PIX'], wave[oi, :])) r['MU_ERR_WAVE'] = abs(delta_pix_to_delta_wave(r['MU_ERR_PIX'], r['MU_PIX'], wave[oi, :])) params_table.add_row(r) params_table.sort(['ORDER', 'MU_PIX']) # A single comb mode can be fit twice (e.g. a structured ZEMAX # PSF split into two peaks a few pixels apart, both assigned # the same MODE_NUM). Two knots with one wavelength wreck any # downstream wavesol interpolant, so keep only the strongest # fit per (ORDER, MODE_NUM). output_model[fiber].lfc_fitparams = _drop_duplicate_lfc_modes( output_model[fiber].lfc_fitparams ) return dict(output=output_model, fit_results=fit_results)
[docs] def _create_preview(self): """ Build an interactive preview comparing each fitted LFC line's Gaussian model to the underlying spectral data. Navigation is three-level: a *fiber* dropdown, an *order* dropdown (options depend on the selected fiber), and a *line* slider (options depend on the selected fiber+order). For speed and file size, this keeps exactly two persistent traces in the figure (the data points and the Gaussian fit curve) and swaps their x/y data on each dropdown/slider interaction, rather than pre-building a trace pair per line and toggling visibility across thousands of traces (which scales quadratically with the number of lines and is what made this slow). Additionally, at most ``preview_n_lines_per_order`` lines (evenly sampled) are included per order; set it to None to include every fitted line. """ output_model = self._output['output'] fit_results = self._output['fit_results'] # Recompute the same fiber/order selection used in _perform so that # fit_results[fiber][i] lines up with do_orders[i]. do_fibers, do_orders = self.get_do_traces(output_model, self.do_fibers, self.do_orders) sigma_scale = 2 * np.sqrt(2 * np.log(2)) # FWHM -> sigma half_win = self.max_fit_window / 2.0 n_preview = self.preview_n_lines_per_order # --- Build a nested fiber -> order -> line structure (sampled per order) --- fiber_meta = [] for fiber in do_fibers: if fiber not in fit_results: continue wave = getattr(output_model, f'wave_fib{fiber}') spec = getattr(output_model, f'spec_fib{fiber}') spec_err = getattr(output_model, f'spec_err_fib{fiber}') n_pix = spec.shape[1] pix_arr = np.arange(n_pix) order_entries = [] for oi_idx, order in enumerate(do_orders): oi = int(np.abs(order - output_model.meta.order_start)) order_fits = fit_results[fiber][oi_idx] if oi_idx < len(fit_results[fiber]) else [] # Cheaply filter to fits with a finite centroid before doing any # array slicing / curve reconstruction work. valid_fits = [lf for lf in order_fits if np.isfinite(getattr(lf, 'mu', np.nan))] if not valid_fits: continue n_total = len(valid_fits) if n_preview is not None and n_total > n_preview: sample_idx = np.unique(np.linspace(0, n_total - 1, n_preview).astype(int)) sampled_fits = [valid_fits[i] for i in sample_idx] else: sampled_fits = valid_fits lines = [] for line_fit in sampled_fits: mu = line_fit.mu amp = getattr(line_fit, 'amplitude', np.nan) amp_err = getattr(line_fit, 'amplitude_err', np.nan) mu_err = getattr(line_fit, 'mu_err', np.nan) fwhm = getattr(line_fit, 'fwhm', np.nan) fwhm_err = getattr(line_fit, 'fwhm_err', np.nan) # Data window around the line, padded a bit beyond the fit window for context lo = max(int(np.floor(mu - 1.5 * half_win)), 0) hi = min(int(np.ceil(mu + 1.5 * half_win)), n_pix - 1) if hi <= lo: continue x_data = pix_arr[lo:hi + 1] y_data = spec[oi, lo:hi + 1] yerr_data = spec_err[oi, lo:hi + 1] # Reconstructed Gaussian model curve, densely sampled x_model = np.linspace(x_data[0], x_data[-1], 200) sigma = fwhm / sigma_scale if np.isfinite(fwhm) and fwhm > 0 else np.nan if np.isfinite(sigma) and np.isfinite(amp): y_model = amp * np.exp(-0.5 * ((x_model - mu) / sigma) ** 2) else: y_model = np.full_like(x_model, np.nan) wave_val = np.interp(mu, pix_arr, wave[oi, :]) if wave is not None else np.nan lines.append(dict( mu=mu, mu_err=mu_err, amp=amp, amp_err=amp_err, fwhm=fwhm, fwhm_err=fwhm_err, wave=wave_val, x_data=x_data, y_data=y_data, yerr_data=yerr_data, x_model=x_model, y_model=y_model, )) if lines: order_entries.append(dict(order=order, lines=lines, n_total=n_total)) if order_entries: fiber_meta.append(dict(fiber=fiber, orders=order_entries)) else: logger.warning(f"No valid line fits to preview for fiber {fiber}.") fig = go.Figure() if not fiber_meta: logger.warning("No LFC line fits available to preview.") fig.update_layout(title='No LFC line fits available to preview.') self._output['preview'] = dict(html=None, png=None, fig=fig) return def _line_title(fiber, order, line, line_idx, n_shown, n_total): wave_str = f", λ={line['wave']:.5f} µm" if np.isfinite(line['wave']) else "" sample_note = f" (sampled {n_shown} of {n_total} fit)" if n_total > n_shown else "" return ( f"LFC Line Fit — Fiber {fiber}, Order {order}, " f"Line {line_idx + 1}/{n_shown}{sample_note}{wave_str}<br>" f"µ = {line['mu']:.3f} ± {line['mu_err']:.3f} px | " f"FWHM = {line['fwhm']:.3f} ± {line['fwhm_err']:.3f} px | " f"Amp = {line['amp']:.4g} ± {line['amp_err']:.4g}" ) def _line_data_update(line): # Only 2 traces ever exist (data, fit), so these arrays map 1:1 to them. return { 'x': [line['x_data'], line['x_model']], 'y': [line['y_data'], line['y_model']], 'error_y.array': [line['yerr_data'], line['yerr_data']], } # --- The only two traces in the figure; their data gets swapped on interaction --- first_line = fiber_meta[0]['orders'][0]['lines'][0] fig.add_trace(go.Scatter( x = first_line['x_data'], y = first_line['y_data'], error_y = dict(type='data', array=first_line['yerr_data'], visible=True), mode = 'markers', name = 'Data', marker = dict(color='steelblue', size=7), )) fig.add_trace(go.Scatter( x = first_line['x_model'], y = first_line['y_model'], mode = 'lines', name = 'Gaussian fit', line = dict(color='crimson', width=2), )) # --- Line slider steps (scrolls through the (sampled) lines within one fiber+order) --- def build_line_slider_steps(f_idx, o_idx): meta = fiber_meta[f_idx] order_entry = meta['orders'][o_idx] n_shown = len(order_entry['lines']) steps = [] for l_idx, line in enumerate(order_entry['lines']): steps.append(dict( method = 'update', label = str(l_idx + 1), args = [ _line_data_update(line), {'title': _line_title(meta['fiber'], order_entry['order'], line, l_idx, n_shown, order_entry['n_total'])}, ], )) return steps # --- Order dropdown buttons (options depend on the selected fiber) --- def build_order_dropdown_buttons(f_idx): meta = fiber_meta[f_idx] buttons = [] for o_idx, order_entry in enumerate(meta['orders']): n_shown = len(order_entry['lines']) label = f"Order {order_entry['order']}" if order_entry['n_total'] > n_shown: label += f" ({n_shown}/{order_entry['n_total']})" buttons.append(dict( label = label, method = 'update', args = [ _line_data_update(order_entry['lines'][0]), { 'title': _line_title(meta['fiber'], order_entry['order'], order_entry['lines'][0], 0, n_shown, order_entry['n_total']), # Update only the line slider (leave both dropdowns untouched) 'sliders[0].steps': build_line_slider_steps(f_idx, o_idx), 'sliders[0].active': 0, }, ], )) return buttons # --- Fiber dropdown buttons (rewrite the order dropdown + line slider) --- fiber_buttons = [] for f_idx, meta in enumerate(fiber_meta): first_order_entry = meta['orders'][0] n_shown = len(first_order_entry['lines']) fiber_buttons.append(dict( label = f'Fiber {meta["fiber"]}', method = 'update', args = [ _line_data_update(first_order_entry['lines'][0]), { 'title': _line_title(meta['fiber'], first_order_entry['order'], first_order_entry['lines'][0], 0, n_shown, first_order_entry['n_total']), # Rebuild the order dropdown's own buttons for this fiber... 'updatemenus[1].buttons': build_order_dropdown_buttons(f_idx), 'updatemenus[1].active': 0, # ...and reset the line slider to this fiber's first order 'sliders[0].steps': build_line_slider_steps(f_idx, 0), 'sliders[0].active': 0, }, ], )) fig.update_layout( title = _line_title( fiber_meta[0]['fiber'], fiber_meta[0]['orders'][0]['order'], fiber_meta[0]['orders'][0]['lines'][0], 0, len(fiber_meta[0]['orders'][0]['lines']), fiber_meta[0]['orders'][0]['n_total'], ), updatemenus = [ dict( # [0] fiber dropdown buttons = fiber_buttons, direction = 'down', showactive = True, x = 1.0, xanchor = 'right', y = 1.15, yanchor = 'top', bgcolor = '#f0f0f0', bordercolor = '#cccccc', ), dict( # [1] order dropdown — options for the initial fiber buttons = build_order_dropdown_buttons(0), direction = 'down', showactive = True, x = 1.0, xanchor = 'right', y = 1.0, yanchor = 'top', bgcolor = '#f0f0f0', bordercolor = '#cccccc', ), ], sliders = [dict( active = 0, currentvalue = dict(prefix='Line: ', font=dict(size=14)), pad = dict(t=50), steps = build_line_slider_steps(0, 0), )], xaxis = dict(title='Pixel', showgrid=True, gridcolor='rgba(200,200,200,0.3)'), yaxis = dict(title='Flux (e-/s)', showgrid=True, gridcolor='rgba(200,200,200,0.3)'), plot_bgcolor = '#ffffff', paper_bgcolor = '#ffffff', font = dict(color='#000000'), legend = dict(bgcolor='#ffffff'), height = 550, margin = dict(t=140), ) base_path = output_model._generate_output_path(output_dir=self.output_dir, suffix=self.suffix) output_path_html = base_path.replace('.fits', '_preview.html') output_path_png = base_path.replace('.fits', '_preview.png') if self.save_preview: fig.write_html(output_path_html, include_plotlyjs='cdn') fig.write_image(output_path_png, scale=2) if self.show_preview: fig.show() self._output['preview'] = { 'html': output_path_html, 'png': output_path_png, 'fig': fig, }
def _drop_duplicate_lfc_modes(params_table): """Keep the highest-AMPLITUDE row per (ORDER, MODE_NUM) pair.""" if len(params_table) == 0: return params_table order_col = np.asarray(params_table['ORDER']) mode_col = np.asarray(params_table['MODE_NUM']) amp_col = np.asarray(params_table['AMPLITUDE'], dtype=float) keys = order_col.astype(np.int64) * 1_000_000_000 + mode_col.astype(np.int64) by_amp = np.argsort(-amp_col, kind='stable') seen: set[int] = set() keep: list[int] = [] for idx in by_amp: key = int(keys[idx]) if key not in seen: seen.add(key) keep.append(int(idx)) out = params_table[np.sort(keep)] out.sort(['ORDER', 'MU_PIX']) return out def _unusable_lfc_line_fit_reason(fit, *, fwhm_bounds) -> str | None: """Return a skip reason for a collapsed / bound-hitting Gaussian, else None.""" mu = fit.mu amp = fit.amplitude fwhm = fit.fwhm fwhm_err = fit.fwhm_err if not np.isfinite(mu): return "MU_PIX is not finite" if (not np.isfinite(amp)) or amp <= 0.0: return f"AMPLITUDE={amp} is not a positive line" if not np.isfinite(fwhm): return "FWHM_PIX is not finite" if fwhm_bounds is not None: lo, hi = float(fwhm_bounds[0]), float(fwhm_bounds[1]) span = hi - lo tol = 1.0e-3 * span if span > 0.0 else 1.0e-3 if fwhm <= lo + tol or fwhm >= hi - tol: return f"FWHM_PIX={fwhm} is at the fit bound {fwhm_bounds}" if (not np.isfinite(fwhm_err)) or fwhm_err > 1.0: return f"FWHM_ERR_PIX={fwhm_err} is unusable" return None def gen_lfc_modes( nu0 : float, delta_nu : float, wave_min : float, wave_max : float ): """ Generate LFC modes based on central frequency, frequency spacing, and wavelength bounds. Parameters ---------- nu0 : float The central frequency (pump line) of the LFC in GHz. delta_nu : float The frequency spacing of the LFC modes in GHz. wave_min : float The minimum wavelength of the LFC modes in microns. wave_max : float The maximum wavelength of the LFC modes in microns. Returns ------- waves : np.ndarray The wavelengths of the LFC modes in microns. nus : np.ndarray The frequencies of the LFC modes in GHz. integers : np.ndarray The integer indices of the LFC modes. """ nu_end = (scipy.constants.c / wave_min) * 1E6 nu_start = (scipy.constants.c / wave_max) * 1E6 n1 = int(np.ceil((nu_start - nu0) / delta_nu)) n2 = int(np.floor((nu_end - nu0) / delta_nu)) integers = np.arange(min(n1, n2), max(n1, n2) + 1).astype(int) waves, nus = _gen_lfc_modes(nu0, delta_nu, integers) waves = waves[::-1] nus = nus[::-1] integers = integers[::-1] return waves, nus, integers def _gen_lfc_modes( nu0 : float, delta_nu : float, integers : np.ndarray ) -> tuple[np.ndarray, np.ndarray]: """ Generate LFC modes based on central frequency, frequency spacing, and integer indices. Parameters ---------- nu0 : float The central frequency (pump line) of the LFC in GHz. delta_nu : float The frequency spacing of the LFC modes in GHz. integers : np.ndarray An array of integer indices representing the mode numbers. Returns ------- waves : np.ndarray The wavelengths of the LFC modes in microns. nus : np.ndarray The frequencies of the LFC modes in GHz. """ nus = integers * delta_nu + nu0 waves = scipy.constants.c / nus * 1E6 return waves, nus def _get_closest_lfc_mode( nu0 : float, delta_nu : float, wave : float ) -> tuple[np.ndarray, np.ndarray, int]: """ Get the closest LFC mode to a given wavelength value. Parameters ---------- nu0 : float The central frequency (pump line) of the LFC in Hz. delta_nu : float The frequency spacing of the LFC modes in Hz. wave : float The wavelength value in microns. Returns ------- np.ndarray The closest wavelength of the LFC mode in microns. np.ndarray The corresponding frequency of the LFC mode in GHz. int The integer index of the closest LFC mode. """ nu = scipy.constants.c / wave * 1E6 n = int(np.rint((nu - nu0) / delta_nu)) nu_mode = nu0 + n * delta_nu wave_mode = scipy.constants.c / nu_mode * 1E6 return wave_mode, nu_mode, n