Common Pipeline Library Reference Manual  6.3.1
Functions
Wavelength calibration

Functions

cpl_error_code cpl_wlcalib_fill_line_spectrum (cpl_vector *self, void *model, const cpl_polynomial *disp)
 Generate a 1D spectrum from a model and a dispersion relation.
 
cpl_error_code cpl_wlcalib_fill_line_spectrum_fast (cpl_vector *self, void *model, const cpl_polynomial *disp)
 Generate a 1D spectrum from a model and a dispersion relation.
 
cpl_error_code cpl_wlcalib_fill_logline_spectrum (cpl_vector *self, void *model, const cpl_polynomial *disp)
 Generate a 1D spectrum from a model and a dispersion relation.
 
cpl_error_code cpl_wlcalib_fill_logline_spectrum_fast (cpl_vector *self, void *model, const cpl_polynomial *disp)
 Generate a 1D spectrum from a model and a dispersion relation.
 
cpl_error_code cpl_wlcalib_find_best_1d (cpl_polynomial *self, const cpl_polynomial *guess, const cpl_vector *spectrum, void *model, cpl_error_code(*filler)(cpl_vector *, void *, const cpl_polynomial *), const cpl_vector *wl_search, cpl_size nsamples, cpl_size hsize, double *xcmax, cpl_vector *xcorrs)
 Find the best 1D dispersion polynomial in a given search space.
 
void cpl_wlcalib_slitmodel_delete (cpl_wlcalib_slitmodel *self)
 Free memory associated with a cpl_wlcalib_slitmodel object.
 
cpl_wlcalib_slitmodel * cpl_wlcalib_slitmodel_new (void)
 Create a new line model to be initialized.
 
cpl_error_code cpl_wlcalib_slitmodel_set_catalog (cpl_wlcalib_slitmodel *self, cpl_bivector *catalog)
 Set the catalog of lines to be used by the spectrum filler.
 
cpl_error_code cpl_wlcalib_slitmodel_set_threshold (cpl_wlcalib_slitmodel *self, double value)
 The (positive) threshold for truncating the transfer function.
 
cpl_error_code cpl_wlcalib_slitmodel_set_wfwhm (cpl_wlcalib_slitmodel *self, double value)
 Set the FWHM of the transfer function to be used by the spectrum filler.
 
cpl_error_code cpl_wlcalib_slitmodel_set_wslit (cpl_wlcalib_slitmodel *self, double value)
 Set the slit width to be used by the spectrum filler.
 

Detailed Description

This module contains functions to perform 1D-wavelength calibration, typically of long-slit spectroscopy data.

Synopsis:
#include "cpl_wlcalib.h"

Function Documentation

cpl_error_code cpl_wlcalib_fill_line_spectrum ( cpl_vector *  self,
void *  model,
const cpl_polynomial *  disp 
)

Generate a 1D spectrum from a model and a dispersion relation.

Parameters
selfVector to fill with spectrum
modelPointer to cpl_wlcalib_slitmodel object
disp1D-Dispersion relation, at least of degree 1
Returns
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
Note
The model is passed as a void pointer so the function can be used with cpl_wlcalib_find_best_1d().
See Also
cpl_wlcalib_find_best_1d()

The fill a vector with a spectrum, one must first initialize the parameters of the model (error checks omitted for brevity):

cpl_vector * spectrum = cpl_vector_new(nresolution);
cpl_wlcalib_slitmodel * model = cpl_wlcalib_slitmodel_new();
cpl_bivector * lines = my_load_lines_catalog(filename);
cpl_polynomial * dispersion = my_1d_dispersion();

With that the spectrum can be filled:

cpl_wlcalib_fill_line_spectrum(spectrum, model, dispersion);

Clean-up when no more spectra are needed (lines are deleted with the model):

Each line profile is given by the convolution of the Dirac delta function with a Gaussian with $\sigma = w_{FWHM}/(2\sqrt(2\log(2))),$ and a top-hat with the slit width as width. This continuous line profile is then integrated over each pixel, wherever the intensity is above the threshold set by the given model. For a given line the value on a given pixel requires the evaluation of two calls to erf().

