MUSE Pipeline Reference Manual  2.1.1
Data Structures | Functions
Basic-processing function

Data Structures

struct  muse_basicproc_params
 Structure of basic processing parameters. More...
 

Functions

muse_basicproc_paramsmuse_basicproc_params_new (cpl_parameterlist *aParameters, const char *aPrefix)
 Create a new structure of basic processing parameters. More...
 
muse_basicproc_paramsmuse_basicproc_params_new_from_propertylist (const cpl_propertylist *aHeader)
 Create a structure of basic processing parameters from a FITS header. More...
 
void muse_basicproc_params_delete (muse_basicproc_params *aBPars)
 Free a structure of basic processing parameters. More...
 
muse_imagelistmuse_basicproc_load (muse_processing *aProcessing, unsigned char aIFU, muse_basicproc_params *aBPars)
 Load the raw input files from disk and do basic processing. More...
 
muse_imagelistmuse_basicproc_load_reduced (muse_processing *aProcessing, unsigned char aIFU)
 Load reduced input files from disk. More...
 
cpl_table * muse_basicproc_get_illum (muse_imagelist *aImages, cpl_table *aTrace, cpl_table *aWave, cpl_table *aGeo)
 Get an illum/attached flat-field from an imagelist and prepare it for use. More...
 
cpl_error_code muse_basicproc_apply_illum (muse_pixtable *aPT, cpl_table *aAttached)
 Apply an illum/attached flat-field to a pixel table. More...
 
cpl_error_code muse_basicproc_apply_twilight (muse_pixtable *aPT, muse_datacube *aTwilight)
 Apply an attached flat-field to a pixel table. More...
 
cpl_error_code muse_basicproc_mask_notch_filter (muse_pixtable *aPT, unsigned char aIFU)
 Mask the range of the NaD notch filter in the given pixel table. More...
 
muse_imagelistmuse_basicproc_combine_images_lampwise (muse_processing *aProcessing, unsigned char aIFU, muse_basicproc_params *aBPars, cpl_frameset ***aLabeledFrames)
 Combine several images into a lampwise image list. More...
 
cpl_error_code muse_basicproc_shift_pixtable (muse_pixtable *aPt, cpl_array *aLines, double aHalfWidth, double aBinWidth, float aLo, float aHi, unsigned char aIter)
 Compute wavelength corrections for science data based on reference sky lines. More...
 
cpl_error_code muse_basicproc_stats_append_header (cpl_image *aImage, cpl_propertylist *aHeader, const char *aPrefix, unsigned aStats)
 Compute image statistics of an image and add them to a header. More...
 
cpl_error_code muse_basicproc_stats_append_header_window (cpl_image *aImage, cpl_propertylist *aHeader, const char *aPrefix, unsigned aStats, int aX1, int aY1, int aX2, int aY2)
 Compute image statistics of an image window and add them to a header. More...
 
cpl_error_code muse_basicproc_qc_saturated (muse_image *aImage, const char *aPrefix)
 Add QC parameter about saturated pixels to a muse_image. More...
 

Detailed Description

This group contains functions that are common to some basic-processing recipes.

Function Documentation

cpl_error_code muse_basicproc_apply_illum ( muse_pixtable aPT,
cpl_table *  aAttached 
)

Apply an illum/attached flat-field to a pixel table.

Parameters
aPTthe pixel table
aAttachedthe table computed from the attached flat
Returns
CPL_ERROR_NONE on success or a CPL error code on failure

This function expects the attached flat-field to be in form of a table, in the format created by muse_basicproc_prepare_attached().

Exceptions
set and return CPL_ERROR_NULL_INPUTaPT, one of it's components, or aAttached are NULL

Definition at line 1842 of file muse_basicproc.c.

References muse_pixtable::header, MUSE_HDR_PT_ILLUM_MEAN, MUSE_HDR_PT_ILLUM_STDEV, MUSE_HDR_PT_ILLUMi, MUSE_PIXTABLE_DATA, muse_pixtable_extracted_delete(), muse_pixtable_extracted_get_size(), muse_pixtable_extracted_get_slices(), MUSE_PIXTABLE_ORIGIN, muse_pixtable_origin_get_slice(), MUSE_PIXTABLE_STAT, muse_utils_get_ifu(), and muse_pixtable::table.

