modules.trace_echelle
Functions to find and trace the echelle orders, fit each order’s trace with a polynomial, and write the trace to a file for use in the extraction module.
Created by DMK on 10/16/2023
Last updated by DMK on 10/18/2023
Module Contents
Functions
|
Function to recenter a trace given an input spectral slice. |
|
Function to find echelle order centers given a slice of the flat field along the cross dispersion axis. |
|
Function to find the full trace from starting locations found at the edge of the echellogram. |
|
Function to take the full trace from find_full_trace and fit each order's trace with a polynomial. |
|
Function to plot trace on top of an image. It can plot multiple figures in a multi-page PDF with different y ranges for zooming in on the echellogram. |
|
Main wrapper function to find and fit the full echellogram order traces, and output the fitted trace file for extracting spectra. |
- modules.trace_echelle.recenter_order_trace(centers, slice_values, padding)
Function to recenter a trace given an input spectral slice. The cross dispersion “edges” of the order are looked for within a set padding number of pixels from the input order trace center. As of 10/18/2023 the pipeline functions with this slice being the flat field, but in principle it could be any frame (such as a bright star)
- Parameters:
centers (array) – Input array with initial order trace centers (shape: number of orders).
slice_values (array) – The spectral cross-dispersion slice to use for re-centering.
padding (int) – The padding radius (above/below) the order center in the cross dispersion direction to find the order edges.
- Returns:
re_centers – The re-centered array of the order trace (shape: number of orders).
- Return type:
array
- modules.trace_echelle.find_order_centers_along_slice(flat_slice, order_xdisp_width, plot_dir, method='peak_find', binned=False)
Function to find echelle order centers given a slice of the flat field along the cross dispersion axis. The gradient of this flat slice is used to find the top edge of each order (where the flux steeply increases at the order edge). There are two methods available to use: one that uses a single threshold value for the flat slice gradient and one to use a scipy.signal peak finding algorithm. The former was from the original pipeline written with Aaron Rizzuto, although has been adjusted to use an estimate of the gradient’s background noise level rather than a percentile cut. The latter is being added in this new version of the pipeline (as of October 2023).
- Parameters:
flat_slice (array) – An array of flat field flux values along a cross dispersion axis slice (typically one pixel within the overscan region).
order_xdisp_width (int) – A rough estimate of the cross dispersion width of an order. For our default Tull coude spectrograph setup this is roughly 20 pixels (order fully filled by flat field).
plot_dir (str) – The path to where plots for the trace should be saved.
method (str, optional) – One of either ‘peak_find’ or ‘gradient_threshold’. The default is ‘peak_find’
- Returns:
order_centers – Array with the cross disperion pixel location of the order center (shape: number of orders found)
- Return type:
array
- modules.trace_echelle.find_full_trace(flat_field_flux, order_centers, order_disp_start_index, order_xdisp_width, plot_dir, binned=False)
Function to find the full trace from starting locations found at the edge of the echellogram. The orders are traced along the flat field, defined with roughly estimating the center of the flat field order 2D spectrum.
- Parameters:
flat_field_flux (array) – The flat field flux image.
order_centers (array) – Array with the cross disperion pixel location of the order centers from find_order_centers_along_slice (shape: number of orders found).
order_disp_start_index (int) – The ~dispersion direction (x-axis) pixel index at which the starting order centers was found (typically to avoid the overscan region).
order_xdisp_width (int) – A rough estimate of the cross dispersion width of an order in the flat field, defined in the config file.
plot_dir (str) – The path to where plots for the trace should be saved.
- Returns:
full_trace – The full trace found from the starting locations using the flat field (shape: number of orders, number of pixels).
- Return type:
array
- modules.trace_echelle.fit_full_trace(trace, trace_poly_degree, trace_poly_fit_start_index, number_of_orders, flat_field_flux, plot_dir, binned)
Function to take the full trace from find_full_trace and fit each order’s trace with a polynomial. Then, the order trace polynomial coefficients themselves are fit as a function of order, and these hyper-fits are used to find “bad orders” with poorly defined traces. Poorly-fit orders have their trace polynomial fit coefficients replaced with coefficients from the hyper-fits.
- Parameters:
trace (array) – The full trace found in find_full_trace (shape: number of orders, number of pixels)
trace_poly_degree (int) – The polynomial degree to use for fitting each order’s trace as defined in the config file.
trace_poly_fit_start_index (int) – The starting pixel index for inclusion in fitting the trace as defined in the config file. This is not necessarily 0 because the trace could be poorly defined at the order ends.
number_of_orders (int) – The config-defined number of orders to trace. If more orders are found, this function returns more orders than number_of_orders. If fewer orders are found, the trace is filled out using the polynomial fit coefficient hyper-fits.
flat_field_flux (array) – The flat field flux image.
plot_dir (str) – The path to where plots for the trace should be saved.
- Returns:
fit_trace (array) – The values of the trace resulting from the polynomial fits to each order’s input full trace.
bad_orders (array) – A list of orders with bad polynomial trace fits, which are replaced using hyper-fits to the polynomial coefficient of well-defined order traces.
- modules.trace_echelle.plot_trace_on_image(image, trace, y_ranges, file_name, title_str='', trace_fit=None, orders_to_highlight=[])
Function to plot trace on top of an image. It can plot multiple figures in a multi-page PDF with different y ranges for zooming in on the echellogram. It can also take an array with the fit trace to overplot as a line for each order, and highlight certain orders (e.g. poorly fit orders) to be plotted as a different formatted line.
- Parameters:
image (array) – The 2D image to plot behind the trace.
trace (array) – The order trace points to overplot (shape: number of orders, number of pixels).
y_ranges (list) – A list of tuples with the y-ranges to plot as individual figures in the multi-page PDF. The motivation is to allow for zoomed-in looks at the trace.
file_name (str) – The file name and path for the output figure.
title_str (str, optional) – An additional string for the plot title to append to the title with information about the number of orders traced. The default is ‘’.
trace_fit (array, optional) – An array of order trace fit values to overplot as a line for each order if provided. The default is None.
orders_to_highlight (list, optional) – A list of orders to highlight in the fit trace (if provided) with dashed lines rather than solid lines. The default is [].
- Return type:
None.
- modules.trace_echelle.get_trace(flat_field, config)
Main wrapper function to find and fit the full echellogram order traces, and output the fitted trace file for extracting spectra. It does not return the trace location array, but writes it to a FITS file.
- Parameters:
flat_field (HDUList) – The FITS file containing the flat field.
config (dict) – The overall config file defined using YAML with all parameters for running the reduction and analysis pipeline.
- Return type:
None.