MUSE Pipeline Reference Manual  1.0.2
Data Structures | Enumerations | Functions | Variables
Flux calibration

Data Structures

struct  muse_flux_object
 Flux object to store data needed while computing the flux calibration. More...
 

Enumerations

enum  muse_flux_interpolation_type {
  MUSE_FLUX_RESP_FILTER = 0, MUSE_FLUX_RESP_FLUX, MUSE_FLUX_RESP_STD_FLUX, MUSE_FLUX_RESP_EXTINCT,
  MUSE_FLUX_TELLURIC
}
 Type of table interpolation to use. More...
 
enum  muse_flux_profile_type { MUSE_FLUX_PROFILE_MOFFAT = 0, MUSE_FLUX_PROFILE_GAUSSIAN, MUSE_FLUX_PROFILE_CIRCLE, MUSE_FLUX_PROFILE_EQUAL_SQUARE }
 Type of optimal profile to use. More...
 
enum  muse_flux_selection_type { MUSE_FLUX_SELECT_BRIGHTEST = 0, MUSE_FLUX_SELECT_NEAREST }
 Type of star selection to use. More...
 
enum  muse_flux_smooth_type { MUSE_FLUX_SMOOTH_NONE = 0, MUSE_FLUX_SMOOTH_MEDIAN, MUSE_FLUX_SMOOTH_PPOLY }
 Type of response curve smoothing to use. More...
 

Functions

muse_flux_objectmuse_flux_object_new (void)
 Allocate memory for a new muse_flux_object object. More...
 
void muse_flux_object_delete (muse_flux_object *aFluxObj)
 Deallocate memory associated to a muse_flux_object. More...
 
static double muse_flux_reference_table_sampling (cpl_table *aTable)
 Compute average sampling for a MUSE-format flux reference table. More...
 
cpl_error_code muse_flux_reference_table_check (cpl_table *aTable)
 Check and/or adapt the standard flux reference table format. More...
 
double muse_flux_response_interpolate (const cpl_table *aResponse, double aLambda, double *aError, muse_flux_interpolation_type aType)
 Compute linearly interpolated response of some kind at given wavelength. More...
 
cpl_error_code muse_flux_integrate_std (muse_pixtable *aPixtable, muse_flux_profile_type aProfile, muse_flux_object *aFluxObj)
 Integrate the flux of the standard star(s) in the field over all wavelengths. More...
 
cpl_error_code muse_flux_response_compute (muse_flux_object *aFluxObj, muse_flux_selection_type aSelect, double aAirmass, const cpl_table *aReference, const cpl_table *aTellBands, const cpl_table *aExtinct)
 Compare measured flux distribution over wavelength with calibrated stellar fluxes and derive instrumental sensitivity curve. More...
 
static void muse_flux_get_response_table_smooth (cpl_table *aResp, double aHalfwidth, double aLambdaMin, double aLambdaMax, cpl_boolean aAverage)
 Get the table of the standard star response function. More...
 
cpl_error_code muse_flux_get_response_table (muse_flux_object *aFluxObj, muse_flux_smooth_type aSmooth)
 Get the table of the standard star response function. More...
 
cpl_error_code muse_flux_get_telluric_table (muse_flux_object *aFluxObj)
 Get the table of the telluric correction. More...
 
cpl_error_code muse_flux_calibrate (muse_pixtable *aPixtable, const cpl_table *aResponse, const cpl_table *aExtinction, const cpl_table *aTelluric)
 Convert the input pixel table from counts to fluxes. More...
 

Variables

const muse_cpltable_def muse_response_tellbands_def []
 Table definition for a telluric bands table.
 
const muse_cpltable_def muse_flux_responsetable_def []
 MUSE response table definition. More...
 
const muse_cpltable_def muse_flux_tellurictable_def []
 MUSE telluric correction table definition. More...
 

Detailed Description

Enumeration Type Documentation

Type of table interpolation to use.

There are several types of tables containing something like a "response" curve which contain at least a column "lambda" relevant to the MUSE pipeline. They all have to be interpolated (linearly) in wavelength. Depending on their content they have to be handled in slightly different ways.

Enumerator
MUSE_FLUX_RESP_FILTER 

filter response curve; column response

MUSE_FLUX_RESP_FLUX 

flux response curve; columns response, resperr

