TiltCorrection#

class specreduce.tilt_correction.TiltCorrection(arc_frames: NDData | Sequence[NDData], trace: Trace | None = None, cdisp_ref_pixel: float | None = None, disp_ref_pixel: float | None = None, n_cdisp_samples: int = 10, cdisp_sample_lims: tuple[float, float] | None = None, cdisp_samples: Sequence[float] | None = None, disp_axis: int = 1, mask_treatment: Literal['apply', 'ignore', 'propagate', 'zero_fill', 'nan_fill', 'apply_mask_only', 'apply_nan_only'] = 'apply')[source]#

Bases: object

A class for 2D spectral tilt correction.

This class provides tools for correcting spectral tilt (curvature) in 2D spectroscopic data using arc lamp frames. It identifies arc lines across the cross-dispersion axis and fits a 2D polynomial transformation from a tilt-corrected (rectified) coordinate space to detector space. The resulting TiltSolution can then be used to resample science frames onto a rectified grid.

Parameters:

arc_frames

A sequence of arc frames as NDData instances.

trace

A trace object representing the spectrum trace. If provided, it will be used to determine the reference positions along the dispersion and cross-dispersion axes.

cdisp_ref_pixel

A reference pixel position along the cross-dispersion axis. Should be close to the spectrum trace’s average cross-dispersion position for the best results.

disp_ref_pixel

A reference pixel position along the dispersion axis. Should be close to the center of the frame along the dispersion axis for best results.

n_cdisp_samples

Number of cross-dispersion (CD) samples to use.

cdisp_sample_lims

Tuple specifying the limits for calculating cross-dispersion sampling.

cdisp_samples

A list of cross-dispersion locations to use. Overrides n_cdisp_samples if provided.

disp_axis

The index of the image’s dispersion axis.

mask_treatment

Specifies how to handle masked or non-finite values in the input image. The accepted values are:

apply: The image remains unchanged, and any existing mask is combined with a mask derived from non-finite values.
ignore: The image remains unchanged, and any existing mask is dropped.
propagate: The image remains unchanged, and any masked or non-finite pixel causes the mask to extend across the entire cross-dispersion axis.
zero_fill: Pixels that are either masked or non-finite are replaced with 0.0, and the mask is dropped.
nan_fill: Pixels that are either masked or non-finite are replaced with nan, and the mask is dropped.
apply_mask_only: The image and mask are left unmodified.
apply_nan_only: The image is left unmodified, the old mask is dropped, and a new mask is created based on non-finite values.

Methods Summary

`find_arc_lines`(fwhm[, noise_factor])	Find arc lines from the provided arc frames for all cross-dispersion samples.
`fit`([degree, method, max_distance])	Fit a 2D polynomial transformation from tilt-corrected space to detector space.
`match_lines`([max_distance, concatenate])	Match the reference arc line locations with the detector-space targets.
`plot_fit_quality`([figsize, ...])	Plot fit quality diagnostics showing residuals of the tilt correction.
`plot_wavelength_contours`([n_disp, n_cdisp, ...])	Plot wavelength contour lines in detector space.
`refine_fit`([degree, match_distance_bound])	Refine the tilt-corrected space -> detector space transformation model parameters.

Methods Documentation

find_arc_lines(fwhm: float, noise_factor: float = 5.0) → None[source]#

Find arc lines from the provided arc frames for all cross-dispersion samples.

This method locates spectral arc lines from the provided arc frames, calculates their centroids, and organizes them into reference lists and sample arrays for further analysis.

Parameters:

fwhm: Full width at half maximum of the spectral line to be detected, used by the line-finding algorithm.
noise_factor: A multiplier for noise thresholding in the line-finding process.

fit(degree: int = 3, method: str = 'Powell', max_distance: float = 10) → TiltSolution[source]#

Fit a 2D polynomial transformation from tilt-corrected space to detector space.

The transformation is calculated by minimizing the sum of distances between transformed samples and their corresponding detector-space targets. The minimization is performed in two stages: an initial minimization of a kd-tree based sum of line-line distances using scipy.optimize.minimize and a refinement using least-squares optimization of matched lines.

Parameters:

degree: The degree of the final 2D polynomial model.
method: The optimization method used during the initial fitting stage.
max_distance: The maximum allowable distance to constrain the minimization.

match_lines(max_distance: float = 5, concatenate: bool = True) → tuple[ndarray, ndarray, ndarray] | tuple[list[ndarray], list[ndarray], list[ndarray]][source]#

Match the reference arc line locations with the detector-space targets.

Parameters:

max_distance: Specifies the maximum allowed distance for matching lines. Matches beyond this distance will be ignored.
concatenate: Specifies whether to concatenate the matched lines.

Returns:

tuple of numpy.ndarray: A tuple containing three concatenated numpy arrays representing: - x-coordinates of matched rectified-space lines. - y-coordinates of matched rectified-space lines. - x-coordinates of matched detector-space lines.

plot_fit_quality(figsize=None, max_match_distance: float = 5, rlim: tuple[float, float] | None = None)[source]#

Plot fit quality diagnostics showing residuals of the tilt correction.

Creates a three-panel figure with a scatter plot of matched line positions and marginal residual plots along the dispersion and cross-dispersion axes.

Parameters:

figsize: Tuple specifying the size of the figure. If None, the default Matplotlib figure size is used.
max_match_distance: Maximum distance for matching lines, passed to match_lines.
rlim: Residual axis limits as a tuple (min, max). Applied to both marginal residual plots. If None, limits are set automatically.

Returns:

matplotlib.figure.Figure: The Matplotlib figure containing the diagnostic plots.

plot_wavelength_contours(n_disp: int = 50, n_cdisp: int = 100, disp_values: Sequence[float] | None = None, ax: Axes | None = None, figsize: tuple[float, float] | None = None, line_args: dict | None = None)[source]#

Plot wavelength contour lines in detector space.

Parameters:

n_disp: The number of dispersion-axis lines.
n_cdisp: The number of cross-dispersion axis points for each disp-axis line.
disp_values: A sequence specifying the dispersion-axis coordinates explicitly. If not provided, it will be automatically calculated based on the arc frame dimensions.
ax: The Matplotlib Axes on which to plot. If None, a new figure and Axes are created.
figsize: Tuple specifying the size of the figure to create, applicable only if ax is None.
line_args: A dictionary of line properties (e.g., color, linewidth, linestyle). These properties modify the default styling provided for grid lines. If None, default styles are used. Default is None.

Returns:

figurematplotlib.figure.Figure: The Matplotlib figure containing the plot. If an Axes instance is passed to ax, the associated figure is returned.

refine_fit(degree: int = 4, match_distance_bound: float = 5.0) → None[source]#

Refine the tilt-corrected space -> detector space transformation model parameters.

Refines the polynomial fit model parameters for matching features with a specified degree and match distance bound. The refinement includes matching lines, updating a polynomial model, and optimizing the parameters using a least squares fitter The derivative is recalculated after the optimization.

Parameters:

degree: Degree of the polynomial used in the Polynomial2D model.
match_distance_bound: Maximum acceptable distance between features to be considered a match.