cpl_error_code muse_basicproc_apply_twilight ( muse_pixtable aPT,
muse_datacube aTwilight 
)

Apply an attached flat-field to a pixel table.

Parameters
aPTthe pixel table
aTwilightthe cube of the twilight skyflat exposure
Returns
CPL_ERROR_NONE on success or a CPL error code on failure

This function applies the twilight-sky based illumination correction using a cube of the skyflat prepared by the muse_twilight recipe.

Spatially, the geometry-table based spatial pixel coordinates are used to find the nearest neighbor. In dispersion direction, the (up to two pixels) in the nearest wavelength plane(s) are interpolated linearly.

Exceptions
set and return CPL_ERROR_NULL_INPUTaPT, one of it's components, or aAttached are NULL

Definition at line 1901 of file muse_basicproc.c.

References muse_datacube::data, muse_datacube::header, muse_pixtable::header, muse_pfits_get_cd(), muse_pfits_get_crpix(), muse_pfits_get_crval(), MUSE_PIXTABLE_DATA, muse_pixtable_get_nrow(), MUSE_PIXTABLE_LAMBDA, MUSE_PIXTABLE_STAT, MUSE_PIXTABLE_XPOS, MUSE_PIXTABLE_YPOS, muse_utils_get_ifu(), and muse_pixtable::table.

muse_imagelist* muse_basicproc_combine_images_lampwise ( muse_processing aProcessing,
unsigned char  aIFU,
muse_basicproc_params aBPars,
cpl_frameset ***  aLabeledFrames 
)

Combine several images into a lampwise image list.

Parameters
aProcessingthe processing structure
aIFUthe IFU/channel number
aBParsbasic processing parameters
aLabeledFramesoptional output array of framesets containing used frames for each lamp
Returns
the list as a muse_imagelist * or NULL on error

Combine several images into one, using method and parameters specified by aProcessing->parameters. Note that this function changes the input images if the "scale" option is used. If all images are found to be of the same lamp, they are all combined into a single output image, which is the only entry in the returned image list.

If aLabeledFrames is not NULL, it will contain a list of framesets or the same size as the returned imagelist. Each frameset contains the frames that were used to preprocess the image at the same index in the image list, and has to be deallocated using cpl_frameset_delete(). The returned pointer has to be deallocated with cpl_free(). The returned pointer will be NULL on error.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaProcessing is NULL
call muse_basicproc_load() with NULL parameteraBPars is NULL
propagate error code, return NULLimage combination failed

Definition at line 2205 of file muse_basicproc.c.

References muse_image::header, muse_processing::inframes, muse_processing::intags, muse_basicproc_load(), muse_combine_images(), muse_combinepar_delete(), muse_combinepar_new(), muse_frameset_find_tags(), muse_imagelist_delete(), muse_imagelist_get(), muse_imagelist_get_size(), muse_imagelist_new(), muse_imagelist_set(), muse_processing::name, muse_processing::parameters, and muse_processing::usedframes.

cpl_table* muse_basicproc_get_illum ( muse_imagelist aImages,
cpl_table *  aTrace,
cpl_table *  aWave,
cpl_table *  aGeo 
)

Get an illum/attached flat-field from an imagelist and prepare it for use.

Parameters
aImagesimage list to search for
aTracetrace table
aWavewavelength calibration table
aGeogeometry table
Returns
the prepared CPL table or NULL on failure

This function finds and erases all attached flat-fields or illumination flat-fields from the input image lists. The first ILLUM found is then converted to a table that can be used by muse_basicproc_apply_illum() to correct a pixel table of a science exposure by the actual illumination.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLone of the input pointers is NULL

Definition at line 1759 of file muse_basicproc.c.

References muse_image::header, muse_image_delete(), muse_imagelist_get(), muse_imagelist_get_size(), muse_imagelist_unset(), muse_pixtable_create(), muse_pixtable_delete(), and muse_utils_get_ifu().

muse_imagelist* muse_basicproc_load ( muse_processing aProcessing,
unsigned char  aIFU,
muse_basicproc_params aBPars 
)

Load the raw input files from disk and do basic processing.

Parameters
aProcessingthe processing structure
aIFUthe IFU/channel number
aBParsbasic processing parameters
Returns
the muse_imagelist * or NULL on error

