MUSE Pipeline Reference Manual  2.1.1
Functions
DAR (Differential Atmospheric Refraction)

Functions

cpl_error_code muse_dar_correct (muse_pixtable *aPixtable, double aLambdaRef)
 Correct the pixel coordinates of all pixels of a given pixel table for differential atmospheric refraction (DAR). More...
 
cpl_error_code muse_dar_check (muse_pixtable *aPixtable, double *aMaxShift, cpl_boolean aCorrect, muse_datacube **aCube)
 check that the continuum of objects in the frame is well-aligned perpendicular to the spatial axis, to determine if the correction for differential atmospheric refraction (DAR) was sufficient More...
 

Detailed Description

Function Documentation

cpl_error_code muse_dar_check ( muse_pixtable aPixtable,
double *  aMaxShift,
cpl_boolean  aCorrect,
muse_datacube **  aCube 
)

check that the continuum of objects in the frame is well-aligned perpendicular to the spatial axis, to determine if the correction for differential atmospheric refraction (DAR) was sufficient

Parameters
aPixtablethe input pixel table to check and correct
aMaxShiftthe output parameter in which the maximum shift of the input data is returned (in arcsec)
aCorrectswitch to signify that the pixel table should be corrected for the derived residual shifts
aCubethe optional output cube
Returns
CPL_ERROR_NONE on success another CPL error code on failure
Remarks
The return value is just a diagnostic flag, the interesting value is returned in aMaxShift. If an error occurs, aMaxShift is set to -99.
This function will add a FITS header (MUSE_HDR_PT_DAR_CHECK) with the value of aMaxShift to the pixel table, so that other functions can detect, if DAR check has been run before on the same data.
This function will add a FITS header (MUSE_HDR_PT_DAR_CORR) with the value of the reference wavelength to the pixel table, if the residual correction was done.

Resample the input pixel table to a cube with coarse wavelength sampling (for reasons of speed and S/N). Find objects on the central plane of the cube and follow the center of each object to the first and last plane. The center is computed by a marginal centroid first, then refined using a (Gaussian) fit. (The centroid and fit are computed in a 11x11 pix box, if the data has previously been corrected for DAR effects – either using this function or muse_dar_correct() –, in a 31x31 pix box otherwise.) Compute the residual offsets for each object, average the individual results, and derive polynomials for the shifts, separately in x- and y-direction, for smooth correction with wavelength. Reset the zeropoint of both polynomials to be at the reference wavelength. Then use the polynomial to search for the extrema and those to finally derive the maximal shift.

The input pixel table can be corrected for the residual shift. In that case, it can be resampled onto a cube again afterwards for debugging.

Quality Assessment:
If there are significant residual shifts, they are visually apparent in any FITS cube viewer by sliding through the cube. The centroid of objects in each wavelength bin can also be measured externally to uncover small (sub-pixel) systematic shifts that cannot be seen by eye.
Exceptions
return CPL_ERROR_NULL_INPUTaPixtable or aMaxShift are NULL
return CPL_ERROR_INVALID_TYPEpixel table WCS type is not MUSE_PIXTABLE_WCS_PIXEL
output info message, do it againDAR correction for the input pixel table was already checked
output info message, do it againresidual DAR correction for the input pixel table was already applied
propagate error of muse_resampling_cuberesampling/saving output cube failed
return CPL_ERROR_DATA_NOT_FOUNDno usable objects found in the datacube

Definition at line 472 of file muse_dar.c.

References muse_resampling_params::crsigma, muse_image::data, muse_datacube::data, muse_image::dq, muse_datacube::dq, muse_datacube::header, muse_image::header, muse_pixtable::header, muse_combine_median_create(), muse_datacube_delete(), muse_datacube_save(), MUSE_HDR_PT_DAR_CHECK, MUSE_HDR_PT_DAR_CORR, MUSE_HDR_PT_DAR_NAME, MUSE_HDR_PT_PREDAR_XHI, MUSE_HDR_PT_PREDAR_XLO, MUSE_HDR_PT_PREDAR_YHI, MUSE_HDR_PT_PREDAR_YLO, MUSE_HDR_PT_XHI, MUSE_HDR_PT_XLO, MUSE_HDR_PT_YHI, MUSE_HDR_PT_YLO, muse_image_delete(), muse_image_new(), muse_image_reject_from_dq(), muse_image_save(), muse_imagelist_delete(), muse_imagelist_new(), muse_imagelist_set(), muse_pfits_get_cd(), muse_pfits_get_crpix(), muse_pfits_get_crval(), muse_pfits_get_mode(), muse_pixgrid_delete(), muse_pixgrid_get_count(), muse_pixgrid_get_index(), muse_pixgrid_get_rows(), muse_pixtable_compute_limits(), MUSE_PIXTABLE_DATA, MUSE_PIXTABLE_DQ, muse_pixtable_get_nrow(), MUSE_PIXTABLE_LAMBDA, muse_pixtable_reset_dq(), MUSE_PIXTABLE_STAT, muse_pixtable_wcs_check(), MUSE_PIXTABLE_WCS_PIXEL, MUSE_PIXTABLE_XPOS, MUSE_PIXTABLE_YPOS, muse_quality_image_reject_using_dq(), MUSE_RESAMPLE_WEIGHTED_DRIZZLE, muse_resampling_cube(), muse_resampling_params_delete(), muse_resampling_params_new(), MUSE_UTILS_CENTROID_MEAN, MUSE_UTILS_CENTROID_MEDIAN, muse_utils_fit_moffat_2d(), muse_utils_get_centroid(), muse_utils_image_get_centroid_window(), muse_utils_iterate_fit_polynomial(), muse_resampling_params::pfx, muse_image::stat, muse_datacube::stat, and muse_pixtable::table.