MUSE_FLUX_RESP_STD_FLUX 

standard star spectrum; columns flux, fluxerr

MUSE_FLUX_RESP_EXTINCT 

extinction curve; column extinction

MUSE_FLUX_TELLURIC 

telluric correction table: columns ftelluric, ftellerr

Definition at line 96 of file muse_flux.h.

Type of optimal profile to use.

Enumerator
MUSE_FLUX_PROFILE_MOFFAT 

Moffat profile

MUSE_FLUX_PROFILE_GAUSSIAN 

Gaussian profile

MUSE_FLUX_PROFILE_CIRCLE 

circular flux integration, with background annulus

MUSE_FLUX_PROFILE_EQUAL_SQUARE 

simplest version: non-optimal square integration

Definition at line 109 of file muse_flux.h.

Type of star selection to use.

Enumerator
MUSE_FLUX_SELECT_BRIGHTEST 

take the brightest star as standard

MUSE_FLUX_SELECT_NEAREST 

take the nearest source as standard

Definition at line 121 of file muse_flux.h.

Type of response curve smoothing to use.

Enumerator
MUSE_FLUX_SMOOTH_NONE 

no smoothing at all!

MUSE_FLUX_SMOOTH_MEDIAN 

sliding median of +/- 15 Angstrom width

MUSE_FLUX_SMOOTH_PPOLY 

piecewise cubic polynomial plus * median of +/- 15 Angstrom width

Definition at line 131 of file muse_flux.h.

Function Documentation

cpl_error_code muse_flux_calibrate ( muse_pixtable aPixtable,
const cpl_table *  aResponse,
const cpl_table *  aExtinction,
const cpl_table *  aTelluric 
)

Convert the input pixel table from counts to fluxes.

Parameters
aPixtablethe input pixel table containing the exposure to be flux calibrated
aResponsethe tabulated response curve
aExtinctionthe extinction curve
aTelluricthe telluric correction table
Returns
CPL_ERROR_NONE for success, any other cpl_error_code for failure.
Remarks
The resulting correction is directly applied and returned in the input pixel table.
This function adds a FITS header (MUSE_HDR_PT_FLUXCAL) with the boolean value 'T' to the pixel table, for information.

Loop through all pixels in the input pixel table, evaluate the response polynomial at the corresponding wavelength and multiply by the response factor. Treat the variance accordingly. Also multiply by the telluric correction factor, weighted by the airmass, for wavelengths redward of the start of the telluric absorption regions.

Quality Assessment:
Apply the flux calibration to the standard star exposure on which it was derived and compare the reference spectra with the flux-calibrated spectrum of the respective star.
Exceptions
return CPL_ERROR_NULL_INPUTthe input pixel table, its header, or the response table are NULL
return CPL_ERROR_INCOMPATIBLE_INPUTthe input pixel table data unit is not "count"
output warning, return CPL_ERROR_ILLEGAL_INPUTthe input pixel table data has non-positive exposure time
output warning and reset airmass to 0. to not do extinction correctionairmass value cannot be determined
output warning and continue without extinction correctionthe extinction curve is missing
output info message and continue without telluric correctionthe telluric correction table is missing

Definition at line 2568 of file muse_flux.c.

References muse_pixtable::header, muse_astro_airmass(), MUSE_FLUX_RESP_EXTINCT, MUSE_FLUX_RESP_FLUX, muse_flux_response_interpolate(), MUSE_FLUX_TELLURIC, MUSE_HDR_PT_FLUXCAL, muse_pfits_get_exptime(), muse_pixtable_get_nrow(), and muse_pixtable::table.

Referenced by muse_postproc_process_exposure().

cpl_error_code muse_flux_get_response_table ( muse_flux_object aFluxObj,
muse_flux_smooth_type  aSmooth 
)

Get the table of the standard star response function.

Parameters
aFluxObjMUSE flux object, containing integrated fluxes and the calculated response
aSmoothMUSE flux object, containing integrated fluxes and the
Returns
CPL_ERROR_NONE on success, another CPL error code on failure

Copy the response information from the sensitivity table of aFluxObj to a new table, also returned in the input aFluxObj.

To reject outliers, the reponse function is smoothed using either a median with 15 Angstrom halfwidth or a piecewise cubic polynomial followed by a sliding average of 15 Angstrom halfwidth.

