MUSE Pipeline Reference Manual  2.1.1
Data Structures | Enumerations | Functions | Variables
Wavelength calibration

Data Structures

struct  muse_wave_params
 Structure containing wavelength calibration parameters. More...
 

Enumerations

Functions

muse_wave_paramsmuse_wave_params_new (cpl_propertylist *aHeader)
 Allocate a wavelength parameters structure and fill it with defaults. More...
 
void muse_wave_params_delete (muse_wave_params *aParams)
 Deallocate memory associated to a wavelength parameters structure. More...
 
cpl_table * muse_wave_calib (muse_image *aImage, cpl_table *aTrace, cpl_table *aLinelist, muse_wave_params *aParams)
 Find wavelength calibration solution on an arc frame. More...
 
cpl_table * muse_wave_calib_lampwise (muse_imagelist *aImages, cpl_table *aTrace, cpl_table *aLinelist, muse_wave_params *aParams)
 Find wavelength calibration solution using a list of arc images with different lamps. More...
 
cpl_boolean muse_wave_lines_check (muse_table *aTable)
 Check that a LINE_CATALOG has the expected format. More...
 
cpl_vector * muse_wave_lines_get (cpl_table *aTable, int aGoodnessLimit, double aFluxLimit)
 Load usable wavelengths from a linelist table into a vector. More...
 
cpl_vector * muse_wave_lines_get_for_lamp (cpl_table *aTable, const char *aLamp, int aGoodnessLimit, double aFluxLimit)
 Load wavelengths for a given lamp from a linelist table into a vector. More...
 
const char * muse_wave_lines_get_lampname (cpl_table *aTable, const int aIdx)
 Associate the ion listed in a linelist table row to a lamp name. More...
 
cpl_boolean muse_wave_lines_covered_by_data (double aLambda, muse_ins_mode aMode)
 Check, if a given wavelength is covered by a given instrument mode. More...
 
cpl_table * muse_wave_lines_search (muse_image *aColumnImage, double aSigma, const unsigned short aSlice, const unsigned char aIFU)
 Search and store emission lines in a column of an arc frame. More...
 
cpl_error_code muse_wave_lines_identify (cpl_table *aLines, cpl_vector *aLambdas, const muse_wave_params *aParams)
 Identify the wavelength of arc detected lines using pattern matching. More...
 
cpl_table * muse_wave_line_handle_singlet (muse_image *aImage, cpl_table *aLinelist, unsigned int aIdx, cpl_polynomial *aPoly, cpl_polynomial **aTrace, const muse_wave_params *aParams, const unsigned short aSlice, int aDebug)
 Handle fitting of all single lines across the columns a given slice. More...
 
cpl_table * muse_wave_line_handle_multiplet (muse_image *aImage, cpl_table *aLinelist, unsigned int aIdx, cpl_polynomial *aPoly, cpl_polynomial **aTrace, const muse_wave_params *aParams, const unsigned short aSlice, int aDebug)
 Handle fitting of all multiplets across the columns a given slice. More...
 
cpl_error_code muse_wave_line_fit_single (muse_image *aImage, int aX, double aY, int aHalfWidth, double aSigma, cpl_table *aFitTable, int aRowsNeeded)
 Fit a Gaussian to a single emission line in an arc frame and do simple error handling. More...
 
cpl_error_code muse_wave_line_fit_multiple (muse_image *aImage, int aX, cpl_bivector *aPeaks, cpl_vector *aLambdas, int aHalfWidth, double aSigma, cpl_table *aFitTable, int aRowsNeeded)
 Fit a multi-Gaussian to a multiplet of arc emission lines and do simple error handling. More...
 
cpl_error_code muse_wave_line_fit_iterate (cpl_table *aFitTable, double aLambda, const muse_wave_params *aParams)
 Use a low-order polynomial to find and discard bad values for line centroid fits of single arc line across one slice. More...
 
cpl_error_code muse_wave_poly_fit (cpl_matrix *aXYPos, cpl_vector *aLambdas, cpl_vector *aDLambdas, cpl_polynomial **aPoly, double *aMSE, muse_wave_params *aParams, const unsigned short aSlice)
 Compute the wavelength solution from the sample positions and the respective wavelengths. More...
 
cpl_table * muse_wave_table_create (const unsigned short aNSlices, const unsigned short aXOrder, const unsigned short aYOrder)
 Create the table to save te wave wavelength calibration coefficients. More...
 
cpl_error_code muse_wave_table_add_poly (cpl_table *aTable, cpl_polynomial *aPoly, double aMSE, unsigned short aXOrder, unsigned short aYOrder, const unsigned short aRow)
 Save the given polynomials to the wavelength calibration table. More...
 
cpl_error_code muse_wave_table_get_orders (const cpl_table *aWave, unsigned short *aXOrder, unsigned short *aYOrder)
 Determine the x- and y-order of the polynomial stored in a wavelength calibration table. More...
 
cpl_polynomial * muse_wave_table_get_poly_for_slice (const cpl_table *aTable, const unsigned short aSlice)
 Construct polynomial from the wavelength calibration table entry for the given slice. More...
 
cpl_image * muse_wave_map (muse_image *aImage, const cpl_table *aWave, const cpl_table *aTrace)
 Write out a wavelength map for visual checks. More...
 
cpl_error_code muse_wave_plot_residuals (cpl_table *aTable, unsigned char aIFU, unsigned short aSlice, unsigned int aIter, cpl_boolean aPlotLambda, cpl_vector *aCuts)
 Fancy plotting of wavelength calibration residuals (color coded over x/y-position) using gnuplot. More...
 