Referenced by muse_postproc_process_exposure().

cpl_error_code muse_dar_correct ( muse_pixtable aPixtable,
double  aLambdaRef 
)

Correct the pixel coordinates of all pixels of a given pixel table for differential atmospheric refraction (DAR).

Parameters
aPixtablethe input pixel table to correct for DAR
aLambdaRefthe reference wavelength (in Angstrom)
Returns
CPL_ERROR_NONE on success another CPL error code on failure
Remarks
The resulting correction is directly applied to the input pixel table.
All needed environmental parameters (temperature [°C] := 11.5, relative humidity [%] := 14.5, and atmospheric pressure [mbar] := 743.0; default values taken from the DAR IDL routine of Enrico Marchetti, ESO, January 2001) are taken from the FITS keywords passed in the muse_pixtable object, they exist in standard ESO FITS files as TEL.AMBI.TEMP, TEL.AMBI.RHUM, TEL.AMBI.PRES.START and TEL.AMBI.PRES.END. If the ambient site monitor was down when writing the files and these parameters are unknown, then the defaults are used.
This function adds a FITS header (MUSE_HDR_PT_DAR_NAME) with the value of aLambdaRef to the pixel table, so that other functions can detect, if DAR correction has already been carried out. If DAR correction was skipped due to a too low or too high aLambdaRef, this header is set to -1.
This function adds four FITS headers MUSE_HDR_PT_PREDAR_[XY]{LO,HI} (see muse_pixtable.h) to store the original values of the pixel table limits, before calling muse_pixtable_compute_limits().

Loop through all pixels of the input pixel table, compute the DAR offset for the wavelength difference with respect to the reference wavelength, and apply it to the coordinates, taking into account the instrument rotation angle on the sky and the parallactic angle at the time of the observations.

Four algorithms are available:

  • "Filippenko": The algorithm from Filippenko, 1982 PASP 94, 715. This only uses the formula from Owens which converts relative humidity to water vapor pressure.
  • "Owens": the algorithm from Sandin et al., 2008 A&A 486, 545 (see Sect. 2.5 of the DRL Design document for the formulae used) which is actually based on the diff_atm_refr.pro IDL script by Enrico Marchetti (ESO) who allowed to use it in a GPL program. The formulae originally come from J. C. Owens, 1967 Applied Optics 6, 51 - 59.
  • "Edlen": the algorithm from B. Edlén, 1966 Metrologia 2, 71 - 80 and K. P. Birch & M. J. Downs, 1993 Metrologia 30, 155 - 162.
  • "Ciddor": the algorithm from Phillip E. Ciddor, 1996 Applied Optics 35, 1566 - 1573. This method is supposed to be the most accurate way to compute the refractive index of air. These algorithms differ in the way they compute the refractive index of air. See http://emtoolbox.nist.gov/Wavelength/Documentation.asp#AppendixA for the formulae used here and muse_phys_air_to_vacuum() as well as the other functions in the muse_phys module for more information.

Use the environment variable MUSE_DAR_CORRECT_METHOD to switch the default from Filippenko to something else. They differ in the way the refractive index of air is computed from the environmental parameters.

Quality Assessment:
In case the exposure contains a bright enough continuum source, the function muse_dar_check can be used to check the result: after resampling, all objects should be aligned along the wavelength direction. In case of "empty" fields, a validation is difficult.
Exceptions
return CPL_ERROR_NULL_INPUTthe input pixel table or its header is NULL
output info message, skip the correction, return CPL_ERROR_NONEthe input reference wavelength is invalid (< 3500 or > 22000)
output info message, skip the correction, return CPL_ERROR_NONEthe input pixel table was already corrected for DAR
propagate CPL errorthe airmass value cannot be determined
propagate CPL errorthe parallactic angle is missing from the header
propagate CPL errorthe position angle is missing from the header
output warning, use defaults, propagate CPL errors about missing FITS headersthe environmental conditions are missing from header
return CPL_ERROR_INVALID_TYPEpixel table WCS type is neither MUSE_PIXTABLE_WCS_PIXEL nor MUSE_PIXTABLE_WCS_CELSPH

Definition at line 139 of file muse_dar.c.

References muse_pixtable::header, muse_astro_airmass(), muse_astro_parangle(), muse_astro_posangle(), MUSE_HDR_PT_DAR_NAME, MUSE_HDR_PT_PREDAR_XHI, MUSE_HDR_PT_PREDAR_XLO, MUSE_HDR_PT_PREDAR_YHI, MUSE_HDR_PT_PREDAR_YLO, MUSE_HDR_PT_XHI, MUSE_HDR_PT_XLO, MUSE_HDR_PT_YHI, MUSE_HDR_PT_YLO, muse_pfits_get_mode(), muse_pfits_get_pres_end(), muse_pfits_get_pres_start(), muse_pfits_get_rhum(), muse_pfits_get_temp(), muse_phys_nrindex_ciddor(), muse_phys_nrindex_edlen(), muse_phys_nrindex_filippenko(), muse_phys_nrindex_owens(), muse_phys_nrindex_owens_coeffs(), muse_phys_nrindex_owens_saturation_pressure(), muse_pixtable_compute_limits(), muse_pixtable_get_nrow(), MUSE_PIXTABLE_LAMBDA, MUSE_PIXTABLE_WCS_CELSPH, muse_pixtable_wcs_check(), MUSE_PIXTABLE_WCS_PIXEL, MUSE_PIXTABLE_XPOS, MUSE_PIXTABLE_YPOS, muse_wcs_get_scales(), and muse_pixtable::table.

Referenced by muse_postproc_process_exposure().