For the median filter, the output errorbars are taken as the median absolute deviation in the same region, or the median of all input errorbars, whatever is larger. For the piecewise polynomial, the error of the fit and the standard deviation of the averaging region are propagated onto the original error of each point.

Exceptions
return CPL_ERROR_NULL_INPUTinput flux object or its sensitivity components are NULL
return CPL_ERROR_ILLEGAL_INPUTaSmooth is unknown

Definition at line 2397 of file muse_flux.c.

References muse_cpltable_new(), muse_flux_get_response_table_smooth(), MUSE_FLUX_SMOOTH_MEDIAN, MUSE_FLUX_SMOOTH_PPOLY, muse_flux_object::response, and muse_flux_object::sensitivity.

Referenced by muse_postproc_process_exposure().

static void muse_flux_get_response_table_smooth ( cpl_table *  aResp,
double  aHalfwidth,
double  aLambdaMin,
double  aLambdaMax,
cpl_boolean  aAverage 
)
static

Get the table of the standard star response function.

Parameters
aRespthe MUSE response table to smoothed
aHalfwidththe smoothing halfwidth in Angstrom
aLambdaMinminimum wavelength to work with
aLambdaMaxmaximum wavelength to work with
aAverageuse sliding average instead of sliding median

Compute a sliding median filter with 2 x aHalfwidth size over the data in aResp (columns "response" and "resperr"). Set the output errorbars as the median absolute deviation in the region of the filter width at each point, or the median of all input errorbars, whatever is larger.

If aLambdaMin and/or aLambdaMax are given such that only a subset of the table is smoothed, the smoothing is done symmetrically around each wavelength.

XXX error handling

Definition at line 2078 of file muse_flux.c.

References muse_cplvector_get_adev_const().

Referenced by muse_flux_get_response_table().

cpl_error_code muse_flux_get_telluric_table ( muse_flux_object aFluxObj)

Get the table of the telluric correction.

Parameters
aFluxObjMUSE flux object, containing integrated fluxes and the calculated telluric correction
Returns
CPL_ERROR_NONE on success, another CPL error code on failure

Copy the telluric correction factors from the sensitivity table of aFluxObj to a new table, also returned in the input aFluxObj. Pad telluric regions with extra entries of ftelluric = 1 (for later interpolation), remove all other invalid entries to minimize the size of the returned table.

Note
The table column "ftellerr" currently contains an error that is at most 0.1, smaller than the distance between the telluric correction factor and 1., but 1e-4 as a mininum.
Exceptions
return CPL_ERROR_NULL_INPUTinput flux object or its sensitivity components are NULL

Definition at line 2458 of file muse_flux.c.

References muse_cpltable_new(), muse_flux_object::sensitivity, and muse_flux_object::telluric.

Referenced by muse_postproc_process_exposure().

cpl_error_code muse_flux_integrate_std ( muse_pixtable aPixtable,
muse_flux_profile_type  aProfile,
muse_flux_object aFluxObj 
)

Integrate the flux of the standard star(s) in the field over all wavelengths.

Parameters
aPixtablethe input pixel table of the standard star exposure
aProfilethe spatial profile to use for flux integration
aFluxObjthe MUSE flux object to modify with the cube and integrated flux
Returns
CPL_ERROR_NONE on success, another CPL error code on failure
Remarks
The flux image returned in aFluxObj contains the flux measurements, with the fluxes in the data extension of the muse_image. The stat extension contains the measurement errors for each wavelength and the header element is used to propagate the WCS keywords to define the wavelength scale. Each image row contains the fluxes of one standard star, so that the vertical image size is equal to the measured stars on success.
aProfile can be one of MUSE_FLUX_PROFILE_GAUSSIAN, MUSE_FLUX_PROFILE_MOFFAT, MUSE_FLUX_PROFILE_CIRCLE, and MUSE_FLUX_PROFILE_EQUAL_SQUARE.

Resample the input pixel table to a cube, with wavelength sampling matched to the MUSE spectral sampling. Find objects (with high S/N) on the central plane of the cube. From the small (because high S/N) detection window determine the FWHM of the objects, and use it to define the flux integration window (as three times the FWHM). Integrate the flux of each object for all wavelength bins, using either simple flux integration or profile fitting depending on aProfile. Store the flux measurements in a two-dimensional image, where each row corresponds to one detected object.