cpl_error_code muse_wave_plot_column (cpl_table *aCTable, cpl_table *aRTable, unsigned char aIFU, unsigned short aSlice, unsigned int aColumn, unsigned int aIter, cpl_boolean aPlotRes)
 Plot wavelength calibration polynomial and data or residuals using gnuplot. More...
 

Variables

const muse_cpltable_def muse_wavelines_def []
 MUSE wavelength calibration arc line fit properties table definition. More...
 
const muse_cpltable_def muse_wavedebug_def []
 MUSE wavelength calibration residuals table definition.
 

Detailed Description

Enumeration Type Documentation

Type of weighting to use in the wavelength calibration fit.

Enumerator
MUSE_WAVE_WEIGHTING_UNIFORM 

no weighting, i.e. uniform weights

MUSE_WAVE_WEIGHTING_CERR 

weighting by inverse centroiding error

MUSE_WAVE_WEIGHTING_SCATTER 

weighting by inverse RMS scatter of each line

MUSE_WAVE_WEIGHTING_CERRSCATTER 

weighting by combined inverse centroiding * error and inverse RMS scatter of each line

Definition at line 48 of file muse_wavecalib.h.

Function Documentation

cpl_table* muse_wave_calib ( muse_image aImage,
cpl_table *  aTrace,
cpl_table *  aLinelist,
muse_wave_params aParams 
)

Find wavelength calibration solution on an arc frame.

Parameters
aImageholds the arc frame to be used for calibration
aTracetable containing the tracing solution
aLinelisttable of expected arc lines
aParamswavelength calibration parameters
Returns
The cpl_table * containing the wavelength calibration polynomials or NULL in case of error.

Loop over all slices: first detect all arc emission lines in a column extracted from the center of the slice (on the filtered image), using muse_wave_lines_search(). Identify all detected arc lines using pattern matching against the input line list (with cpl_ppm_match_positions()). Then measure the position of each identified arc line outwards from the center to the edges of the slice (on the original input image), using muse_wave_line_fit_single(). Finally, derive a two-dimensional polynomial wavelength solution for each slice, using muse_wave_create_poly() and store it with muse_wave_poly_to_table().

If aParams->rflag is true, the table aParams->residuals is created and filled using data on the fit iterations, by muse_wave_poly_fit().

Note
The FITS headers of the input image will be modified to contain ESO QC keywords of the wavelength calibration. Existing ESO QC keywords will be removed.
Quality Assessment:
Residuals of the polynomial fit will be a robust indicator for failures. To exclude that misidentifications of arc lines conspire to give good but wrong solutions, the fitting solutions of neighboring slices can be compared.
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLinput image is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLinput image does not contain valid STAT extension
set CPL_ERROR_NULL_INPUT, return NULLtrace table is NULL
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLtrace table does not contain the right number of slices
set CPL_ERROR_NULL_INPUT, return NULLinput arc line list is NULL
set CPL_ERROR_NULL_INPUT, return NULLinput parameters structure is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLvertical size of the data is below 4000 pixels
set CPL_ERROR_BAD_FILE_FORMAT, return NULLloading reference wavelengths from table did not work

Definition at line 670 of file muse_wavecalib.c.

References muse_image::data, muse_wave_params::ddisp, muse_wave_params::detsigma, muse_image::dq, muse_wave_params::fitweighting, muse_image::header, muse_combine_median_create(), muse_cpltable_new(), muse_cplvector_count_unique(), muse_image_delete(), muse_image_new(), muse_imagelist_delete(), muse_imagelist_new(), muse_imagelist_set(), muse_pfits_get_bunit(), muse_trace_polys_delete(), muse_trace_table_get_polys_for_slice(), muse_utils_get_ifu(), muse_wave_line_fit_iterate(), muse_wave_line_fit_single(), muse_wave_lines_get(), muse_wave_lines_identify(), muse_wave_lines_search(), muse_wave_poly_fit(), muse_wave_table_add_poly(), muse_wave_table_create(), MUSE_WAVE_WEIGHTING_CERRSCATTER, MUSE_WAVE_WEIGHTING_UNIFORM, muse_wave_params::residuals, muse_image::stat, muse_wave_params::xorder, and muse_wave_params::yorder.

cpl_table* muse_wave_calib_lampwise ( muse_imagelist aImages,
cpl_table *  aTrace,
cpl_table *  aLinelist,
muse_wave_params aParams 
)

Find wavelength calibration solution using a list of arc images with different lamps.

Parameters
aImagesthe list of arc images to be used for calibration
aTracetable containing the tracing solution
aLinelisttable of expected arc lines
aParamswavelength calibration parameters
Returns
The cpl_table * containing the coefficients of the wavelength calibration polynomials or NULL in case of error.
Algorithm:
Check the input imagelist to make sure that the images all have the same size, and don't contain QC parameters any more.

Loop over all slices: use tracing information to locate the vertical center of each slice. Loop over all input images (all lamps) and median-combine three CCD columns around the slice center to create a spectra which are then used separately to detect, using muse_wave_lines_search(), the arc emission lines. Use the fluxes measured to select appropriate lines from the input linelist for identify and call muse_wave_lines_identify() to assign wavelengths. Create a combined, sorted list of such identified lines for all lamps, and use it to derive a first one-dimensional (vertical) wavelength solution.

Loop through all lines suitable for measurement from the input linelist, use the 1D solution to determine each line position on the CCD. Fit Gaussians to each arc line in all CCD columns, using muse_wave_line_fit_single(), going outwards from the center of the slice to its edges. Use a horizontal one-dimensional polynomial fit, using muse_wave_line_fit_iterate(), to reject outliers in the measurements of each arc line.

Finally, use all such measurements to derive the final two-dimensional wavelength solution for the slice, iteratively rejecting outliers, with muse_wave_poly_fit(). The polynomial is saved to the output table using muse_wave_table_add_poly().

