MUSE Pipeline Reference Manual  2.1.1
Enumerations | Functions
Xposure combination

Enumerations

Functions

cpl_error_code muse_xcombine_weights (muse_pixtable **aPixtables, muse_xcombine_types aWeighting)
 compute the weights for combination of two or more exposures More...
 
double * muse_xcombine_find_offsets (const cpl_table *aOffsets, const char *aDateObs)
 Get offsets and scale from table row with matching DATE-OBS entry. More...
 
muse_pixtablemuse_xcombine_tables (muse_pixtable **aPixtables, const cpl_table *aOffsets)
 combine the pixel tables of several exposures into one More...
 

Detailed Description

Enumeration Type Documentation

Xposure combination types.

Enumerator
MUSE_XCOMBINE_EXPTIME 

weight exposures by exposure time

MUSE_XCOMBINE_FWHM 

weight exposures by fwhm (and exposure time)

MUSE_XCOMBINE_NONE 

do not weight exposures at all

Definition at line 44 of file muse_xcombine.h.

Function Documentation

double* muse_xcombine_find_offsets ( const cpl_table *  aOffsets,
const char *  aDateObs 
)

Get offsets and scale from table row with matching DATE-OBS entry.

Parameters
aOffsetstable with coordinate offsets to apply
aDateObsthe DATE-OBS string to compare
Returns
a three-element double array, with the two coordinate offsets or NULL on error
Note
The returned pointer has to be deallocated with cpl_free() after use.
By default (if the optional MUSE_OFFSETS_FSCALE column does not exist) or on error, the third element of the returned array is NAN, so that no flux scaling occurs (when applying the output of this function to a pixel table).
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaOffsets and/or aDateObs are NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLaDateObs has a length of less than 19 or more than 68 characters
set NAN for each invalid value, output a warningthe value(s) in the columns MUSE_OFFSETS_DRA and/or MUSE_OFFSETS_DDEC could not be read
no error is raised, just return NULLan entry with aDateObs is not found in aOffsets

Definition at line 334 of file muse_xcombine.c.

Referenced by muse_xcombine_tables().

muse_pixtable* muse_xcombine_tables ( muse_pixtable **  aPixtables,
const cpl_table *  aOffsets 
)

combine the pixel tables of several exposures into one

Parameters
aPixtablesthe NULL-terminated array of pixel tables to combine
aOffsetsa table with coordinate offsets to apply (optional, can be NULL)
Returns
a muse_pixtable * with the combined pixel table of all exposures or NULL on error
Remarks
The FITS headers as passed to this function through the muse_pixtable objects are assumed to contain accurate on-sky positional information (RA and DEC).
The input pixel tables needs to contain a column with weights; otherwise all exposures will be weighted equally when resampling later.
To get an actual combined datacube, run one of the muse_resampling_<format> functions on the output data of this function.
Warning
Do not re-order the output table, otherwise the exposure ranges in the pixel table headers are out of sync!
Remarks
This function adds a FITS header (MUSE_HDR_PT_COMBINED) with the number of combined exposures, for information.

Determine offsets from input FITS headers, loop through all pixel tables, position them to the RA,DEC in their headers using muse_wcs_position_celestial(), and append the small pixel tables to the end of the output pixel table. All used input pixel tables are deleted in this function, only the input pointer remains.

The behavior of this function can be tweaked using the second argument, a table listing offsets in RA and DEC for a given DATE-OBS. This can be used to align exposures with different relative offsets not reflected in the RA and DEC headers. If this is done, the header keywords MUSE_HDR_OFFSETi_DATEOBS, MUSE_HDR_OFFSETi_DRA, and MUSE_HDR_OFFSETi_DDEC are written to the header of the output pixel table, to show which RA and DEC offsets were applied to the exposure of which DATE-OBS.

Similarly, if aOffsets contains a column MUSE_OFFSETS_FSCALE, the values are interpreted as scaling factors to apply to the given exposure before inserting into the big pixel table. If flux scales are applied, they are stored in a keyword MUSE_HDR_FLUX_SCALEi.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaPixtables is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLthere are less than 2 input pixel tables
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLfirst pixel table was not projected to native spherical coordinates
output warningfirst pixel table was not radial-velocity corrected
skip this pixel tableother pixel tables were not projected to native spherical coordinates
output warninganother pixel table was not radial-velocity corrected

Definition at line 435 of file muse_xcombine.c.

References muse_pixtable::header, MUSE_HDR_PT_COMBINED, MUSE_HDR_PT_EXP_FST, MUSE_HDR_PT_EXP_LST, muse_pfits_get_dateobs(), muse_pfits_get_dec(), muse_pfits_get_ra(), muse_pixtable_compute_limits(), muse_pixtable_delete(), muse_pixtable_flux_multiply(), muse_pixtable_get_nrow(), muse_pixtable_is_rvcorr(), muse_pixtable_origin_copy_offsets(), muse_pixtable_wcs_check(), MUSE_PIXTABLE_WCS_NATSPH, MUSE_PIXTABLE_XPOS, MUSE_PIXTABLE_YPOS, muse_utils_memory_dump(), muse_wcs_position_celestial(), muse_xcombine_find_offsets(), and muse_pixtable::table.

cpl_error_code muse_xcombine_weights ( muse_pixtable **  aPixtables,
muse_xcombine_types  aWeighting 
)

compute the weights for combination of two or more exposures

Parameters
aPixtablesthe NULL-terminated array of pixel tables to weight
aWeightingthe weighting scheme to use
Returns
CPL_ERROR_NONE on success any other value on failure
Remarks
The weights are applied to the input pixel tables, adding another column. If a table column MUSE_PIXTABLE_WEIGHT already exists, the values it contains are overwritten.
This function adds a FITS header (MUSE_HDR_PT_WEIGHTED) with the boolean value 'T' to the pixel table, for information.

For exposure time weighting (aWeighting == MUSE_XCOMBINE_EXPTIME), compute the ratio of the exposure time of the current exposure with the one from the first exposure, and store this ratio as weight in a new table column. For FWHM-based weighting (aWeighting == MUSE_XCOMBINE_FWHM), use the DIMM seeing information, and multiply the FWHM ratio by the exposure-weight to form the final weight.

If aWeighting is MUSE_XCOMBINE_NONE, this function only checks for valid inputs, but then returns without doing anything.

Exceptions
return CPL_ERROR_NULL_INPUTaPixtables is NULL
return CPL_ERROR_ILLEGAL_INPUTthere are less than 2 input pixel tables
output warning and return CPL_ERROR_UNSUPPORTED_MODEan unknown weighting scheme was given
return CPL_ERROR_INCOMPATIBLE_INPUTEXPTIME is not set in the header of the first pixel table
weights for these tables are set to zerothe exposure time header is missing from one or more input pixel tables
output warning and set CPL_ERROR_DATA_NOT_FOUND, switch to EXPTIME-weighting, but return CPL_ERROR_NONEall FWHM header entries are missing from one or more input pixel tables although MUSE_XCOMBINE_FWHM is requrested

Definition at line 205 of file muse_xcombine.c.

References MUSE_HDR_PT_WEIGHTED, muse_pixtable_get_nrow(), MUSE_PIXTABLE_WEIGHT, MUSE_XCOMBINE_EXPTIME, MUSE_XCOMBINE_FWHM, and MUSE_XCOMBINE_NONE.