modules.wavelength_solve_and_calibrate

Functions to wavelength calibrate the spectra. Finds lines in arc lamp spectra (ThAr), matches them to a line list based on a preliminary input wavelength solution, and then iteratively fits a polynomial solution.

Created by DMK on 11/11/2023

Last updated by DMK on 11/13/2023

Module Contents

Functions

order_offset_with_wave_sol_guess(prelim_wavelengths, ...)

Function to determine if there is an order offset between the wavelength solution guess and the observed spectrum.

get_flux_mad_from_spectral_chunks(obs_flux[, chunk_size])

Function to get a noise estimate for the arc lamp spectrum by looking at the MAD of chunks of the spectrum.

find_arc_lamp_line_pixel_centers(flux, config)

Function to find lines in an input lamp spectrum using scipy.signal's find_peaks algorithm, with options set in the config file.

fit_wavelength_solution(pixel_centroids, ...)

Function to fit a polynomial wavelength solution, iterating based on sigma rejection with the fit.

wavelength_solution_post_process(wave_sol_coeffs)

interpolate_wavelength_solution(jd_to_interpolate, ...)

Function to interpolate the wavelength solutions measured with the reference sources (e.g. arc lamps) to the times of science observations.

plot_spectra_zoom_windows(obs_wavelength, obs_flux, ...)

Function to plot zoom-ins of the final adopted wavelength calibrated observed spectrum compared to a reference source spectrum. Each page has multiple panels with small cut-out of the spectrum.

plot_wavelength_fit_iteration_spectra(fit_record, ...)

Function to plot the wavelength-calibrated observed spectra for each of the fitting iterations compared to a reference spectrum. This is to highlight the quality of the solution.

plot_wavelength_fit_iteration_residuals(fit_record, ...)

Function to plot the velocity residuals for the iterative wavelength solution fitting. It is a multi-page PDF plot where each page is a separate iteration (working backwards -- the first page is the adopted iteration).

wavelength_solution(file_indices, header_df, config)

Main function to run for fitting the wavelength solution of a set of reference source spectra (e.g. arc lamps).

wavelength_calibrate(obj_file_indices, ...)

Main function to run to wavelength calibrate the observed science spectra.
modules.wavelength_solve_and_calibrate.order_offset_with_wave_sol_guess(prelim_wavelengths, obs_flux, ref_wavelength, ref_flux, order_use_range=[12, 40], offset_test_radius=10)

Function to determine if there is an order offset between the wavelength solution guess and the observed spectrum. It uses a reference arc lamp spectrum to calculate residuals with the observed lamp spectrum while shifting the wavelength solution guess to determine the best fit order offset. It primarily works if the wavelength solution guess is already pretty good, and is used mostly for the wavelength solution guess having more orders than extracted (padding the calibration).

Parameters:

  • prelim_wavelengths (array) – The preliminary wavelength solution guess, with shape (number of orders, number of pixels). There can be a different number of orders than the extracted spectrum.

  • obs_flux (array) – The observed arc lamp flux spectrum, with shape (number of extracted orders, number of pixel).

  • ref_wavelength (array) – The wavelength array for the arc lamp reference spectrum.

  • ref_flux (array) – The flux array for the arc lamp reference spectrum.

  • order_use_range (list of int, optional) – List of minimum and maximum orders to calculate the order offset for. The default is [ 12, 40 ].

  • offset_test_radius (int, optional) – The order offset +/- each order to calculate residuals for. The default is 10.

Returns:

order_offset – The minimum residual order offset between the wavelength solution guess and observed spectrum.

Return type:

int

modules.wavelength_solve_and_calibrate.get_flux_mad_from_spectral_chunks(obs_flux, chunk_size=50)

Function to get a noise estimate for the arc lamp spectrum by looking at the MAD of chunks of the spectrum. Designed to reduce the influence of bleeding over of saturated Ar lines (and oxide bands to a lesser extent)

Parameters:

  • flux (array) – The observed spectrum flux array.

  • chunk_size (int, optional) – The number of pixels in the spectral chunks to calculate the MAD within. The default is 50.

Returns:

median_chunk_mad – The median MAD calculated across all the spectral chunks.

Return type:

float

modules.wavelength_solve_and_calibrate.find_arc_lamp_line_pixel_centers(flux, config)

Function to find lines in an input lamp spectrum using scipy.signal’s find_peaks algorithm, with options set in the config file.

Parameters:

  • flux (array) – The flux spectrum array.

  • config (dict) – The overall config file defined using YAML with all parameters for running the reduction and analysis pipeline.

Returns:

peak_pixels_initial_fit – The array of pixel centroids found as lines in the input flux spectrum.

Return type:

array

modules.wavelength_solve_and_calibrate.fit_wavelength_solution(pixel_centroids, prelim_wavelengths, line_list_wavelengths, config)

Function to fit a polynomial wavelength solution, iterating based on sigma rejection with the fit.

Parameters:

  • pixel_centroids (array) – The array of pixel centroid locations (dependent variable for the wavelength solution).

  • prelim_wavelengths (array) – A preliminary guess for the wavelength solution (shape same as the output spectrum).

  • line_list_wavelengths (array) – The array of line list wavelengths for the arc lamp used to match to.

  • config (dict) – The overall config file defined using YAML with all parameters for running the reduction and analysis pipeline.