Read the raw input files from disk and store them as images in the images structure. Apply bad pixel table, bias, dark, and flat files to them, thereby adding two images with bad pixel information and variance to each of them, so that they are all of format muse_image. Saturated pixels are added to the bad pixel extension of every image.

For raw bias exposures, the overscan levels are checked against the first input file. A mean overscan level is then added to the header of the first image to be propagated into the final combined master bias.

For raw flat-field exposures, the gain is estimated from the data and compared to the one listed in the input FITS header.

The necessary calibrations for each step are loaded as required.

Exceptions
propagate error from muse_processing_check_input(), return NULLinput data is invalid somehow (NULL aProcessing pointer etc.)
set an error code, return NULLraw images could not be loaded
reset errors and continueapplying the bad pixel table failed
set a cpl_error_code, return NULLsaturation check failed
set a cpl_error_code, return NULLcorrecting quadrants by overscan fitting failed
set a cpl_error_code, return NULLcomputing overscan statistics and rejecting cosmic rays in overscans failed
set a cpl_error_code, return NULLimages could not be trimmed
output warning and continueoverscan correction was requested but failed
set a cpl_error_code, return NULLoverscan check failed
set a cpl_error_code, return NULLapplying bias failed
ignore errors and continuechecking gain failed
set a cpl_error_code, return NULLcoversion from adu to count failed
set a cpl_error_code, return NULLapplying dark failed
set a cpl_error_code, return NULLcarrying out cr rejection failed
set a cpl_error_code, return NULLapplying simple sky subtraction failed
set a cpl_error_code, return NULLapplying flat failed

Definition at line 1572 of file muse_basicproc.c.

References muse_imagelist_delete(), and muse_processing_check_input().

Referenced by muse_basicproc_combine_images_lampwise().

muse_imagelist* muse_basicproc_load_reduced ( muse_processing aProcessing,
unsigned char  aIFU 
)

Load reduced input files from disk.

Parameters
aProcessingthe processing structure
aIFUthe IFU/channel number
Returns
the muse_imagelist * or NULL on error

Read the reduced input files from disk and store them as images in the images structure.

Exceptions
propagate error from muse_processing_check_input(), return NULLinput data is invalid somehow (NULL aProcessing pointer etc.)

Definition at line 1662 of file muse_basicproc.c.

References muse_pixtable::header, muse_processing::inframes, muse_processing::intags, muse_frameset_find_tags(), muse_image_load(), muse_image_load_from_extensions(), muse_imagelist_new(), muse_imagelist_set(), MUSE_PIXTABLE_DATA, muse_pixtable_extracted_delete(), muse_pixtable_extracted_get_size(), muse_pixtable_extracted_get_slices(), MUSE_PIXTABLE_ORIGIN, muse_pixtable_origin_get_slice(), muse_pixtable_restrict_wavelength(), muse_processing_append_used(), muse_utils_get_ifu(), and muse_pixtable::table.

cpl_error_code muse_basicproc_mask_notch_filter ( muse_pixtable aPT,
unsigned char  aIFU 
)

Mask the range of the NaD notch filter in the given pixel table.

Parameters
aPTthe pixel table to mask the range in
aIFUthe IFU number (for output)
Returns
CPL_ERROR_NONE on success, and another CPL error code on failure.

This function selects the range of wavelengths inside the notch filter (given by kMuseNa2LambdaMin and kMuseNa2LambdaMax) and sets the DQ entries to EURO3D_MISSDATA.

The function returns without clearing the table row selection.

Exceptions
set and return CPL_ERROR_NULL_INPUTaPT or one of its components is NULL
set and return CPL_ERROR_ILLEGAL_INPUTinstrument mode without notch filter found

Definition at line 2050 of file muse_basicproc.c.

References muse_pixtable::header, muse_pfits_get_insmode(), muse_pfits_get_lamp_name(), muse_pfits_get_lamp_status(), muse_pfits_get_mode(), muse_pfits_get_shut_name(), muse_pfits_get_shut_status(), MUSE_PIXTABLE_DQ, MUSE_PIXTABLE_LAMBDA, and muse_pixtable::table.

void muse_basicproc_params_delete ( muse_basicproc_params aBPars)