Possible _cpl_error_code_ set by this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_INVALID_TYPE If the input polynomial is not 1D
  • CPL_ERROR_ILLEGAL_INPUT If the input polynomial is non-increasing over the given input (pixel) range, or if a model parameter is non-physical (e.g. non-positive slit width).
  • CPL_ERROR_DATA_NOT_FOUND If no catalog lines are available in the range of the dispersion relation
  • CPL_ERROR_INCOMPATIBLE_INPUT If the wavelengths of two catalog lines are found to be in non-increasing order.
cpl_error_code cpl_wlcalib_fill_line_spectrum_fast ( cpl_vector *  self,
void *  model,
const cpl_polynomial *  disp 
)

Generate a 1D spectrum from a model and a dispersion relation.

Parameters
selfVector to fill with spectrum
modelPointer to cpl_wlcalib_slitmodel object
disp1D-Dispersion relation, at least of degree 1
Returns
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
Note
The generated spectrum will use an approximate line profile for speed
See Also
cpl_wlcalib_fill_line_spectrum()

The approximation preserves the position of the maximum, the symmetry and the flux of the line profile.

The use of a given line in a spectrum requires the evaluation of four calls to erf().

The fast spectrum generation can be useful when the model spectrum includes many catalog lines.

cpl_error_code cpl_wlcalib_fill_logline_spectrum ( cpl_vector *  self,
void *  model,
const cpl_polynomial *  disp 
)

Generate a 1D spectrum from a model and a dispersion relation.

Parameters
selfVector to fill with spectrum
modelPointer to cpl_wlcalib_slitmodel object
disp1D-Dispersion relation, at least of degree 1
Returns
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
Note
The spectrum is generated from 1 + the logarithm of the line intensities
See Also
cpl_wlcalib_fill_line_spectrum()
cpl_error_code cpl_wlcalib_fill_logline_spectrum_fast ( cpl_vector *  self,
void *  model,
const cpl_polynomial *  disp 
)

Generate a 1D spectrum from a model and a dispersion relation.

Parameters
selfVector to fill with spectrum
modelPointer to cpl_wlcalib_slitmodel object
disp1D-Dispersion relation, at least of degree 1
Returns
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
Note
The spectrum is generated from 1 + the logarithm of the line intensities and an approximate line profile for speed
See Also
cpl_wlcalib_fill_line_spectrum_fast()
cpl_error_code cpl_wlcalib_find_best_1d ( cpl_polynomial *  self,
const cpl_polynomial *  guess,
const cpl_vector *  spectrum,
void *  model,
cpl_error_code(*)(cpl_vector *, void *, const cpl_polynomial *)  filler,
const cpl_vector *  wl_search,
cpl_size  nsamples,
cpl_size  hsize,
double *  xcmax,
cpl_vector *  xcorrs 
)

Find the best 1D dispersion polynomial in a given search space.

Parameters
selfPre-created 1D-polynomial for the result
guess1D-polynomial with the guess, may equal self
spectrumThe vector with the observed 1D-spectrum
modelThe spectrum model
fillerThe function used to make the spectrum
wl_searchSearch range around the anchor points, same unit as guess
nsamplesNumber of samples around the anchor points
hsizeMaximum (pixel) displacement of the polynomial guess
xcmaxOn success, the maximum cross-correlation
xcorrsThe vector to fill with the correlation values or NULL
Returns
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
See Also
cpl_wlcalib_fill_line_spectrum() for the model and filler.

Find the polynomial that maximizes the cross-correlation between an observed 1D-spectrum and a model spectrum based on the polynomial dispersion relation.

The wavelength search range is in the same units as the Y-values of the dispersion relation.

For each candidate polynomial P(x), the polynomial P(x+u), -hsize <= u <= hsize is also evaluated. The half-size hsize may be zero. When it is non-zero, an additional 2 * hsize cross-correlations are performed for each candidate polynomial, one for each possible shift. The maximizing polynomial among those shifted polynomials is kept. A well-chosen half-size can allow for the use of fewer number of samples around the anchor points, leading to a reduction of polynomials to be evaluated.