Note
The area over which the flux integration is measured, depends on the seeing. For most methods the half-size is at least 3x the measured FWHM at each wavelength. Only for MUSE_FLUX_PROFILE_CIRCLE, it is forced to be 4x the FWHM, where the FWHM is either the measured value or the DIMM seeing from the FITS header, depending on which is larger.

Both the resampled datacube and the flux measurements image are added into the aFluxObj structure (components intimage and cube).

Quality Assessment:
The quality will be checked with the output file of muse_flux_calibrate(), which uses the output of this function and muse_std_derive_response(). The calibration will be applied to the standard star exposure itself and after resampling to a cube the reference spectra and the flux calibrated spectra of the standard stars can be compared.
Exceptions
return CPL_ERROR_NULL_INPUTinputs aPixtable or aFluxObj are NULL
return CPL_ERROR_ILLEGAL_INPUTthe input profile type is unknown
return CPL_ERROR_DATA_NOT_FOUNDno objects found

Definition at line 1020 of file muse_flux.c.

References muse_resampling_params::crsigma, muse_resampling_params::crtype, muse_flux_object::cube, muse_image::data, muse_datacube::data, muse_image::dq, muse_datacube::dq, muse_datacube::header, muse_image::header, muse_flux_object::intimage, muse_datacube_save(), MUSE_FLUX_PROFILE_CIRCLE, MUSE_FLUX_PROFILE_EQUAL_SQUARE, MUSE_FLUX_PROFILE_GAUSSIAN, MUSE_FLUX_PROFILE_MOFFAT, muse_image_new(), muse_pfits_get_dec(), muse_pfits_get_exptime(), muse_pfits_get_fwhm_end(), muse_pfits_get_fwhm_start(), muse_pfits_get_mode(), muse_pfits_get_ra(), muse_pixtable_save(), muse_quality_image_reject_using_dq(), MUSE_RESAMPLE_WEIGHTED_DRIZZLE, MUSE_RESAMPLING_CRSTATS_MEDIAN, muse_resampling_cube(), muse_resampling_params_delete(), muse_resampling_params_new(), muse_wcs_apply_cd(), muse_wcs_celestial_from_pixel(), muse_wcs_create_default(), muse_resampling_params::pfx, muse_image::stat, and muse_datacube::stat.

Referenced by muse_postproc_process_exposure().

void muse_flux_object_delete ( muse_flux_object aFluxObj)

Deallocate memory associated to a muse_flux_object.

Parameters
aFluxObjinput MUSE flux object

Just calls the required *_delete() functions for each component before freeing the memory for the pointer itself. As a safeguard, it checks if a valid pointer was passed, so that crashes cannot occur.

Definition at line 89 of file muse_flux.c.

References muse_flux_object::cube, muse_flux_object::intimage, muse_datacube_delete(), muse_image_delete(), muse_flux_object::response, muse_flux_object::sensitivity, muse_flux_object::tellbands, and muse_flux_object::telluric.

muse_flux_object* muse_flux_object_new ( void  )

Allocate memory for a new muse_flux_object object.

Returns
a new muse_flux_object * or NULL on error
Remarks
The returned object has to be deallocated using muse_flux_object_delete().
This function does not allocate the contents of the elements, these have to be allocated with the respective *_new() functions.

Allocate memory to store the pointers of the muse_flux_object structure. Set the raref and decref components to NAN to signify that they are unset.

Definition at line 68 of file muse_flux.c.

References muse_flux_object::decref, and muse_flux_object::raref.

Referenced by muse_postproc_process_exposure().

cpl_error_code muse_flux_reference_table_check ( cpl_table *  aTable)

Check and/or adapt the standard flux reference table format.

Parameters
aTablethe input STD_FLUX_TABLE
Returns
CPL_ERROR_NONE on successful check or conversion, another cpl_error_code on failure.

We need a table with columns "lambda" and "flux" (and, optionally, "fluxerr") for the standard response calculation. The table columns all need to be in double format, and in the right units ("Angstrom", "erg/s/cm**2/Angstrom"). If the wrong units are used for "lambda" and/or "flux" the table is rejected completely as incompatible, if only "fluxerr" has an unrecognized unit, that column is erased.