Note
If aParams->rflag is true, the table aParams->residuals is created and filled using data on the fit iterations, by muse_wave_poly_fit().
Output QC parameters are returned in the headers of the images in the input imagelist, previously present QC paramters are deleted (using the "^ESO QC" regular expression).
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLinput imagelist is NULL or empty
set CPL_ERROR_NULL_INPUT, return NULLtrace table is NULL
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLtrace table does not contain the right number of slices
set CPL_ERROR_NULL_INPUT, return NULLinput arc line list is NULL
set CPL_ERROR_NULL_INPUT, return NULLinput parameters structure is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLvertical size of the data is below 4000 pixels
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLimagelist is not uniform
set CPL_ERROR_BAD_FILE_FORMAT, return NULLloading reference wavelengths from table did not work
set CPL_ERROR_DATA_NOT_FOUND, continue with next slicesearching for arc lines and line identification did not find enough lines
propagate error code, continue with next slicederiving polynomial solution produced error

Definition at line 1119 of file muse_wavecalib.c.

References muse_image::data, muse_wave_params::ddisp, muse_wave_params::detsigma, muse_image::dq, muse_wave_params::fitweighting, muse_image::header, muse_combine_median_create(), muse_cpltable_new(), muse_cplvector_count_unique(), muse_image_delete(), muse_image_new(), muse_imagelist_delete(), muse_imagelist_get(), muse_imagelist_get_size(), muse_imagelist_new(), muse_imagelist_set(), muse_pfits_get_bunit(), muse_trace_polys_delete(), muse_trace_table_get_polys_for_slice(), muse_utils_get_ifu(), muse_utils_header_get_lamp_names(), muse_utils_header_get_lamp_numbers(), muse_utils_iterate_fit_polynomial(), muse_wave_line_handle_multiplet(), muse_wave_line_handle_singlet(), muse_wave_lines_get(), muse_wave_lines_get_for_lamp(), muse_wave_lines_get_lampname(), muse_wave_lines_identify(), muse_wave_lines_search(), muse_wave_poly_fit(), muse_wave_table_add_poly(), muse_wave_table_create(), MUSE_WAVE_WEIGHTING_CERRSCATTER, MUSE_WAVE_WEIGHTING_UNIFORM, muse_image::stat, muse_wave_params::xorder, and muse_wave_params::yorder.

cpl_error_code muse_wave_line_fit_iterate ( cpl_table *  aFitTable,
double  aLambda,
const muse_wave_params aParams 
)

Use a low-order polynomial to find and discard bad values for line centroid fits of single arc line across one slice.

Parameters
aFitTablethe table holding the fit results at all positions
aLambdawavelength of the line to fit
aParamswavelength calibration parameters
Returns
CPL_ERROR_NONE on success, another CPL error code on failure.
Note
aFitTable is changed to return the fit result!