The complexity in terms of model spectra creation is O(N^D) and in terms of cross-correlations O(hsize * N^D), where N is nsamples and D is the length of wl_error.

xcorrs must be NULL or have a size of (at least) N^D*(1 + 2 * hsize).

Possible _cpl_error_code_ set by this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_INVALID_TYPE If an input polynomial is not 1D
  • CPL_ERROR_ILLEGAL_INPUT If nfree is less than 2, or nsamples is less than 1, hsize negative or if wl_search contains a zero search bound, or if xcorrs is non-NULL and too short.
  • CPL_ERROR_DATA_NOT_FOUND If no model spectra can be created using the supplied model and filler
void cpl_wlcalib_slitmodel_delete ( cpl_wlcalib_slitmodel *  self)

Free memory associated with a cpl_wlcalib_slitmodel object.

Parameters
selfThe cpl_wlcalib_slitmodel object or NULL
Returns
Nothing
See Also
cpl_wlcalib_slitmodel_new()
Note
If self is NULL nothing is done and no error is set.
cpl_wlcalib_slitmodel* cpl_wlcalib_slitmodel_new ( void  )

Create a new line model to be initialized.

Returns
1 newly allocated cpl_wlcalib_slitmodel
Note
All elements are initialized to either zero or NULL.
See Also
cpl_wlcalib_slitmodel_delete() for object deallocation.

The model comprises these elements: Slit Width FWHM of transfer function Truncation threshold of the transfer function Catalog of lines (typically arc or sky)

The units of the X-values of the lines is a length, it is assumed to be the same as that of the Y-values of the dispersion relation (e.g. meter), the units of slit width and the FWHM are assumed to be the same as the X-values of the dispersion relation (e.g. pixel), while the units of the produced spectrum will be that of the Y-values of the lines.

cpl_error_code cpl_wlcalib_slitmodel_set_catalog ( cpl_wlcalib_slitmodel *  self,
cpl_bivector *  catalog 
)

Set the catalog of lines to be used by the spectrum filler.

Parameters
selfThe cpl_wlcalib_slitmodel object
catalogThe catalog of lines (e.g. arc lines)
Returns
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
See Also
cpl_wlcalib_slitmodel_new()
Note
The values in the X-vector must be increasing. Any previously set catalog is deallocated

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
cpl_error_code cpl_wlcalib_slitmodel_set_threshold ( cpl_wlcalib_slitmodel *  self,
double  value 
)

The (positive) threshold for truncating the transfer function.

Parameters
selfThe cpl_wlcalib_slitmodel object
valueThe (non-negative) truncation threshold, 5 is a good value.
Returns
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
See Also
cpl_wlcalib_slitmodel_new()
Note
The threshold should be high enough to ensure a good line profile, but not too high to make the spectrum generation too costly.

The line profile is truncated at this distance [pixel] from its maximum: $x_{max} = w/2 + k * \sigma,$ where $w$ is the slit width and $\sigma = w_{FWHM}/(2\sqrt(2\log(2))),$ where $w_{FWHM}$ is the Full Width at Half Maximum (FWHM) of the transfer function and $k$ is the user supplied value.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT the value is negative
cpl_error_code cpl_wlcalib_slitmodel_set_wfwhm ( cpl_wlcalib_slitmodel *  self,
double  value 
)

Set the FWHM of the transfer function to be used by the spectrum filler.

Parameters
selfThe cpl_wlcalib_slitmodel object
valueThe (positive) FWHM
Returns
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
See Also
cpl_wlcalib_slitmodel_new()

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT the value is non-positive
cpl_error_code cpl_wlcalib_slitmodel_set_wslit ( cpl_wlcalib_slitmodel *  self,
double  value 
)

Set the slit width to be used by the spectrum filler.

Parameters
selfThe cpl_wlcalib_slitmodel object
valueThe (positive) width of the slit
Returns
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
See Also
cpl_wlcalib_slitmodel_new()

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT the value is non-positive