Free a structure of basic processing parameters.

Parameters
aBParsthe structure of basic processing parameters

This deallocates the string and muse_image components and the structure itself.

Definition at line 169 of file muse_basicproc.c.

References muse_basicproc_params::crmethod, muse_image::data, muse_basicproc_params::dcrpasses, muse_basicproc_params::dcrthres, muse_basicproc_params::dcrxbox, muse_basicproc_params::dcrybox, muse_image::dq, muse_basicproc_params::flatimage, muse_image::header, muse_processing::inframes, muse_processing::intags, muse_basicproc_params::keepflat, muse_badpix_table_def, muse_basicproc_params_delete(), muse_basicproc_params_new_from_propertylist(), muse_cosmics_dcr(), muse_cpltable_load(), muse_frameset_check_raw(), muse_frameset_find(), muse_frameset_find_master(), muse_image_adu_to_count(), muse_image_delete(), muse_image_divide(), muse_image_duplicate(), muse_image_load(), muse_image_load_from_extensions(), muse_image_load_from_raw(), muse_image_save(), muse_image_scale(), muse_image_subtract(), muse_image_variance_create(), muse_imagelist_delete(), muse_imagelist_get(), muse_imagelist_get_size(), muse_imagelist_is_uniform(), muse_imagelist_new(), muse_imagelist_set(), muse_pfits_get_binx(), muse_pfits_get_biny(), muse_pfits_get_chip_id(), muse_pfits_get_chip_name(), muse_pfits_get_exptime(), muse_pfits_get_gain(), muse_pfits_get_insmode(), muse_pfits_get_mode(), muse_pfits_get_pro_catg(), muse_pfits_get_read_id(), muse_pfits_get_read_name(), muse_processing_append_used(), muse_processing_check_intags(), muse_quadrants_get_window(), muse_quadrants_overscan_check(), muse_quadrants_overscan_correct(), muse_quadrants_overscan_polyfit_vertical(), muse_quadrants_overscan_stats(), muse_quadrants_trim_image(), muse_quality_set_saturated(), muse_utils_get_extension_for_ifu(), muse_utils_get_ifu(), muse_basicproc_params::overscan, muse_basicproc_params::ovscignore, muse_basicproc_params::ovscsigma, muse_basicproc_params::rejection, muse_imagelist::size, and muse_image::stat.

Referenced by muse_basicproc_params_delete().

muse_basicproc_params* muse_basicproc_params_new ( cpl_parameterlist *  aParameters,
const char *  aPrefix 
)

Create a new structure of basic processing parameters.

Parameters
aParametersthe list of parameters
aPrefixthe prefix of the recipe
Returns
The basic processing parameters as muse_basicproc_params or NULL on error.

Create a new set of basic processing parameters from a recipe parameter list. It takes the parameters "overscan", "ovscreject", "ovscsigma", and "ovscignore" and converts them into the structure. If aPrefix contains "muse_scibasic", it also takes the parameters "cr", "xbox", "ybox", "passes", and "thres".

The error handling is done by the cpl_parameterlist functions that this function calls.

The component "keepflat" is set to false, so that by default the flat-field image is not stored in the "flatimage" component.

Use muse_basicproc_params_delete() to free memory allocated by this function.

Definition at line 85 of file muse_basicproc.c.

References muse_basicproc_params::crmethod, muse_basicproc_params::dcrpasses, muse_basicproc_params::dcrthres, muse_basicproc_params::dcrxbox, muse_basicproc_params::dcrybox, muse_cplparamerterlist_find_prefix(), muse_basicproc_params::overscan, muse_basicproc_params::ovscignore, muse_basicproc_params::ovscsigma, and muse_basicproc_params::rejection.

Referenced by muse_basicproc_params_new_from_propertylist().

muse_basicproc_params* muse_basicproc_params_new_from_propertylist ( const cpl_propertylist *  aHeader)

Create a structure of basic processing parameters from a FITS header.

Parameters
aHeaderthe FITS header
Returns
The basic processing parameters as muse_basicproc_params or NULL on error.

This creates a new parameter list from the ESO.PRO.REC1 keywords present in the input FITS header, and then gives the result to muse_basicproc_params_new() to actually create the output structure.

Note
This only works, if the input header is that of a product produced by the MUSE pipeline.