This function fits a polynomial to all detected arc line centers and uses this to remove deviant values (that could be due to low S/N in single spectra or blemishes (bad pixels/cosmic ray hits) on the CCD.

aLambda is used to select the correct entries for a single line in aFitTable. If aLambda is negative, this function assumes that aFitTable only contains fits of a single arc line, and skips the selection by wavelength.

Of the parameter passed in aParams, xorder, linesigma, and fitweighting are used here (read-only). The fit done here is not actually weighted, no matter what aParams->fitweighting is set, but that setting decides in which way the "cerr" column of aFitTable is handled: nothing is done for MUSE_WAVE_WEIGHTING_UNIFORM and MUSE_WAVE_WEIGHTING_CERR, but for MUSE_WAVE_WEIGHTING_SCATTER the RMS of the polynomial fit replaces the original error and for MUSE_WAVE_WEIGHTING_CERRSCATTER the RMS is added to the original "cerr" in quadrature. In case the fit fails, this most likely happens when not enough points are present before or after iterating the fit, all output errors will be set to 10, a value higher than can normally be reached.

(Alternatively, one could use the polynomial to replace detected positions with interpolated values from the polynomial fit. But in that case one loses the positional error estimates of the Gaussian fit to the arc line, that's why this is not currently done.)

Exceptions
return CPL_ERROR_NULL_INPUTaFitTable is NULL
return CPL_ERROR_ILLEGAL_INPUTaFitTable has no entries
use 2.5aParams->linesigma is negative

Definition at line 2917 of file muse_wavecalib.c.

References muse_wave_params::fitweighting, muse_wave_params::linesigma, muse_utils_iterate_fit_polynomial(), MUSE_WAVE_WEIGHTING_CERRSCATTER, MUSE_WAVE_WEIGHTING_SCATTER, and muse_wave_params::xorder.

Referenced by muse_wave_calib(), muse_wave_line_handle_multiplet(), and muse_wave_line_handle_singlet().

cpl_error_code muse_wave_line_fit_multiple ( muse_image aImage,
int  aX,
cpl_bivector *  aPeaks,
cpl_vector *  aLambdas,
int  aHalfWidth,
double  aSigma,
cpl_table *  aFitTable,
int  aRowsNeeded 
)

Fit a multi-Gaussian to a multiplet of arc emission lines and do simple error handling.

Parameters
aImagemuse_image that holds the arc frame
aXthe column in the arc frame
aPeaksfirst-guess values of the peaks to fit (the bivector components are y-position and flux)
aLambdaswavelengths corresponding to the peaks
aHalfWidthhalf-width of the region to extract
aSigmacommon sigma of the multi-Gaussian function, can be negative to signify handling as fixed parameter
aFitTabletable to which the result is written
aRowsNeedednumber of rows that the table needs to write this line
Returns
CPL_ERROR_NONE on success, another CPL error code on failure.
Remarks
The return value is just a diagnostic; the actual result is returned in the aFitTable parameter (see DRLDesign document (6.6) for table layout).

This function wraps muse_utils_fit_multigauss_1d() to fit multiple arc emission lines with a multi-Gaussian function. The results of this fit are written to the input table (aFitTable), which is enlarged as necessary.

aPeaks is filled with the results of the fit, so they can be used as start for another fit in a neighboring column.

Exceptions
return CPL_ERROR_NULL_INPUTaImage, its data or stat components, or aFitTable are NULL
propagate return code of muse_utils_fit_multigauss_1d() or CPL_ERROR_ILLEGAL_OUTPUTmulti-Gaussian fit failed (no covariance matrix)
propagate return code of muse_utils_fit_multigauss_1d()multi-Gaussian fit failed (other cases)
return CPL_ERROR_ACCESS_OUT_OF_RANGEmulti-Gaussian fit gave unexpectedly large offset
return CPL_ERROR_ILLEGAL_OUTPUTmulti-Gaussian fit resulted in line(s) with negative fluxes
enlarge tableaFitTable has less rows than needed

Definition at line 2735 of file muse_wavecalib.c.

References muse_image::data, muse_utils_fit_multigauss_1d(), and muse_image::stat.

Referenced by muse_wave_line_handle_multiplet().

cpl_error_code muse_wave_line_fit_single ( muse_image aImage,
int  aX,
double  aY,
int  aHalfWidth,
double  aSigma,
cpl_table *  aFitTable,
int  aRowsNeeded 
)

Fit a Gaussian to a single emission line in an arc frame and do simple error handling.

Parameters
aImagemuse_image that holds the arc frame
aXthe column in the arc frame
aYthe most likely position in the y-direction
aHalfWidthhalf-width of the region to extract
aSigmasigma of the Gaussian function to fit the arc line, can be negative to signify handling as fixed parameter
aFitTabletable to which the result is written
aRowsNeedednumber of rows that the table needs to write this line
Returns
CPL_ERROR_NONE on success, another CPL error code on failure.
Remarks
The return value is just a diagnostic; the actual result is returned in the aFitTable parameter (see DRLDesign document (6.6) for table layout).

This function wraps cpl_vector_fit_gaussian() to fit a single arc emission line with a Gaussian function. The results of this fit are written to the input table (aFitTable), which is enlarged if necessary.

Exceptions
return CPL_ERROR_NULL_INPUTaImage, its data or stat components, or aFitTable are NULL
propagate return code of cpl_vector_fit_gaussian() or CPL_ERROR_ILLEGAL_OUTPUTGaussian fit failed (no covariance matrix)
propagate return code of cpl_vector_fit_gaussian()Gaussian fit failed (other cases)
return CPL_ERROR_ACCESS_OUT_OF_RANGEGaussian fit gave unexpectedly large offset
enlarge tableaFitTable has less rows than needed

Definition at line 2579 of file muse_wavecalib.c.

References muse_image::data, and muse_image::stat.

Referenced by muse_wave_calib(), and muse_wave_line_handle_singlet().

cpl_table* muse_wave_line_handle_multiplet ( muse_image aImage,
cpl_table *  aLinelist,
unsigned int  aIdx,
cpl_polynomial *  aPoly,
cpl_polynomial **  aTrace,
const muse_wave_params aParams,
const unsigned short  aSlice,
int  aDebug 
)

Handle fitting of all multiplets across the columns a given slice.

Parameters
aImageimage with the arc line to fit
aLinelistlist of arc lines
aIdxindex of the first line of the multiplet in aLineList
aPolyfirst-guess polynomial wavelength solution in the middle of the slice
aTracearray of the three tracing polynomials
aParamswavelength calibration parameters
aSliceslice number (for debug output)
aDebugdebug level
Returns
A cpl_table containing all fit results on success or NULL on error.

The remaining line(s) of the multiplet are searched in aLinelist, and their first-guess y-positions are computed using aPoly. The slice edges are computed for the average y-position using aTrace. Then muse_wave_line_fit_multiple() is called for each CCD column, moving from the center of the slice to both edges, using first-guess position and a default value (taken to be the nominal instrumental width) for the Gaussian sigma. The result from the previous (neighboring) CCD column is taken as first-guess position of the next column, if it did not significantly differ from the previous result. Fits that went wrong are ignored. Possibly deviant fits are rejected using a 1D polynomial fit of aParams->xorder, calling muse_wave_line_fit_iterate() separately for each of the arc lines of the multiplet.

Note
This function changes aLinelist to invert the sign on the MUSE_LINE_CATALOG_QUALITY column for all multiplet components already used.
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaImage, aLinelist, aPoly, or aTrace are NULL
return NULLfirst-guess y-position of the arc lines is near the edge or even outside the image

Definition at line 2389 of file muse_wavecalib.c.

References muse_image::data, muse_image::header, muse_cpltable_new(), muse_utils_get_ifu(), muse_wave_line_fit_iterate(), muse_wave_line_fit_multiple(), and muse_wave_lines_get_lampname().

Referenced by muse_wave_calib_lampwise().

cpl_table* muse_wave_line_handle_singlet ( muse_image aImage,
cpl_table *  aLinelist,
unsigned int  aIdx,
cpl_polynomial *  aPoly,
cpl_polynomial **  aTrace,
const muse_wave_params aParams,
const unsigned short  aSlice,
int  aDebug 
)

Handle fitting of all single lines across the columns a given slice.

Parameters
aImageimage with the arc line to fit
aLinelistlist of arc lines
aIdxindex of the current line in aLineList
aPolyfirst-guess polynomial wavelength solution in the middle of the slice
aTracearray of the three tracing polynomials
aParamswavelength calibration parameters
aSliceslice number (for debug output)
aDebugdebug level
Returns
A cpl_table containing all fit results on success or NULL on error.

The first-guess y-position for the arc line at index aIdx in aLinelist is computed using aPoly. The slice edges are computed for this position using aTrace. Then muse_wave_line_fit_single() is called for each CCD column, moving from the center of the slice to both edges, using first-guess position and a default value (taken to be the nominal instrumental width) for the Gaussian sigma. If the arc lines at aIdx is not a FWHM reference line, the sigma passed is negative to signify a fixed sigma to the fitting procedure. The result from the previous (neighboring) CCD column is taken as first-guess position of the next column, if it did not significantly differ from the previous result. Fits that went wrong are ignored. Possibly deviant fits are rejected using a 1D polynomial fit of aParams->xorder, using muse_wave_line_fit_iterate().

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaImage, aLinelist, aPoly, or aTrace are NULL
return NULLfirst-guess y-position of the arc line is near the edge or even outside the image

Definition at line 2234 of file muse_wavecalib.c.

References muse_image::data, muse_image::header, muse_cpltable_new(), muse_utils_get_ifu(), muse_wave_line_fit_iterate(), and muse_wave_line_fit_single().

Referenced by muse_wave_calib_lampwise().

cpl_boolean muse_wave_lines_check ( muse_table aTable)

Check that a LINE_CATALOG has the expected format.

Parameters
aTablethe line list table in MUSE format (table + header)
Returns
CPL_TRUE when format matches expectations, CPL_FALSE otherwise.

Expected format currently means that the MUSE_LINE_CATALOG_LAMBDA and MUSE_LINE_CATALOG_QUALITY table columns are present, and that the header has an entry "VERSION = 3".

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaTable is NULL or empty or aHeader is NULL
output error message, set CPL_ERROR_DATA_NOT_FOUND, return NULLinput table does not contain the required columns
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLtable does not contain a VERSION header

Definition at line 1567 of file muse_wavecalib.c.

References muse_table::header, muse_cpltable_check(), muse_line_catalog_def, and muse_table::table.

cpl_boolean muse_wave_lines_covered_by_data ( double  aLambda,
muse_ins_mode  aMode 
)

Check, if a given wavelength is covered by a given instrument mode.

Parameters
aLambdathe wavelength to check
aModethe MUSE instrument mode
Returns
CPL_TRUE is the mode covers the wavelength, CPL_FALSE otherwise.

Definition at line 1784 of file muse_wavecalib.c.

Referenced by muse_lsf_create_arcpixtable(), and muse_wave_poly_fit().

cpl_vector* muse_wave_lines_get ( cpl_table *  aTable,
int  aGoodnessLimit,
double  aFluxLimit 
)

Load usable wavelengths from a linelist table into a vector.

Parameters
aTabletable containing the linelist
aGoodnessLimitlower limit of the goodness of a line
aFluxLimitlower limit of the flux of a line
Returns
the cpl_vector * containing the wavelengths of usable lines or NULL in case of error

This uses the column MUSE_LINE_CATALOG_LAMBDA for the wavelengths and column MUSE_LINE_CATALOG_QUALITY for the quality setting. It expects that the input table is sorted by increasing wavelength. If lines occur that are closer together than 1.5 Angstrom, they are removed from the output.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLinput table is NULL or empty
output error message, set CPL_ERROR_DATA_NOT_FOUND, return NULLinput table does not contain the required columns
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLtable is not sorted by increasing wavelength
set CPL_ERROR_DATA_NOT_FOUND, return NULLno limes passing aGoodnessLimit were found

Definition at line 1620 of file muse_wavecalib.c.

References muse_cplvector_erase_element().

Referenced by muse_wave_calib(), muse_wave_calib_lampwise(), and muse_wave_lines_get_for_lamp().

cpl_vector* muse_wave_lines_get_for_lamp ( cpl_table *  aTable,
const char *  aLamp,
int  aGoodnessLimit,
double  aFluxLimit 
)

Load wavelengths for a given lamp from a linelist table into a vector.

Parameters
aTabletable containing the linelist
aLampthe name of the lamp
aGoodnessLimitlower limit of the goodness of a line
aFluxLimitlower limit of the flux of a line
Returns
the cpl_vector * containing the wavelengths of usable lines or NULL in case of error

This extracts those entries in the table corresponding to the given lamp, using muse_wave_lines_get_lampname(), and then calls muse_wave_lines_get() to create the vector for them.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaTable is NULL or empty or aLamp is NULL

Definition at line 1711 of file muse_wavecalib.c.

References muse_wave_lines_get(), and muse_wave_lines_get_lampname().

Referenced by muse_wave_calib_lampwise().

const char* muse_wave_lines_get_lampname ( cpl_table *  aTable,
const int  aIdx 
)

Associate the ion listed in a linelist table row to a lamp name.

Parameters
aTabletable containing the linelist
aIdxthe row index in the table
Returns
one of "HgCd", "Ne", or "Xe" on success, "Unknown_Lamp" on error.

This just uses string comparison of the first two characters in the ion column to set the corresponding lamp name.

Exceptions
set CPL_ERROR_NULL_INPUT, return ,Unknown_Lamp""aTable is NULL
set CPL_ERROR_ILLEGAL_INPUT, return ,Unknown_Lamp""row aIdx does not contain a valid ion

Definition at line 1754 of file muse_wavecalib.c.

Referenced by muse_lsf_create_arcpixtable(), muse_wave_calib_lampwise(), muse_wave_line_handle_multiplet(), and muse_wave_lines_get_for_lamp().

cpl_error_code muse_wave_lines_identify ( cpl_table *  aLines,
cpl_vector *  aLambdas,
const muse_wave_params aParams 
)

Identify the wavelength of arc detected lines using pattern matching.

Parameters
aLinesthe arc line fit properties table
aLambdasthe reference arc line list
aParamswavelength calibration parameters
Returns
CPL_ERROR_NONE on success, another CPL error code on failure.

The identified lines are stored in the input table aLines, non-identified lines are removed from the table, the wavelengths of the identified lines are appended in the "lambda" column.

Of the parameter passed in aParams, ddisp, tolerance, and yorder are used here (read-only).

Exceptions
return CPL_ERROR_NULL_INPUTaLines or aLambdas is NULL
return CPL_ERROR_DATA_NOT_FOUNDno arc lines could be identified
return CPL_ERROR_ILLEGAL_OUTPUTcould not identify enough arc lines to fit polynomials of order aParams->yorder

Definition at line 2128 of file muse_wavecalib.c.

References muse_wave_params::ddisp, and muse_wave_params::tolerance.

Referenced by muse_wave_calib(), and muse_wave_calib_lampwise().

cpl_table* muse_wave_lines_search ( muse_image aColumnImage,
double  aSigma,
const unsigned short  aSlice,
const unsigned char  aIFU 
)

Search and store emission lines in a column of an arc frame.

Parameters
aColumnImagemuse_image that holds the column
aSigmasigma (median deviation) as criterion for a line
aSliceslice number (for debug output)
aIFUthe IFU number (for output)
Returns
The arc line fit properties table or NULL on error.
Remarks
See DRLDesign document (6.6) for layout of returned table.

This function uses the detection threshold of aSigma times median deviation above the (median) background value of the S/N values of the input spectrum. Before attempting this S/N-based detetion, the background of the spectrum is removed by subtracting a wide median-filtered version of the data. (If the incoming arc exposure was flat-field corrected, using the S/N ensures that no spurious noise peaks in the blue part of the spectrum are mistaken as arc lines.) The detections are used to create a mask of the line locations. Detections of single pixels are rejected. The center of each of the remaining locations is then used as a starting value to fit a Gaussian function, to derive a good first estimate of the line position. Finally, the results of the Gaussian fits are evaluated and lines with improbable fits (too narrow/broad, too faint, uncertain position) are removed from the output.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLthe input column image is NULL
set CPL_ERROR_DATA_NOT_FOUND, return NULLvariance extension invalid
set CPL_ERROR_ILLEGAL_INPUT, return NULLaSigma <= 0

Definition at line 1838 of file muse_wavecalib.c.

References muse_image::data, muse_cpltable_new(), muse_image_save(), and muse_image::stat.

Referenced by muse_wave_calib(), and muse_wave_calib_lampwise().

cpl_image* muse_wave_map ( muse_image aImage,
const cpl_table *  aWave,
const cpl_table *  aTrace 
)

Write out a wavelength map for visual checks.

Parameters
aImageimage that used to contruct the map
aWavethe table containing the wavelength calibration solution
aTracethe table containing the tracing solution
Returns
a cpl_image * containing the wavelength map or NULL on error
Remarks
A wavelength map is an image in which the value of each pixel is the wavelength that is assigned to it by the wavelength calibration. It can be useful during debugging.
Only the dimensions of the data component of aImage are used (for the construction of the output map). Its header, dq, and stat extensions do not need to exist.

Loop through all pixels in the image, evaluate, if the pixel is within a slice. If so, evaluate the respective wavelength solution and set the pixel value in the output image to the wavelength derived.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLthe input image, the input wavelength calibration solution table, or the input trace solution table are NULL

Definition at line 3654 of file muse_wavecalib.c.

References muse_image::data, muse_image::header, muse_trace_polys_delete(), muse_trace_table_get_order(), muse_trace_table_get_polys_for_slice(), muse_utils_get_ifu(), muse_wave_table_get_orders(), and muse_wave_table_get_poly_for_slice().

void muse_wave_params_delete ( muse_wave_params aParams)

Deallocate memory associated to a wavelength parameters structure.

Parameters
aParamsarc line fit properties table

Deallocates the residuals component of aParams before freeing the whole structure. As a safeguard, it checks if a valid pointer was passed, so that crashes cannot occur.

Definition at line 193 of file muse_wavecalib.c.

References muse_image::data, muse_image::header, muse_pfits_get_lampnum(), muse_pfits_get_mode(), muse_utils_get_ifu(), and muse_wave_params::residuals.

muse_wave_params* muse_wave_params_new ( cpl_propertylist *  aHeader)

Allocate a wavelength parameters structure and fill it with defaults.

Parameters
aHeaderoptional FITS header to set instrument mode
Returns
the newly allocated structure

Allocate memory to store the pointers of the muse_wave_params structure. The structure is filled with defaults that are known to give reasonable results, pflags is set to CPL_FALSE, so that by default not residuals table is created.

If aHeader was given, the mode component is set to the correct MUSE instrument mode. If it is NULL, mode remains zero, indicating WFM-NOAO-N.

Use muse_wave_params_delete() to free the memory of the returned object after use.

Definition at line 158 of file muse_wavecalib.c.

References muse_wave_params::ddisp, muse_wave_params::detsigma, muse_wave_params::fitsigma, muse_wave_params::fitweighting, muse_wave_params::linesigma, muse_wave_params::mode, muse_pfits_get_insmode(), muse_pfits_get_mode(), MUSE_WAVE_WEIGHTING_UNIFORM, muse_wave_params::residuals, muse_wave_params::rflag, muse_wave_params::targetrms, muse_wave_params::tolerance, muse_wave_params::xorder, and muse_wave_params::yorder.

cpl_error_code muse_wave_plot_column ( cpl_table *  aCTable,
cpl_table *  aRTable,
unsigned char  aIFU,
unsigned short  aSlice,
unsigned int  aColumn,
unsigned int  aIter,
cpl_boolean  aPlotRes 
)

Plot wavelength calibration polynomial and data or residuals using gnuplot.

Parameters
aCTablethe table with the wavelength solution polynomials
aRTablethe table with debug information on wavelength calibration residuals
aIFUthe IFU number (only used if > 0)
aSliceslice number to plot
aIteriteration to plot (0 for the last one)
aColumnCCD column to plot (0 for the central one of the slice)
aPlotResif true, plot lambda values on the y axis
Returns
CPL_ERROR_NONE on success a CPL error code on failure
Note
This function directly works on the input table data, i.e. erases all rows that are not relevant!
Exceptions
return CPL_ERROR_NULL_INPUTone of the input tables is NULL
return CPL_ERROR_ILLEGAL_INPUTone of the input tables is faulty
return CPL_ERROR_ACCESS_OUT_OF_RANGEslice number is invalid
return CPL_ERROR_ASSIGNING_STREAMgnuplot stream (pipe) could not be opened
return CPL_ERROR_UNSUPPORTED_MODEplatform does not have popen() or pclose()
return CPL_ERROR_DATA_NOT_FOUNDdata for this slice/iteration was not found in the input table

Definition at line 3972 of file muse_wavecalib.c.

References muse_cpltable_check(), and muse_wave_table_get_orders().

cpl_error_code muse_wave_plot_residuals ( cpl_table *  aTable,
unsigned char  aIFU,
unsigned short  aSlice,
unsigned int  aIter,
cpl_boolean  aPlotLambda,
cpl_vector *  aCuts 
)

Fancy plotting of wavelength calibration residuals (color coded over x/y-position) using gnuplot.

Parameters
aTablethe table with debug information on wavelength calibration residuals
aIFUthe IFU number (only used if > 0)
aSliceslice number to plot (0 for all)
aIteriteration to plot (0 for the last one)
aPlotLambdaif true, plot lambda values on the y axis
aCutsif not NULL and of size 2, use contents as color cuts
Returns
CPL_ERROR_NONE on success a CPL error code on failure
Note
This function directly works on the input table data, i.e. erases all rows that are not relevant!
Exceptions
return CPL_ERROR_ILLEGAL_INPUTinput table is not a MUSE wavelength calibration residuals table
return CPL_ERROR_ASSIGNING_STREAMgnuplot stream (pipe) could not be opened
return CPL_ERROR_UNSUPPORTED_MODEplatform does not have popen() or pclose()
return CPL_ERROR_DATA_NOT_FOUNDdata for this slice/iteration was not found in the input table

Definition at line 3766 of file muse_wavecalib.c.

References muse_cpltable_check().

cpl_error_code muse_wave_poly_fit ( cpl_matrix *  aXYPos,
cpl_vector *  aLambdas,
cpl_vector *  aDLambdas,
cpl_polynomial **  aPoly,
double *  aMSE,
muse_wave_params aParams,
const unsigned short  aSlice 
)

Compute the wavelength solution from the sample positions and the respective wavelengths.

Parameters
aXYPosthe matrix with the x- and y-positions
aLambdasthe vector with the wavelengths at all positions
aDLambdasthe vector with the wavelength errors at all positions (can be NULL)
aPolythe wavelength solution polynomial that is computed here
aMSEthe mean squared error of the solution, computed here
aParamswavelength calibration parameters
aSliceslice number (for use with aParams->residuals)
Returns
CPL_ERROR_NONE on success, another CPL error code on failure.

The polynomial is allocated within this function, it has to be deallocated using cpl_polynomial_delete(). If this function returns with a failure, no deallocations are necessary.

The input list of measurements is checked against the instrument mode set in aParams->mode, to see if a line is actually giving a good measurement in that mode. This is meant to exclude lines at the blue end of the wavelength range but especially inside the NaD notch filter region. (If a line is detected there it might still be shifted in wavelength due to the strongly varying filter function.)

The mean-squared error aMSE computed here is weighted using the inverse of the wavelength errors, if aDLambdas is given. The rejection limit used within each iteration is |aParams->fitsigma * aMSE|. The iterations converge and the result is returned, if one of the following is true:

  • an iteration results in an RMS below aParams->targetrms
  • the RMS has improved by only 0.001 Angstrom compared to the previous iteration
  • no residuals larger than the rejection limit are found

Of the parameter passed in aParams, xorder, yorder, fitsigma, and targetrms are used here (read-only); the residuals table is created and filled by this function, if rflag is true.

Exceptions
return CPL_ERROR_NULL_INPUTaPoly, aXYPos, or aLambdas are NULL
return CPL_ERROR_ILLEGAL_OUTPUTthe polynomial fit failed
use 3.0aParams->fitsigma is negative

Definition at line 3144 of file muse_wavecalib.c.

References muse_wave_params::fitsigma, muse_wave_params::mode, muse_cpltable_new(), muse_cplvector_erase_element(), muse_wave_lines_covered_by_data(), muse_wave_params::residuals, muse_wave_params::rflag, muse_wave_params::targetrms, muse_wave_params::xorder, and muse_wave_params::yorder.

Referenced by muse_wave_calib(), and muse_wave_calib_lampwise().

cpl_error_code muse_wave_table_add_poly ( cpl_table *  aTable,
cpl_polynomial *  aPoly,
double  aMSE,
unsigned short  aXOrder,
unsigned short  aYOrder,
const unsigned short  aRow 
)

Save the given polynomials to the wavelength calibration table.

Parameters
aTabletable to save the solution into
aPolythe wavelength solution polynomial
aMSEthe mean squared error for the solution
aXOrderthe polynomial order in x-direction
aYOrderthe polynomial order in y-direction
aRowtable row to use (slice index)
Returns
CPL_ERROR_NONE on success, a cpl_error_code on failure
Exceptions
return CPL_ERROR_NULL_INPUTaTable or aPoly are NULL
return CPL_ERROR_ILLEGAL_INPUTdimension of aPoly is not 2

Definition at line 3483 of file muse_wavecalib.c.

Referenced by muse_wave_calib(), and muse_wave_calib_lampwise().

cpl_table* muse_wave_table_create ( const unsigned short  aNSlices,
const unsigned short  aXOrder,
const unsigned short  aYOrder 
)

Create the table to save te wave wavelength calibration coefficients.

Parameters
aNSlicesthe number of slices to be stored in this table
aXOrderthe polynomial order in x-direction
aYOrderthe polynomial order in y-direction
Returns
the newly created table on success, NULL on error
Remarks
the returned table has to be deallocated using cpl_table_delete().

Definition at line 3435 of file muse_wavecalib.c.

Referenced by muse_wave_calib(), and muse_wave_calib_lampwise().

cpl_error_code muse_wave_table_get_orders ( const cpl_table *  aWave,
unsigned short *  aXOrder,
unsigned short *  aYOrder 
)

Determine the x- and y-order of the polynomial stored in a wavelength calibration table.

Parameters
aWavethe table containing the wavelength calibration solution
aXOrderthe pointer to the x-order to return
aYOrderthe pointer to the y-order to return
Returns
CPL_ERROR_NONE on success, another CPL error code on failure.

This function assumes that the second last column in the input table contains the highest order and that its name is of the format wlcXY where X and Y are the numbers that we want to find out here.

Exceptions
return CPL_ERROR_NULL_INPUTaWave, aXOrder, or aYOrder are NULL

Definition at line 3539 of file muse_wavecalib.c.

Referenced by muse_pixtable_create(), muse_wave_map(), muse_wave_plot_column(), and muse_wave_table_get_poly_for_slice().

cpl_polynomial* muse_wave_table_get_poly_for_slice ( const cpl_table *  aTable,
const unsigned short  aSlice 
)

Construct polynomial from the wavelength calibration table entry for the given slice.

Parameters
aTablewavelength calibration table holding the waveelength calibration solution
aSlicethe slice number, between 1 and kMuseSlicesPerCCD
Returns
the polynomial defining the wavelength solution of the given slice or NULL on error

The returned polynomial has to be deallocated using cpl_polynomial_delete() after use.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaTable is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLaSlice is outside the valid range of slices for MUSE
set CPL_ERROR_DATA_NOT_FOUND, return NULLthe requested slice cannot be found in the table
set CPL_ERROR_ILLEGAL_OUTPUT, return NULLa coefficient in aTable cannot be read

Definition at line 3583 of file muse_wavecalib.c.

References muse_wave_table_get_orders().

Referenced by muse_geo_measure_spots(), muse_pixtable_create(), and muse_wave_map().

Variable Documentation

const muse_cpltable_def muse_wavelines_def[]
Initial value:
= {
{ "lampno", CPL_TYPE_INT, "", "%d", "Number of the lamp", CPL_TRUE },
{ "lampname", CPL_TYPE_STRING, "", "%s", "Name of the lamp", CPL_TRUE },
{ "x", CPL_TYPE_DOUBLE, "pix", "%.2f", "x-position on CCD", CPL_TRUE },
{ "y", CPL_TYPE_DOUBLE, "pix", "%.2f", "first-guess y-position on CCD", CPL_TRUE },
{ "peak", CPL_TYPE_DOUBLE, "pix", "%g", "Peak of line", CPL_TRUE },
{ "center", CPL_TYPE_DOUBLE, "pix", "%.4f", "Gaussian line center", CPL_TRUE },
{ "cerr", CPL_TYPE_DOUBLE, "pix", "%.4f", "error estimate of line center", CPL_TRUE },
{ "sigma", CPL_TYPE_DOUBLE, "pix", "%.3f", "Gaussian sigma", CPL_TRUE },
{ "fwhm", CPL_TYPE_DOUBLE, "pix", "%.3f", "Gaussian FWHM", CPL_TRUE },
{ "flux", CPL_TYPE_DOUBLE, "count", "%g", "Gaussian area (flux)", CPL_TRUE },
{ "bg", CPL_TYPE_DOUBLE, "count", "%.2f", "background level", CPL_TRUE },
{ "mse", CPL_TYPE_DOUBLE, "", "%e", "mean squared error", CPL_TRUE },
{ "lambda", CPL_TYPE_DOUBLE, "Angstrom", "%9.3f",
"identified wavelength of the line", CPL_TRUE },
{ NULL, 0, NULL, NULL, NULL, CPL_FALSE }
}

MUSE wavelength calibration arc line fit properties table definition.

The wavelength calibration routines use a table to store the results of (Gaussian) fits to the arc lines. This table is not used anywhere else within the MUSE DRL. It has the following columns:

  • lampno: number of the lamp
  • lampname: name of the lamp
  • x: x-position on CCD
  • y: first-guess y-position on CCD
  • peak: Peak of line
  • center: Gaussian line center
  • cerr: error estimate of line center
  • sigma: Gaussian sigma
  • fwhm: Gaussian FWHM
  • flux: Gaussian area (flux)
  • bg: background level
  • mse: mean squared error
  • lambda: identified wavelength of the line

Not all table columns are always used, e.g. lambda can be empty if the arc lines were not yet identified.

Definition at line 95 of file muse_wavecalib.c.