MUSE Pipeline Reference Manual  0.18.5
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...
 

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, 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 (muse_flux_object *aFluxObj, cpl_table *aResp, double aHalfwidth)
 Get the table of the standard star response function. More...
 
cpl_error_code muse_flux_get_response_table (muse_flux_object *aFluxObj)
 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 84 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 97 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 2161 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)

Get the table of the standard star response function.

Parameters
aFluxObjMUSE flux object, containing integrated fluxes and the calculated response
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 a median with 15 Angstrom halfwidth. The output errorbars are taken as the median absolute deviation in the same region, or the median of all input errorbars, whatever is larger.

Exceptions
return CPL_ERROR_NULL_INPUTinput flux object or its sensitivity components are NULL

Definition at line 2009 of file muse_flux.c.

References muse_cpltable_new(), and muse_flux_get_response_table_smooth().

Referenced by muse_postproc_process_exposure().

static void muse_flux_get_response_table_smooth ( muse_flux_object aFluxObj,
cpl_table *  aResp,
double  aHalfwidth 
)
static

Get the table of the standard star response function.

Parameters
aFluxObjMUSE flux object, containing the sensitivity curve
aRespthe MUSE response table to be filled by smoothing
aHalfwidththe smoothing halfwidth in Angstrom

Compute a sliding median filter with 2 x aHalfwidth size over the data in aFluxObj->sensitivity (columns "sens" and "serr"). The smoothed output data is stored in aResp, in 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.

XXX error handling

Definition at line 1947 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 2051 of file muse_flux.c.

References muse_cpltable_new().

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 1006 of file muse_flux.c.

References muse_resampling_params::crsigma, muse_resampling_params::crtype, muse_image::data, muse_datacube::data, muse_image::dq, muse_datacube::dq, muse_datacube::header, muse_image::header, muse_datacube_save(), MUSE_FLUX_PROFILE_CIRCLE, MUSE_FLUX_PROFILE_EQUAL_SQUARE, MUSE_FLUX_PROFILE_GAUSSIAN, MUSE_FLUX_PROFILE_MOFFAT, muse_image_new(), muse_image_save(), muse_pfits_get_exptime(), muse_pfits_get_fwhm_end(), muse_pfits_get_fwhm_start(), muse_pfits_get_mode(), 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_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 84 of file muse_flux.c.

References muse_datacube_delete(), and muse_image_delete().

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.

Simply allocate memory to store the pointers of the muse_flux_object structure.

Definition at line 66 of file muse_flux.c.

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").

XXX This function cannot check, if the input table is in vacuum or air wavelengths, and makes not effort to convert it. But the pipeline in principle needs air wavelengths for the atmospheric properties inside the spectrograph.

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 162 of file muse_flux.c.

References 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 114 of file muse_flux.c.

Referenced by muse_flux_reference_table_check().

cpl_error_code muse_flux_response_compute ( muse_flux_object aFluxObj,
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
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

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 1833 of file muse_flux.c.

References muse_image::data.

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 322 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 1900 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 1921 of file muse_flux.c.