MUSE Pipeline Reference Manual
2.1.1
|
Data Structures | |
struct | muse_flux_object |
Flux object to store data needed while computing the flux calibration. More... | |
Enumerations |
Functions | |
muse_flux_object * | muse_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... | |
muse_image * | muse_flux_integrate_cube (muse_datacube *aCube, cpl_apertures *aApertures, muse_flux_profile_type aProfile) |
Integrate the flux of the standard star(s) given a datacube. More... | |
cpl_error_code | muse_flux_integrate_std (muse_pixtable *aPixtable, muse_flux_profile_type aProfile, muse_flux_object *aFluxObj) |
Reconstruct a cube, detect the standard star, and integrate its flux. 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... | |
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_compute_qc (muse_flux_object *aFluxObj) |
Compute QC parameters, related to on-sky throughput. More... | |
cpl_error_code | muse_flux_compute_qc_zp (muse_flux_object *aFluxObj, const muse_table *aFilter, const char *aName) |
Compute QC zeropoint for given filter. More... | |
cpl_error_code | muse_flux_calibrate (muse_pixtable *aPixtable, const muse_table *aResponse, const cpl_table *aExtinction, const muse_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... | |
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.
Definition at line 111 of file muse_flux.h.
Type of optimal profile to use.
Definition at line 124 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 136 of file muse_flux.h.
Type of response curve smoothing to use.
Definition at line 146 of file muse_flux.h.
cpl_error_code muse_flux_calibrate | ( | muse_pixtable * | aPixtable, |
const muse_table * | aResponse, | ||
const cpl_table * | aExtinction, | ||
const muse_table * | aTelluric | ||
) |
Convert the input pixel table from counts to fluxes.
aPixtable | the input pixel table containing the exposure to be flux calibrated |
aResponse | the tabulated response curve with header |
aExtinction | the extinction curve |
aTelluric | the telluric correction table with header |
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.
return CPL_ERROR_NULL_INPUT | the input pixel table, its header, or the response table are NULL |
return CPL_ERROR_INCOMPATIBLE_INPUT | the input pixel table data unit is not "count" |
return CPL_ERROR_INCOMPATIBLE_INPUT | the flat-field spectrum correction status between aPixtable and aResponse does not match |
output warning only, but continue | the flat-field spectrum correction status between aPixtable and aTelluric does not match |
output warning, return CPL_ERROR_ILLEGAL_INPUT | the input pixel table data has non-positive exposure time |
output warning and reset airmass to 0. to not do extinction correction | airmass value cannot be determined |
output warning and continue without extinction correction | the extinction curve is missing |
output info message and continue without telluric correction | the telluric correction table is missing |
Definition at line 3083 of file muse_flux.c.
References muse_table::header, muse_pixtable::header, muse_astro_airmass(), MUSE_FLUX_RESP_EXTINCT, MUSE_FLUX_RESP_FLUX, muse_flux_response_interpolate(), MUSE_FLUX_TELLURIC, MUSE_HDR_PT_FFCORR, MUSE_HDR_PT_FLUXCAL, muse_pfits_get_exptime(), muse_pfits_get_pro_catg(), MUSE_PIXTABLE_DATA, muse_pixtable_get_nrow(), MUSE_PIXTABLE_LAMBDA, MUSE_PIXTABLE_STAT, muse_table::table, and muse_pixtable::table.
Referenced by muse_postproc_process_exposure().
cpl_error_code muse_flux_compute_qc | ( | muse_flux_object * | aFluxObj | ) |
Compute QC parameters, related to on-sky throughput.
aFluxObj | MUSE flux object, containing integrated fluxes and the calculated telluric correction |
This uses approximately known parameters of the VLT to compute the throughput of MUSE + VLT + atmosphere using the parameters available in the aFluxObj structure.
If available, the final response curve (aFluxObj->response) is used. Then the QC parameters are also written to the output FITS header of the response. Otherwise, the (unsmoothed) sensitivity function (aFluxObj->sensitivity) is used, and the resulting values are just printed to screen/log. In both cases, a new table column "throughput" is created, or its contents are overwritten, if the column already exists.
The keywords written (if aFluxObj contains the response curve) are QC_STD_THRU for the throughput values and QC_STD_NAME for the name of the standard star (field) that gets transferred from the target name in the cube header.
set and return CPL_ERROR_NULL_INPUT | input flux object both its sensitivity and response components are NULL |
set and return CPL_ERROR_DATA_NOT_FOUND | neither sensitivity nor response->table component could be duplicated |
Definition at line 2858 of file muse_flux.c.
References muse_flux_object::cube, muse_table::header, muse_datacube::header, muse_pfits_get_targname(), muse_flux_object::response, muse_flux_object::sensitivity, and muse_table::table.
Referenced by muse_postproc_process_exposure().
cpl_error_code muse_flux_compute_qc_zp | ( | muse_flux_object * | aFluxObj, |
const muse_table * | aFilter, | ||
const char * | aName | ||
) |
Compute QC zeropoint for given filter.
aFluxObj | MUSE flux object, containing integrated fluxes and the calculated telluric correction |
aFilter | table contining the filter's throughput curve |
aName | the name of the filter |
This function integrates the aFluxObj->reference curve of the standard star over the filter function to compute its magnitude. Then, the final output response (aFluxObj->response, if available) or the unsmoothed sensitivity (aFluxObj->sensitivity) is used to create the measured spectrum of the standard star and integrate this as well. The zeropoint then is the difference between the two:
ZP = m_obs - m_ref = -2.5 log10(F_obs / F_ref)
set and return CPL_ERROR_NULL_INPUT | input flux object both its sensitivity and response components, reference spectrum, aFilter, or its table component are NULL |
set filter name for output FITS keyword to ,UNKNOWN" | but continue" aName is NULL or does not contain an underscore |
Definition at line 2972 of file muse_flux.c.
References muse_table::header, MUSE_FLUX_RESP_FILTER, MUSE_FLUX_RESP_STD_FLUX, muse_flux_response_interpolate(), muse_flux_object::reference, muse_flux_object::response, muse_flux_object::sensitivity, and muse_table::table.
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.
aFluxObj | MUSE flux object, containing integrated fluxes and the calculated response |
aSmooth | MUSE flux object, containing integrated fluxes and the |
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.
If smoothing was applied to the table, the unsmoothed values are tracked in extra table columns (with "_unsmoothed" postfix).
return CPL_ERROR_NULL_INPUT | input flux object or its sensitivity components are NULL |
return CPL_ERROR_ILLEGAL_INPUT | aSmooth is unknown |
Definition at line 2644 of file muse_flux.c.
References muse_flux_object::cube, muse_table::header, muse_datacube::header, muse_cpltable_new(), MUSE_FLUX_SMOOTH_MEDIAN, MUSE_FLUX_SMOOTH_PPOLY, muse_pfits_get_mode(), muse_table_new(), MUSE_WCS_KEYS, muse_flux_object::response, muse_flux_object::sensitivity, and muse_table::table.
Referenced by muse_postproc_process_exposure().
cpl_error_code muse_flux_get_telluric_table | ( | muse_flux_object * | aFluxObj | ) |
Get the table of the telluric correction.
aFluxObj | MUSE flux object, containing integrated fluxes and the calculated telluric correction |
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.
return CPL_ERROR_NULL_INPUT | input flux object or its sensitivity components are NULL |
Definition at line 2752 of file muse_flux.c.
References muse_flux_object::cube, muse_table::header, muse_datacube::header, muse_cpltable_new(), muse_table_new(), MUSE_WCS_KEYS, muse_flux_object::sensitivity, muse_table::table, and muse_flux_object::telluric.
Referenced by muse_postproc_process_exposure().
muse_image* muse_flux_integrate_cube | ( | muse_datacube * | aCube, |
cpl_apertures * | aApertures, | ||
muse_flux_profile_type | aProfile | ||
) |
Integrate the flux of the standard star(s) given a datacube.
aCube | input datacube with the standard star |
aApertures | apertures of detected objects in the cube |
aProfile | the spatial profile to use for flux integration |
Use the input datacube (aCube) and the detections in it (aApertures) to 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, and the three image components are data, data quality, and variance. It also carries a standard spectral WCS in its header component.
set CPL_ERROR_NULL_INPUT, return NULL | inputs aCube or aApertures are NULL |
set CPL_ERROR_ILLEGAL_INPUT, return NULL | the input profile type is unknown |
Definition at line 1009 of file muse_flux.c.
References muse_image::data, muse_datacube::data, muse_image::dq, muse_datacube::dq, muse_datacube::header, muse_image::header, MUSE_FLUX_PROFILE_CIRCLE, MUSE_FLUX_PROFILE_EQUAL_SQUARE, MUSE_FLUX_PROFILE_GAUSSIAN, MUSE_FLUX_PROFILE_MOFFAT, muse_image_new(), muse_pfits_get_bunit(), muse_pfits_get_cd(), muse_pfits_get_crpix(), muse_pfits_get_crval(), muse_pfits_get_ctype(), muse_pfits_get_cunit(), 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_quality_image_reject_using_dq(), muse_wcs_apply_cd(), muse_wcs_celestial_from_pixel(), muse_wcs_create_default(), muse_image::stat, and muse_datacube::stat.
Referenced by muse_flux_integrate_std().
cpl_error_code muse_flux_integrate_std | ( | muse_pixtable * | aPixtable, |
muse_flux_profile_type | aProfile, | ||
muse_flux_object * | aFluxObj | ||
) |
Reconstruct a cube, detect the standard star, and integrate its flux.
aPixtable | the input pixel table of the standard star exposure |
aProfile | the spatial profile to use for flux integration |
aFluxObj | the MUSE flux object to modify with the cube and integrated flux |
Resample the input pixel table to a cube, with wavelength sampling matched to the MUSE spectral sampling. Find objects (lowering the S/N between 50 and 5, in multiple steps) on the central plane of the cube. Create apertures for all detections and integrate their flux in each wavelength. See muse_flux_integrate_cube() for details on the flux integration.
Both the resampled datacube and the flux measurements image are added into the aFluxObj structure (components intimage and cube).
return CPL_ERROR_NULL_INPUT | inputs aPixtable or aFluxObj are NULL |
return CPL_ERROR_ILLEGAL_INPUT | the input profile type is unknown |
return CPL_ERROR_DATA_NOT_FOUND | no objects found |
Definition at line 1362 of file muse_flux.c.
References muse_resampling_params::crsigma, muse_resampling_params::crtype, muse_flux_object::cube, muse_datacube::data, muse_datacube::dq, muse_pixtable::header, muse_flux_object::intimage, muse_datacube_save(), muse_flux_integrate_cube(), MUSE_FLUX_PROFILE_CIRCLE, MUSE_FLUX_PROFILE_EQUAL_SQUARE, MUSE_FLUX_PROFILE_GAUSSIAN, MUSE_FLUX_PROFILE_MOFFAT, muse_pfits_get_mode(), MUSE_PIXTABLE_DQ, muse_pixtable_get_nrow(), 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, and muse_pixtable::table.
Referenced by muse_postproc_process_exposure().
void muse_flux_object_delete | ( | muse_flux_object * | aFluxObj | ) |
Deallocate memory associated to a muse_flux_object.
aFluxObj | input 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_table_delete(), muse_flux_object::reference, 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.
muse_flux_object *
or NULL
on error muse_flux_object_delete()
. *_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.
aTable | the input STD_FLUX_TABLE |
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").
return CPL_ERROR_NULL_INPUT | aTable is NULL |
return CPL_ERROR_INCOMPATIBLE_INPUT | a table with unrecognized format was found |
propagate CPL error | a (table column casting) operation did not work |
Definition at line 170 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 |
Compute average sampling for a MUSE-format flux reference table.
aTable | the STD_FLUX_TABLE |
set CPL_ERROR_NULL_INPUT, return 0. | aTable is NULL |
Definition at line 121 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.
aFluxObj | image containing the standard flux measurements |
aSelect | how to select the standard star |
aAirmass | the corresponding airmass (passing 0.0 is allowed to switch off extinction correction) |
aReference | table containing the reference response for the star |
aTellBands | table containing the telluric band regions (optional) |
aExtinct | the extinction table |
Select the star in aFluxObj->intimage depending on aSelect, to be either the brightest or the nearest integrated object.
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.
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().
return CPL_ERROR_NULL_INPUT | inputs aFluxObj, its intimage component, or aReference table are NULL |
return CPL_ERROR_ILLEGAL_INPUT | aAirmass invalid (< 1.) |
use builtin defaults | aTellBands is NULL |
output warning, but continue, ignoring extinction | extinction table is missing |
Definition at line 2070 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_pfits_get_bunit(), muse_flux_object::raref, muse_flux_object::reference, 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.
aResponse | the response table |
aLambda | wavelength to query |
aError | the error connected to the interpolated datapoint, can be NULL |
aType | interpolation type |
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:
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 338 of file muse_flux.c.
References MUSE_FLUX_RESP_EXTINCT, MUSE_FLUX_RESP_FILTER, MUSE_FLUX_RESP_FLUX, MUSE_FLUX_RESP_STD_FLUX, MUSE_FLUX_TELLURIC, muse_utils_fit_moffat_2d(), and muse_utils_iterate_fit_polynomial().
Referenced by muse_flux_calibrate(), muse_flux_compute_qc_zp(), muse_resampling_collapse_pixgrid(), and muse_utils_filter_fraction().
const muse_cpltable_def muse_flux_responsetable_def[] |
MUSE response table definition.
A MUSE response table has the following columns:
Definition at line 2190 of file muse_flux.c.
const muse_cpltable_def muse_flux_tellurictable_def[] |
MUSE telluric correction table definition.
A MUSE telluric correction table has the following columns:
Definition at line 2211 of file muse_flux.c.