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.stitch_spectra_discrete(wavelength_arrays: list[ndarray], data_arrays: list[ndarray], uncertainty_arrays: list[ndarray] | None = None, weight_arrays: list[ndarray] | None = None, average_routine: Callable[[ndarray, ndarray, ndarray], tuple[float, float]] = None, interpolation_routine: Callable[[ndarray, ndarray], Callable[[ndarray], ndarray]] = None, reference_wavelength: ndarray = None) tuple[ndarray, ndarray, 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 spectra. 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 spectra.

  • data_arrays (list[ndarray]) – The list of the data arrays representing each spectra.

  • uncertainty_arrays (list[ndarray], default = None) – The list of the uncertainty arrays representing the data of each spectra. 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 spectra 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.

  • interpolation_routine (Callable, default = None) – The interpolation routine factory which we use to interpolate each of the spectra to each other wavelength frame. It should have the input form of \(\text{ipr}(x,y) \rightarrow f:x \mapsto y\). If None, we default to a cubic spline, handling gaps.

  • reference_wavelength (ndarray, default = None) – The reference wavelength is where the stitched spectra 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[Callable[[ndarray], ndarray]], data_functions: list[Callable[[ndarray], ndarray]], uncertainty_functions: list[Callable[[ndarray], ndarray]] | None = None, weight_functions: list[Callable[[ndarray], ndarray]] | None = None, average_routine: Callable[[ndarray, ndarray, ndarray], tuple[float, float]] = None, interpolation_routine: Callable[[ndarray, ndarray], Callable[[ndarray], ndarray]] = None, reference_wavelength: ndarray = None) tuple[Callable[[ndarray], ndarray], Callable[[ndarray], ndarray], Callable[[ndarray], 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 spectra. 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.

  • interpolation_routine (Callable, default = None) – The interpolation routine factory which we use to interpolate each of the spectra to each other wavelength frame. It should have the input form of \(\text{ipr}(x,y) \rightarrow f:x \mapsto y\). If None, we default to a cubic spline, handling gaps.

  • 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: ndarray, sample_mode: str = 'hierarchy') 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