lezargus.library.stitch module#
Stitch spectra, images, and cubes together.
Stitching spectra, images, and cubes consistently, while keeping all of the pitfalls in check, is not trivial. We group these three stitching functions, and the required spin-off functions, here.
- lezargus.library.stitch.calculate_spectra_scale_factor(base_wavelength: hint.NDArray, base_data: hint.NDArray, input_wavelength: hint.NDArray, input_data: hint.NDArray, base_uncertainty: hint.NDArray | None = None, input_uncertainty: hint.NDArray | None = None, bounds: tuple[float, float] = (-inf, inf)) tuple[float, float] [source]#
Find the scale factor to scale one overlapping spectrum to another.
We determine what scale factor would properly match some input spectrum data to some base data, provided that they have some wavelength overlap. An additional bounds may be set in addition to the wavelength overlap. The method provided is described in [[TODO]].
Parameter#
- base_wavelengthndarray
The wavelength array of the base spectrum data. Must be the same unit as the input wavelength.
- base_datandarray
The spectral data of the base, which the scale factor would scale the input to.
- input_wavelengthndarray
The wavelength array of the input spectrum data. Must be the same unit as the base wavelength.
- input_datandarray
The spectral data of the input, what the scale factor is for.
- base_uncertaintyndarray, default = None
The uncertainty on the base data. If None, we default to no uncertainty.
- input_uncertaintyndarray, default = None
The uncertainty on the input data. If None, we default to no uncertainty.
- boundstuple, default = (-np.inf, +np.inf)
An additional set of wavelength bounds to specify the limits of the overlap which we use to determine the scale factor. Format is (minimum, maximum). Must be in the same units as the base and input wavelengths.
- returns:
scale_factor (float) – The scale factor to scale the input data to match the base data.
scale_uncertainty (float) – The uncertainty in the scale factor. This is usually not relevant.
- lezargus.library.stitch.stitch_spectra_discrete(wavelength_arrays: list[hint.NDArray], data_arrays: list[hint.NDArray], uncertainty_arrays: list[hint.NDArray] | None = None, weight_arrays: list[hint.NDArray] | None = None, average_routine: hint.Callable[[hint.NDArray, hint.NDArray, hint.NDArray], tuple[float, float]] | None = None, interpolate_routine: type[hint.Generic1DInterpolate] | None = None, reference_wavelength: hint.NDArray | None = None) tuple[hint.NDArray, hint.NDArray, hint.NDArray] [source]#
Stitch spectra data arrays together.
We take the discrete point data of spectra (wavelength, data, and uncertainty), along with weights, to stitch together and determine the average spectrum. The scale of the data and uncertainty should be of the same scale, as should the wavelength and reference points.
This function serves as the intended way to stitch spectra, though
stitch.stitch_spectra_functional()
is the work-horse function and more information can be found there. We build interpolators for said function using the input data and attempt to guess for any gaps.- Parameters:
wavelength_arrays (list[ndarray]) – The list of the wavelength arrays representing each spectrum.
data_arrays (list[ndarray]) – The list of the data arrays representing each spectrum.
uncertainty_arrays (list[ndarray], default = None) – The list of the uncertainty arrays representing the data of each spectrum. The scale of the data arrays and uncertainty arrays should be the same. If None, we default to no uncertainty.
weight_arrays (list[ndarray], default = None) – The list of the weight arrays to weight each spectrum for the average routine. If None, we assume uniform weights.
average_routine (Callable, default = None) – The averaging function. It must be able to support the propagation of uncertainties and weights. As such, it should have the form of \(\text{avg}(x, \sigma, w) \rightarrow \bar{x} \pm \sigma\). If None, we use a standard weighted average, ignoring NaNs.
interpolate_routine (Generic1DInterpolate, default = None) – The 1D interpolation routine class used to handle interpolation.
reference_wavelength (ndarray, default = None) – The reference wavelength is where the stitched spectrum wavelength values should be. If None, we attempt to construct it based on the overlap and ordering of the input wavelength arrays. We do not accept NaNs in either cases and remove them.
- Returns:
stitched_wavelength_points (ndarray) – The discrete data points of the average wavelength.
stitched_data_points (ndarray) – The discrete data points of the average data.
stitched_uncertainty_points (ndarray) – The discrete data points of the propagated uncertainties.
- lezargus.library.stitch.stitch_spectra_functional(wavelength_functions: list[hint.Callable[[hint.NDArray], hint.NDArray]], data_functions: list[hint.Callable[[hint.NDArray], hint.NDArray]], uncertainty_functions: list[hint.Callable[[hint.NDArray], hint.NDArray]] | None = None, weight_functions: list[hint.Callable[[hint.NDArray], hint.NDArray]] | None = None, average_routine: hint.Callable[[hint.NDArray, hint.NDArray, hint.NDArray], tuple[float, float]] = None, interpolate_routine: type[hint.Generic1DInterpolate] | None = None, reference_wavelength: hint.NDArray = None) tuple[hint.Callable[[hint.NDArray], hint.NDArray], hint.Callable[[hint.NDArray], hint.NDArray], hint.Callable[[hint.NDArray], hint.NDArray]] [source]#
Stitch spectra functions together.
We take functional forms of the wavelength, data, uncertainty, and weight (in the form of f(wave) = result), and determine the average spectrum. We assume that the all of the functional forms properly handle any bounds, gaps, and interpolative limits. The input lists of functions should be parallel and all of them should be of the same (unit) scale.
For more information, the formal method is described in [[TODO]].
- Parameters:
wavelength_functions (list[Callable]) – The list of the wavelength function. The inputs to these functions should be the wavelength.
data_functions (list[Callable]) – The list of the data function. The inputs to these functions should be the wavelength.
uncertainty_functions (list[Callable], default = None) – The list of the uncertainty function. The inputs to these functions should be the wavelength.
weight_functions (list[Callable], default = None) – The list of the weight function. The weights are passed to the averaging routine to properly weight the average. If None, we assume equal weights.
average_routine (Callable, default = None) – The averaging function. It must be able to support the propagation of uncertainties and weights. As such, it should have the input form of \(\text{avg}(x, \sigma, w) \rightarrow \bar{x} \pm \sigma\). If None, we use a standard weighted average, ignoring NaNs.
interpolate_routine (Generic1DInterpolate, default = None) – The 1D interpolation class used to handle interpolation.
reference_wavelength (ndarray, default = None) –
The reference points which we are going to evaluate the above functions at. The values should be of the same (unit) scale as the input of the above functions. If None, we default to a uniformly distributed set:
\[\left\{ x \in \mathbb{R}, N=10^6 \;|\; 0.30 \leq x \leq 5.50 \right\}\]Otherwise, we use the points provided. We remove any non-finite points and sort.
- Returns:
stitched_wavelength_function (Callable) – The functional form of the average wavelength.
stitched_data_function (Callable) – The functional form of the average data.
stitched_uncertainty_function (Callable) – The functional form of the propagated uncertainties.
- lezargus.library.stitch.stitch_wavelengths_discrete(*wavelengths: hint.NDArray, sample_mode: str = 'hierarchy') hint.NDArray [source]#
Stitch only wavelength arrays together.
This function simply takes input wavelength arrays and outputs a single wavelength array which serves as the combination of all of them, depending on the sampling mode. For more information, see [[TODO]].
- Parameters:
*wavelengths (ndarray) – Positional arguments for the wavelength arrays we are combining. We remove any NaNs.
sample_mode (string, default = "hierarchy") –
The sampling mode of stitching that we will be doing. It must be one of the following modes:
merge: We just combine them as one array, ignoring the sampling of the input wavelength arrays.
hierarchy: We combine each wavelength with those first input taking precedence within their wavelength limits.
- Returns:
stitched_wavelength_points – The combined wavelength.
- Return type:
ndarray