Use muse_basicproc_params_delete() to free memory allocated by this function.

Definition at line 143 of file muse_basicproc.c.

References muse_basicproc_params_new(), and muse_cplparameterlist_from_propertylist().

Referenced by muse_basicproc_params_delete().

cpl_error_code muse_basicproc_qc_saturated ( muse_image aImage,
const char *  aPrefix 
)

Add QC parameter about saturated pixels to a muse_image.

Parameters
aImagethe image to count on and modify
aPrefixprefix of the QC header
Returns
CPL_ERROR_NONE on success, another CPL error code on failure.

Count EURO3D_SATURATED pixels in the dq component of aImage and add a aPrefix+QC_BASIC_NSATURATED (if aPrefix does not contain a trailing space, one is added in between) keyword to its header component.

Exceptions
return CPL_ERROR_NULL_INPUTaImage or its dq or header components, or aPrefix are NULL
propagate error codekeyword updating failed

Definition at line 2545 of file muse_basicproc.c.

References muse_image::dq, and muse_image::header.

cpl_error_code muse_basicproc_shift_pixtable ( muse_pixtable aPt,
cpl_array *  aLines,
double  aHalfWidth,
double  aBinWidth,
float  aLo,
float  aHi,
unsigned char  aIter 
)

Compute wavelength corrections for science data based on reference sky lines.

Parameters
aPtthe pixel table with the science data
aLinesarray with the reference wavelengths of sky emission lines
aHalfWidthhalf-width of the wavelength region around each sky line
aBinWidthpixel size in Angstrom of the intermediate spectrum
aLolow sigma-clipping limit for the intermediate spectrum
aHihigh sigma-clipping limit for the intermediate spectrum
aIternumber of iterations for sigma-clipping the spectrum
Returns
CPL_ERROR_NONE on success or another CPL error code on failure

This function subsequently calls muse_utils_pixtable_fit_line_gaussian() for all sky lines given in aLines. It computes a weighted mean offset and applies this shift in wavelength to the data in aPt.

The input array aLines needs to be of simple floating-point type.

Exceptions
return CPL_ERROR_NULL_INPUTaPt and/or aLines are NULL
return CPL_ERROR_ILLEGAL_INPUTaLines is not of floating-point type

Definition at line 2390 of file muse_basicproc.c.

References muse_pixtable::header, MUSE_HDR_PT_LHI, MUSE_HDR_PT_LLO, MUSE_PIXTABLE_LAMBDA, muse_utils_get_ifu(), muse_utils_pixtable_fit_line_gaussian(), and muse_pixtable::table.

cpl_error_code muse_basicproc_stats_append_header ( cpl_image *  aImage,
cpl_propertylist *  aHeader,
const char *  aPrefix,
unsigned  aStats 
)

Compute image statistics of an image and add them to a header.

Parameters
aImagethe image to derive statistics for and add them to
aHeaderthe header to add them to
aPrefixthe prefix of the output FITS keywords
aStatsthe statistics properties to compute
Returns
a CPL error code on failure or CPL_ERROR_NONE on success

This function only supports a subset of the properties supported by cpl_stats_new_from_image(), see muse_basicproc_stats_append_header_window().

Definition at line 2451 of file muse_basicproc.c.

References muse_basicproc_stats_append_header_window().

cpl_error_code muse_basicproc_stats_append_header_window ( cpl_image *  aImage,
cpl_propertylist *  aHeader,
const char *  aPrefix,
unsigned  aStats,
int  aX1,
int  aY1,
int  aX2,
int  aY2 
)

Compute image statistics of an image window and add them to a header.

Parameters
aImagethe image to derive statistics for and add them to
aHeaderthe header to add them to
aPrefixthe prefix of the output FITS keywords
aStatsthe statistics properties to compute
aX1the lower left x-coordinate of the window
aY1the lower left y-coordinate of the window
aX2the upper right x-coordinate of the window
aY2the upper right y-coordinate of the window
Returns
a CPL error code on failure or CPL_ERROR_NONE on success

This function only supports a subset of the properties supported by cpl_stats_new_from_image_window(), namely median, mean, stdev, min, max, and flux,

Definition at line 2481 of file muse_basicproc.c.

Referenced by muse_basicproc_stats_append_header().