Alternatively, we can accept HST CALSPEC tables which basically have the same information, just with different column names ("WAVELENGTH", "FLUX", and "STATERROR" plus "SYSERROR"), using different strings the the same units ("ANGSTROMS", "FLAM").

Note
This function cannot check, if the input table is in vacuum or air wavelengths. But if the input is in HST CALSPEC format, then it assumes that the wavelength given in the "WAVELENGTH" column are in vacuum. It then converts them to air wavelengths using the standard IAU conversion formula.
Exceptions
return CPL_ERROR_NULL_INPUTaTable is NULL
return CPL_ERROR_INCOMPATIBLE_INPUTa table with unrecognized format was found
propagate CPL errora (table column casting) operation did not work

Definition at line 168 of file muse_flux.c.

References muse_astro_wavelength_vacuum_to_air(), and muse_flux_reference_table_sampling().

Referenced by muse_postproc_process_exposure().

static double muse_flux_reference_table_sampling ( cpl_table *  aTable)
static

Compute average sampling for a MUSE-format flux reference table.

Parameters
aTablethe STD_FLUX_TABLE
Returns
The sampling in Angstrom per bin or 0 on error.
Exceptions
set CPL_ERROR_NULL_INPUT, return 0.aTable is NULL

Definition at line 119 of file muse_flux.c.

Referenced by muse_flux_reference_table_check().

cpl_error_code muse_flux_response_compute ( muse_flux_object aFluxObj,
muse_flux_selection_type  aSelect,
double  aAirmass,
const cpl_table *  aReference,
const cpl_table *  aTellBands,
const cpl_table *  aExtinct 
)

Compare measured flux distribution over wavelength with calibrated stellar fluxes and derive instrumental sensitivity curve.

Parameters
aFluxObjimage containing the standard flux measurements
aSelecthow to select the standard star
aAirmassthe corresponding airmass (passing 0.0 is allowed to switch off extinction correction)
aReferencetable containing the reference response for the star
aTellBandstable containing the telluric band regions (optional)
aExtinctthe extinction table
Returns
CPL_ERROR_NONE on success, another CPL error code on failure

Select the star in aFluxObj->intimage depending on aSelect, to be either the brightest or the nearest integrated source.

Note
If aSelect is MUSE_FLUX_SELECT_NEAREST, then aFluxObj->raref and aFluxObj->decref need to be filled (i.e. not NAN) with the coordinates of the real reference source on sky, otherwise MUSE_FLUX_SELECT_BRIGHTEST is assumed.

Compare the measured flux at each wavelength to the reference flux, and scale by airmass, to create the sensitivity function. Questionable entries (those within the telluric regions and outside the wavelength range of the MUSE setup), are marked, the ones outside subsequently removed. The telluric regions are interpolated over (using a 2nd order polynomial) or extrapolated (linearly), and telluric correction factors are computed for these regions, scaled by the airmass of the standard star exposure. The resulting curve is then extrapolated linearly to cover the wavelength range that MUSE can possibly cover with any pixel.

The real result of this function is the sensitivity table that gets added to aFluxObj.

Note
The sensitivity distribution is not smoothed or fit in any way, so it will contain outliers!

The sensitivity table produced here can be converted to the necessary STD_RESPONSE and STD_TELLURIC tables using muse_flux_get_response_table() and muse_flux_get_telluric_table().

Quality Assessment:
The quality will be checked with the output file of muse_flux_calibrate(), which uses the output of this function and muse_flux_integrate_std(). The calibration will be applied to the standard star exposure itself and after resampling to a cube, the reference spectra and the flux-calibrated spectra of the standard stars can be compared.
Exceptions
return CPL_ERROR_NULL_INPUTinputs aFluxObj, its intimage component, or aReference table are NULL
return CPL_ERROR_ILLEGAL_INPUTaAirmass invalid (< 1.)
use builtin defaultsaTellBands is NULL
output warning, but continue, ignoring extinctionextinction table is missing

Definition at line 1930 of file muse_flux.c.

References muse_image::data, muse_flux_object::decref, muse_image::header, muse_flux_object::intimage, muse_astro_angular_distance(), MUSE_FLUX_SELECT_BRIGHTEST, MUSE_FLUX_SELECT_NEAREST, muse_flux_object::raref, and muse_flux_object::sensitivity.