Returns:

  • wave_poly_fit (array) – The final adopted polynomial fit coefficients for the wavelength solution (wavelength as a function of pixel). Size is the polynomial degree + 1.

  • line_centroid_record (dict) – A dictionary containing a record of the fitting iterations. Each entry is a list of arrays, with each entry being a subsequent fitting iteration. Contains keys: ‘pixel’: the pixel centroids used in the fit iteration. ‘wavelength’: the corresponding wavelength centroids use in the fit iteration. ‘vel_resid’: the residuals between the input wavelength centroids and polynomial fit values in velocity (km/s) ‘poly_coeffs’: that iteration’s polynomial fit coefficients. The last entry is the same as the output ‘wave_poly_fit’

modules.wavelength_solve_and_calibrate.wavelength_solution_post_process(wave_sol_coeffs)
modules.wavelength_solve_and_calibrate.interpolate_wavelength_solution(jd_to_interpolate, jd_reference, wavelength_solution_reference)

Function to interpolate the wavelength solutions measured with the reference sources (e.g. arc lamps) to the times of science observations.

Parameters:

  • jd_to_interpolate (float) – The JD of the observation to interpolate to.

  • jd_reference (array) – The array of JDs of the reference source observations.

  • wavelength_solution_reference (array) – The wavelength solution for the reference source observations.

Returns:

  • wavelength_solution_interpolate (array) – The interpolated wavelength solution at the input observation time.

  • wavelength_solution_flag (str) – A string denoting what wavelength solution was adopted. Either ‘LINTERP’ to denote that it was linearly interpolated, or ‘CLOSEST” to denote that it could not be interpolated and the closest reference solution was adopted.

modules.wavelength_solve_and_calibrate.plot_spectra_zoom_windows(obs_wavelength, obs_flux, ref_wavelength, ref_flux, lines_used_wavelength, file_name, window_size=10, number_of_subplots=6)

Function to plot zoom-ins of the final adopted wavelength calibrated observed spectrum compared to a reference source spectrum. Each page has multiple panels with small cut-out of the spectrum. This is to highlight the quality of the wavelength solution, and see how it compares to the reference for individual lines across the spectrum.

Parameters:

  • obs_wavelength (array) – The final adopted wavelength solution for the observed spectrum.

  • obs_flux (array) – The observed flux array.

  • ref_wavelength (array) – The reference source wavelength array.

  • ref_flux (array) – The reference source flux array.

  • lines_used_wavelength (array) – The wavelengths of the reference lines from the line list used to calibrate the wavelength solution.

  • file_name (str) – The plot file name to write to.

  • window_size (float, optional) – The wavelength width of each individual spectrum window. The default is 10.

  • number_of_subplots (int, optional) – The number of spectrum window panels on each page. The default is 6.

Return type:

None.

modules.wavelength_solve_and_calibrate.plot_wavelength_fit_iteration_spectra(fit_record, obs_flux, ref_wavelength, ref_flux, file_name)

Function to plot the wavelength-calibrated observed spectra for each of the fitting iterations compared to a reference spectrum. This is to highlight the quality of the solution. It is a multi-page PDF plot where each page is a separate iteration (working backwards – the first page is the adopted iteration).

Parameters:

  • fit_record (dict) – A dictionary containing a record of the lines used and fit coefficients for each of the fitting iterations. This is the output from fit_wavelength_solution.

  • obs_flux (array) – The observed flux array.

  • ref_wavelength (array) – The reference source wavelength array.

  • ref_flux (array) – The reference source flux array.

  • file_name (str) – The plot file name to write to.

Return type:

None.

modules.wavelength_solve_and_calibrate.plot_wavelength_fit_iteration_residuals(fit_record, vel_resid_sigma_reject, file_name)

Function to plot the velocity residuals for the iterative wavelength solution fitting. It is a multi-page PDF plot where each page is a separate iteration (working backwards – the first page is the adopted iteration).

Parameters:

  • fit_record (dict) – A dictionary containing a record of the lines used and fit coefficients for each of the fitting iterations. This is the output from fit_wavelength_solution.

  • file_name (str) – The plot file name to write to.

  • vel_resid_sigma_reject (float) – The sigma-level used for rejection, to plot horizontal lines and highlight points that are rejected in each iteration.

Return type:

None.

modules.wavelength_solve_and_calibrate.wavelength_solution(file_indices, header_df, config)

Main function to run for fitting the wavelength solution of a set of reference source spectra (e.g. arc lamps). Each reference source observation is read in, lines are found and matched to a line list, and the wavelength solution is iteratively fit with a polynomial. The wavelength solution is appended to the spectrum FITS file.

Parameters:

  • file_indices (array) – The file indices (in the header information file) of the reference source observations for wavelength solution fitting.

  • header_df (pandas DataFrame) – The compiled information from the file headers.

  • config (dict) – The overall config file defined using YAML with all parameters for running the reduction and analysis pipeline.

Return type:

None.

modules.wavelength_solve_and_calibrate.wavelength_calibrate(obj_file_indices, ref_file_indices, header_df, config)

Main function to run to wavelength calibrate the observed science spectra. The wavelength solutions fit for each of the reference source observations are interpolated onto the observation times of the other spectra.

Parameters:

  • obj_file_indices (array) – The file indices (in the header information file) of all observations with extracted spectra (including science frames and wavelength reference sources).

  • ref_file_indices (array) – The file indices (in the header information file) of the reference source observations for wavelength solution fitting.

  • header_df (pandas DataFrame) – The compiled information from the file headers.

  • config (dict) – The overall config file defined using YAML with all parameters for running the reduction and analysis pipeline.

Return type:

None.