Referenced by muse_postproc_process_exposure().

double muse_flux_response_interpolate ( const cpl_table *  aResponse,
double  aLambda,
double *  aError,
muse_flux_interpolation_type  aType 
)

Compute linearly interpolated response of some kind at given wavelength.

Parameters
aResponsethe response table
aLambdawavelength to query
aErrorthe error connected to the interpolated datapoint, can be NULL
aTypeinterpolation type
Returns
The interpolated response; on error return 0. (1. for aType == MUSE_FLUX_TELLURIC).

This function uses binary search to linearly interpolate a response curve at the correct interval. The response table can be a filter (aType == MUSE_FLUX_RESP_FILTER), a flux response curve (MUSE_FLUX_RESP_FLUX), a standard star spectrum (MUSE_FLUX_RESP_STD_FLUX), an atmospheric extinction curve (MUSE_FLUX_RESP_EXTINCT), or a telluric correction (MUSE_FLUX_TELLURIC).

The table aResponse has to contain at least the column "lambda" (listing the wavelength in Angstroms). The other necessary columns depend on aType:

  • "throughput" (for filter curve, with the relative response for each wavelength),
  • "response" and "resperr" (for flux response curve, the response factor and its error, respectively),
  • "flux" and "fluxerr" (for standard star spectrum, the flux and its error, respectively),
  • "extinction" (for the extinction curve).
  • "ftelluric" and "ftellerr" (for the telluric correction factor and its error, respectively), All columns are expected to be of type CPL_TYPE_DOUBLE.
Exceptions
set CPL_ERROR_NULL_INPUT, return 0. or 1.the input filter is NULL
set CPL_ERROR_UNSUPPORTED_MODE, return 0. or 1.the type is unknown
propagate CPL error, return 0. or 1.the table has less than 1 rows
propagate CPL error, return 0. or 1.the table data could not be returned

Definition at line 336 of file muse_flux.c.

References MUSE_FLUX_RESP_EXTINCT, MUSE_FLUX_RESP_FILTER, MUSE_FLUX_RESP_FLUX, MUSE_FLUX_RESP_STD_FLUX, and MUSE_FLUX_TELLURIC.

Referenced by muse_flux_calibrate(), and muse_resampling_collapse_pixgrid().

Variable Documentation

const muse_cpltable_def muse_flux_responsetable_def[]
Initial value:
= {
{ "lambda", CPL_TYPE_DOUBLE, "Angstrom", "%7.2f", "wavelength", CPL_TRUE },
{ "response", CPL_TYPE_DOUBLE,
"2.5*log10((count/s/Angstrom)/(erg/s/cm**2/Angstrom))", "%.4e",
"instrument response derived from standard star", CPL_TRUE },
{ "resperr", CPL_TYPE_DOUBLE,
"2.5*log10((count/s/Angstrom)/(erg/s/cm**2/Angstrom))", "%.4e",
"instrument response error derived from standard star", CPL_TRUE },
{ NULL, 0, NULL, NULL, NULL, CPL_FALSE }
}

MUSE response table definition.

A MUSE response table has the following columns:

  • 'lambda': the wavelength in Angstrom
  • "response": instrument response derived from standard star
  • "resperr": instrument response error derived from standard star

Definition at line 2027 of file muse_flux.c.

const muse_cpltable_def muse_flux_tellurictable_def[]
Initial value:
= {
{ "lambda", CPL_TYPE_DOUBLE, "Angstrom", "%7.2f", "wavelength", CPL_TRUE },
{ "ftelluric", CPL_TYPE_DOUBLE, "", "%.5f",
"the telluric correction factor, normalized to an airmass of 1", CPL_TRUE },
{ "ftellerr", CPL_TYPE_DOUBLE, "", "%.5f",
"the error of the telluric correction factor", CPL_TRUE },
{ NULL, 0, NULL, NULL, NULL, CPL_FALSE }
}

MUSE telluric correction table definition.

A MUSE telluric correction table has the following columns:

  • 'lambda': the wavelength in Angstrom
  • "ftelluric": the telluric correction factor, normalized to an airmass of 1
  • "ftellerr": the error of the telluric correction factor

Definition at line 2048 of file muse_flux.c.