Utilities

Data Structures

struct  muse_mask
 Handling of "mask" files. More...
struct  muse_cpl_optimize_control_t
 Optimization control parameters. More...

Typedefs

typedef cpl_error_code( muse_cpl_evaluate_func )(void *aData, cpl_array *aPar, cpl_array *aRetval)
 User provided function to evaluate in muse_cpl_optimize_lvmq().

Enumerations

enum  muse_utils_centroid_type { MUSE_UTILS_CENTROID_NORMAL = 0, MUSE_UTILS_CENTROID_MEAN, MUSE_UTILS_CENTROID_MEDIAN }
 

Background handling when computing centroids.

More...

Functions

muse_maskmuse_mask_new (void)
 Allocate memory for a new muse object.
void muse_mask_delete (muse_mask *aMask)
 Deallocate memory associated to a muse_mask object.
muse_maskmuse_mask_load (const char *aFilename)
 Load a mask file and its FITS header.
cpl_error_code muse_mask_save (muse_mask *aMask, const char *aFilename)
 Save the data and the FITS headers of a MUSE mask to a file.
static void muse_cpl_optimize_print (const char *func, int n_par, double *par, int m_dat, double *fvec, void *data, int iflag, int iter, int nfev)
 Default printout method adopted to CPL.
cpl_error_code muse_cpl_optimize_lvmq (void *aData, cpl_array *aPar, int aSize, muse_cpl_evaluate_func *aFunction, muse_cpl_optimize_control_t *aCtrl)
 Minimize a function with the Levenberg-Marquardt algorithm.
const char * muse_get_license (void)
 Get the pipeline copyright and license.
unsigned char muse_utils_get_ifu (const cpl_propertylist *aHeaders)
 Find out the IFU/channel from which this header originated.
int muse_utils_get_extension_for_ifu (const char *aFilename, unsigned char aIFU)
 Return extension number that corresponds to this IFU/channel number.
cpl_frameset * muse_frameset_find (const cpl_frameset *aFrames, const char *aTag, unsigned char aIFU, cpl_boolean aInvert)
 return frameset containing data from an IFU/channel with a certain tag
cpl_frameset * muse_frameset_find_tags (const cpl_frameset *aFrames, const cpl_array *aTags, unsigned char aIFU, cpl_boolean aInvert)
 return frameset containing data from an IFU/channel with the given tag(s)
cpl_frameset * muse_frameset_check_raw (const cpl_frameset *aFrames, const cpl_array *aTags, unsigned char aIFU)
 return frameset containing good raw input data
cpl_frameset * muse_frameset_sort_raw_other (const cpl_frameset *aFrames, int aIndex, const char *aDateObs, cpl_boolean aSequence)
 Create a new frameset containing all relevant raw frames first then all other frames.
cpl_frame * muse_frameset_find_master (const cpl_frameset *aFrames, const char *aTag, unsigned char aIFU)
 find the master frame according to its CCD number and tag
cpl_error_code muse_utils_frameset_merge_frames (cpl_frameset *aFrames, cpl_boolean aDelete)
 Merge IFU-specific files from a frameset to create multi-IFU outputs.
cpl_table * muse_table_load (muse_processing *aProcessing, const char *aTag, unsigned char aIFU)
 load a table according to its tag and IFU/channel number
cpl_propertylist * muse_propertylist_load (muse_processing *aProcessing, const char *aTag)
 load a propertylist according to its tag
cpl_table * muse_table_load_filter (muse_processing *aProcessing, const char *aFilterName)
 Load a table for a given filter name.
char * muse_utils_header_get_lamp_names (cpl_propertylist *aHeader, char aSep)
 Concatenate names of all active calibration lamps.
cpl_array * muse_utils_header_get_lamp_numbers (cpl_propertylist *aHeader)
 List numbers of all active calibration lamps.
cpl_matrix * muse_matrix_new_gaussian_2d (int aXHalfwidth, int aYHalfwidth, double aSigma)
 Create a matrix that contains a normalized 2D Gaussian.
cpl_image * muse_utils_image_fit_polynomial (const cpl_image *aImage, unsigned short aXOrder, unsigned short aYOrder)
 Create a smooth version of a 2D image by fitting it with a 2D polynomial.
cpl_error_code muse_utils_image_get_centroid_window (cpl_image *aImage, int aX1, int aY1, int aX2, int aY2, double *aX, double *aY, muse_utils_centroid_type aBgType)
 Compute centroid over an image window, optionally marginalizing over the background.
cpl_error_code muse_utils_get_centroid (const cpl_matrix *aPositions, const cpl_vector *aValues, const cpl_vector *aErrors, double *aX, double *aY, muse_utils_centroid_type aBgType)
 Compute centroid of a two-dimensional dataset.
cpl_error_code muse_utils_fit_multigauss_1d (const cpl_vector *aX, const cpl_bivector *aY, cpl_vector *aCenter, double *aSigma, cpl_vector *aFlux, cpl_vector *aPoly, double *aMSE, double *aRedChisq, cpl_matrix **aCovariance)
 Carry out a multi-Gaussian fit of data in a vector.
cpl_error_code muse_utils_fit_moffat_2d (const cpl_matrix *aPositions, const cpl_vector *aValues, const cpl_vector *aErrors, cpl_array *aParams, cpl_array *aPErrors, const cpl_array *aPFlags, double *aRMS, double *aRedChisq)
 Fit a 2D Moffat function to a given set of data.
cpl_polynomial * muse_utils_iterate_fit_polynomial (cpl_matrix *aPos, cpl_vector *aVal, cpl_vector *aErr, cpl_table *aExtra, const unsigned int aOrder, const double aRSigma, double *aMSE, double *aChiSq)
 Iterate a polynomial fit.
double muse_utils_pixtable_fit_line_gaussian (muse_pixtable *aPixtable, double aLambda, double aHalfWidth, double aBinSize, float aLo, float aHi, unsigned char aIter, cpl_array *aResults, cpl_array *aErrors)
 Fit a 1D Gaussian to a given wavelength range in a pixel table.
cpl_error_code muse_utils_copy_modified_header (cpl_propertylist *aH1, cpl_propertylist *aH2, const char *aKeyword, const char *aString)
 Copy a modified header keyword from one header to another.
cpl_error_code muse_utils_set_hduclass (cpl_propertylist *aHeader, const char *aClass2, const char *aExtData, const char *aExtDQ, const char *aExtStat)
 Set HDU headers for the ESO FITS data format.
void muse_utils_memory_dump (const char *aMarker)
 Display the current memory usage of the given program.
cpl_image * muse_convolve_image (const cpl_image *aImage, const cpl_matrix *aKernel)
 Compute the convolution of an image with a kernel.
muse_imagemuse_fov_load (const char *aFilename)
 Load a FOV image into a MUSE image.

Variables

const muse_cpltable_def muse_filtertable_def []
 MUSE filter table definition.

Detailed Description

This group handles several utility functions.


Typedef Documentation

typedef cpl_error_code( muse_cpl_evaluate_func)(void *aData, cpl_array *aPar, cpl_array *aRetval)

User provided function to evaluate in muse_cpl_optimize_lvmq().

Parameters:
aData Data forwarded from the fit algorithm call.
aPar Current fit parameter
aRetval Return value vector
Returns:
CPL_ERROR_NONE if everything went OK. Any other value is considered as error and will stop the minimization muse_cpl_optimize_lvmq().
Sample prototype:
cpl_error_code
muse_evaluate_sample(void *aData, cpl_array *aPar, cpl_array *aRetval);

Definition at line 88 of file muse_optimize.h.


Enumeration Type Documentation

Background handling when computing centroids.

Enumerator:
MUSE_UTILS_CENTROID_NORMAL 

no background treatment

MUSE_UTILS_CENTROID_MEAN 

subtract average as background

MUSE_UTILS_CENTROID_MEDIAN 

subtract median value as background

Definition at line 102 of file muse_utils.h.


Function Documentation

cpl_image* muse_convolve_image ( const cpl_image *  aImage,
const cpl_matrix *  aKernel 
)

Compute the convolution of an image with a kernel.

Parameters:
aImage The image to convolve.
aKernel The convolution kernel.
Returns:
On success the convoluted image is returned, and NULL if an error occurred.

The function convolves the input image aImage with the convolution kernel aKernel using an FFT. If aImage has an odd number of pixels along the y-axis, the last image row is discarded to make it a size even, however, the size of aImage along the x-axis must be even and an error is returned if it is not.

Exceptions:
set CPL_ERROR_NULL_INPUT, return NULL a parameter is NULL
set CPL_ERROR_IVALID_TYPE, return NULL aImage is not if type double
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULL invalid image size

Definition at line 2744 of file muse_utils.c.

Referenced by muse_find_stars().

cpl_error_code muse_cpl_optimize_lvmq ( void *  aData,
cpl_array *  aPar,
int  aSize,
muse_cpl_evaluate_func aFunction,
muse_cpl_optimize_control_t aCtrl 
)

Minimize a function with the Levenberg-Marquardt algorithm.

Parameters:
aData Any data to be forwarded to the evaluation function.
aPar Array containing the fits parameters.
aSize Number of data points.
aFunction Function that evaluates the fit.
aCtrl Structure that controls the algorithm, or NULL for defaults.
Return values:
CPL_ERROR_NONE Everything went OK.
CPL_ERROR_NULL_INPUT (aPar != NULL) not fulfilled
CPL_ERROR_ILLEGAL_INPUT (cpl_array_get_size(aPar) > 0) not fulfilled
CPL_ERROR_ILLEGAL_INPUT (aSize > 0) not fulfilled
CPL_ERROR_NULL_INPUT (aFunction != NULL) not fulfilled
CPL_ERROR_SINGULAR_MATRIX Return vector is orthogonal to the columns of the jacobian
CPL_ERROR_CONTINUE The algorithm did not converge.
CPL_ERROR_ILLEGAL_OUTPUT Memory allocation failed
Remarks:
If the evaluation function did not return CPL_ERROR_NONE, the minimization stops and returns with the return value of the evaluation function.

The interface is loosely modeled after cpl_fit_lvmq(). However it can be used with functions that calc the whole result vector at once, it does not need to provide a dervitative, and in may forward any data to the evaluation function.

Note:
The implementation used here is copied from http://www.messen-und-deuten.de/lmfit/ .

Referenced by muse_lsf_params_fit(), muse_sky_lines_fit(), muse_sky_lines_fit_old(), and muse_utils_fit_moffat_2d().

static void muse_cpl_optimize_print ( const char *  func,
int  n_par,
double *  par,
int  m_dat,
double *  fvec,
void *  data,
int  iflag,
int  iter,
int  nfev 
) [static]

Default printout method adopted to CPL.

Parameters:
func Function name
n_par Number of parameters
par Vector of parameters
m_dat Number of datapoints
fvec Vector of datapoints
data For soft control of printout behaviour, add control variables to the data struct.
iflag 0 (init) 1 (outer loop) 2(inner loop) -1(terminated)
iter outer loop counter
nfev number of calls to *evaluate

Definition at line 177 of file muse_optimize.c.

muse_image* muse_fov_load ( const char *  aFilename  ) 

Load a FOV image into a MUSE image.

Parameters:
aFilename name of the file to load
Returns:
a muse_image or NULL on error

Load the DATA extension containing the FOV image data from the input file. Bad pixels may be encoded as NaN values in the image data directly, or, if a DQ extension is found in the input file, it is used to replace the bad pixels in the FOV image data with NaN values.

Alternatively, if the DATA extension is an extension with higher-dimensional data or no image content (NAXIS != 2), load the first 2D image extension. In that case, search for the related STAT and DQ extension by prefixing them with the filter name.

Definition at line 2860 of file muse_utils.c.

References muse_image::data, muse_image::dq, muse_image::header, muse_image_delete(), muse_image_dq_to_nan(), muse_image_new(), muse_pfits_get_bunit(), muse_pfits_get_extname(), muse_pfits_get_naxis(), MUSE_WCS_KEYS, and muse_image::stat.

cpl_frameset* muse_frameset_check_raw ( const cpl_frameset *  aFrames,
const cpl_array *  aTags,
unsigned char  aIFU 
)

return frameset containing good raw input data

Parameters:
aFrames the input frameset
aTags the required DFS tag(s) of the frame (optional)
aIFU the IFU/channel number
Returns:
the resulting frameset or NULL on failure

Returns the good raw input data in form of a frameset. If aTag is NULL, tags are not checked.

Definition at line 283 of file muse_utils.c.

References muse_frameset_find_tags(), muse_pfits_get_binx(), muse_pfits_get_biny(), muse_pfits_get_chip_id(), muse_pfits_get_chip_name(), muse_pfits_get_read_id(), muse_pfits_get_read_name(), and muse_utils_get_extension_for_ifu().

cpl_frameset* muse_frameset_find ( const cpl_frameset *  aFrames,
const char *  aTag,
unsigned char  aIFU,
cpl_boolean  aInvert 
)

return frameset containing data from an IFU/channel with a certain tag

Parameters:
aFrames the input frameset
aTag the required DFS tag of the frame (optional)
aIFU the IFU/channel number to check for (optional)
aInvert if true, invert the selection
Returns:
the resulting frameset or NULL on failure

Returns the data in form of a frameset. Note that this frameset may be empty (but non-NULL), if no frame matching the parameters was found! If aTag is NULL, tags are not checked. If aIFU is 0, the IFU number is not checked.

If aTag is MUSE_TAG_GEOMETRY_TABLE or MUSE_TAG_TWILIGHT_CUBE, then all frames with that tag are matched, irrespective of the IFU number found it the header of the corresponding file.

The IFU number is checked using muse_utils_get_ifu(). If this fails, then the respective file is expected to be a generic calibration file.

Exceptions:
set CPL_ERROR_NULL_INPUT, return NULL aFrames is NULL
propagate error code, continue with next frame header of a file cannot be loaded

Definition at line 159 of file muse_utils.c.

References muse_pfits_get_pipefile(), muse_utils_get_extension_for_ifu(), and muse_utils_get_ifu().

Referenced by muse_frameset_find_master(), muse_frameset_find_tags(), muse_postproc_cube_load_output_wcs(), muse_processing_check_input(), muse_processing_lsf_params_load(), muse_processing_mask_load(), muse_sky_continuum_load(), and muse_sky_lines_load().

cpl_frame* muse_frameset_find_master ( const cpl_frameset *  aFrames,
const char *  aTag,
unsigned char  aIFU 
)

find the master frame according to its CCD number and tag

Parameters:
aFrames the frames list
aTag the tag
aIFU the IFU/channel number
Returns:
the frame of the master image

The returned frame is duplicated from the input frameset and therefore has to be deallocated after use.

Definition at line 504 of file muse_utils.c.

References muse_frameset_find().

Referenced by muse_propertylist_load(), muse_table_load(), and muse_table_load_filter().

cpl_frameset* muse_frameset_find_tags ( const cpl_frameset *  aFrames,
const cpl_array *  aTags,
unsigned char  aIFU,
cpl_boolean  aInvert 
)

return frameset containing data from an IFU/channel with the given tag(s)

Parameters:
aFrames the input frameset
aTags the required DFS tag(s) of the frame
aIFU the IFU/channel number to check for (optional)
aInvert if true, invert the selection
Returns:
the resulting frameset or NULL on failure

Returns the data in form of a frameset. Note that this frameset may be empty (but non-NULL), if no frame matching the parameters was found! If aIFU is 0, the IFU number is not checked.

This function just loops over muse_frameset_find() for all tags in aTags.

Exceptions:
set CPL_ERROR_NULL_INPUT, return NULL aFrames is NULL

Definition at line 252 of file muse_utils.c.

References muse_frameset_find().

Referenced by muse_basicproc_combine_images_lampwise(), muse_basicproc_load_reduced(), and muse_frameset_check_raw().

cpl_frameset* muse_frameset_sort_raw_other ( const cpl_frameset *  aFrames,
int  aIndex,
const char *  aDateObs,
cpl_boolean  aSequence 
)

Create a new frameset containing all relevant raw frames first then all other frames.

Parameters:
aFrames the frames list
aIndex the frame index (use a negative value to signify to take all raw frames or use aDateObs for comparison)
aDateObs the DATE-OBS string to search for (only when aIndex is negative, use NULL to signify to take all frames)
aSequence if target frame is part of a sequence
Returns:
The new ordered frameset or NULL on error.

Normal raw frames are sorted first, if their location in aFrames match the aIndex, or aDateObs is given and the DATE-OBS in their header match it. If aSequence is true, then it is expected that they are part of an exposure sequence (e.g. calibration flats), and they are taken irrespective of aIndex.

Raw frames tagged "ILLUM" also get a special handling, in that the first of them -- i.e. the one that got used in muse_basicproc_get_illum() -- is sorted into the output frameset after all other raw frames, but before all other frames.

The returned frameset is duplicated from the input frameset and therefore has to be deallocated using cpl_frameset_delete() after use.

Exceptions:
set CPL_ERROR_NULL_INPUT, return NULL input frameset was NULL

Definition at line 417 of file muse_utils.c.

References muse_pfits_get_dateobs().

const char* muse_get_license ( void   ) 

Get the pipeline copyright and license.

Returns:
The copyright and license string

The function wraps the cpl_get_license() macro and hence returns a pointer to the statically allocated license string. This string should not be modified using the returned pointer.

Definition at line 82 of file muse_utils.c.

void muse_mask_delete ( muse_mask aMask  ) 

Deallocate memory associated to a muse_mask object.

Parameters:
aMask input MUSE mask

Just calls cpl_mask_delete() and cpl_propertylist_delete() for the four components of a muse_mask, and frees memory for the aMask pointer. As a safeguard, it checks if a valid pointer was passed, so that crashes cannot occur.

Definition at line 68 of file muse_mask.c.

References muse_mask::header, and muse_mask::mask.

Referenced by muse_mask_load(), muse_postproc_process_exposure(), and muse_postproc_properties_delete().

muse_mask* muse_mask_load ( const char *  aFilename  ) 

Load a mask file and its FITS header.

Parameters:
aFilename name of the file to load
Returns:
a new muse_mask * or NULL on error
Remarks:
The new mask has to be deallocated using muse_mask_delete().
Only FITS keywords from the primary FITS header will be loaded.
Exceptions:
return NULL, propagate CPL error code cpl_propertylist_load fails (this handles the case of an invalid or empty filename)

Definition at line 90 of file muse_mask.c.

References muse_mask::header, muse_mask::mask, muse_mask_delete(), and muse_mask_new().

Referenced by muse_processing_mask_load().

muse_mask* muse_mask_new ( void   ) 

Allocate memory for a new muse object.

Returns:
a new muse_mask * or NULL on error
Remarks:
The returned object has to be deallocated using muse_mask_delete().
This function does not allocate the contents of the elements, these have to be allocated with cpl_mask_new() or cpl_propertylist_new(), respectively, or equivalent functions.

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

Definition at line 51 of file muse_mask.c.

Referenced by muse_mask_load(), and muse_sky_create_skymask().

cpl_error_code muse_mask_save ( muse_mask aMask,
const char *  aFilename 
)

Save the data and the FITS headers of a MUSE mask to a file.

Parameters:
aMask input MUSE mask
aFilename name of the output file
Returns:
CPL_ERROR_NONE or the relevant cpl_error_code on error
Remarks:
The primary headers of the output file will be constructed from the header member of the muse_mask structure.
Exceptions:
return CPL_ERROR_NULL_INPUT aImage or aFilename are NULL
return CPL error code failure to save any of the components

Definition at line 131 of file muse_mask.c.

References muse_mask::header, and muse_mask::mask.

Referenced by muse_processing_save_mask().

cpl_matrix* muse_matrix_new_gaussian_2d ( int  aXHalfwidth,
int  aYHalfwidth,
double  aSigma 
)

Create a matrix that contains a normalized 2D Gaussian.

Parameters:
aXHalfwidth horizontal half width of the kernel matrix
aYHalfwidth vertical half width of the kernel matrix
aSigma sigma of Gaussian function
Returns:
The new matrix or NULL on error

The 2*halfwidth+1 gives the size of one side of the matrix, i.e. halfwidth=3 for a 7x7 matrix. The created matrix has to be deallocated by cpl_matrix_delete().

Definition at line 1095 of file muse_utils.c.

Referenced by muse_geo_measure_spots().

cpl_propertylist* muse_propertylist_load ( muse_processing aProcessing,
const char *  aTag 
)

load a propertylist according to its tag

Parameters:
aProcessing the processing structure, includes the input frames list
aTag the tag
Returns:
the cpl_propertylist * or NULL if an error occurred.

This function tries to find the frame in the input frameset and loads the propertylist from it.

Definition at line 841 of file muse_utils.c.

References muse_processing::inframes, muse_frameset_find_master(), and muse_processing_append_used().

cpl_table* muse_table_load ( muse_processing aProcessing,
const char *  aTag,
unsigned char  aIFU 
)

load a table according to its tag and IFU/channel number

Parameters:
aProcessing the processing structure, includes the input frames list
aTag the tag
aIFU the IFU/channel number
Returns:
the cpl_table * or NULL if an error occurred.

This function tries to find an extension that is specific for the given IFU number, and loads that, if available. If not, it is assumed that either the table is a general one applicable for all IFUs or only contains data for this one IFU.

Definition at line 773 of file muse_utils.c.

References muse_processing::inframes, muse_frameset_find_master(), muse_pfits_get_extname(), muse_processing_append_used(), and muse_utils_get_extension_for_ifu().

cpl_table* muse_table_load_filter ( muse_processing aProcessing,
const char *  aFilterName 
)

Load a table for a given filter name.

Parameters:
aProcessing the processing structure, includes the input frames list
aFilterName the filter name
Returns:
the cpl_table * or NULL on error

This function tries to find a filter table and in it an extension for the filter of the given name. The table from that extension is loaded.

A filter called "white" is built into this function, it covers the full MUSE wavelength range with constant throughput.

Exceptions:
set CPL_ERROR_NULL_INPUT, return NULL aFilterName is NULL
return NULL (and output debug message) aFilterName is "none"
set CPL_ERROR_FILE_NOT_FOUND, return NULL input frame with tag MUSE_TAG_FILTER_LIST was not found
set CPL_ERROR_DATA_NOT_FOUND, return NULL valid file with tag MUSE_TAG_FILTER_LIST does not contain filter named aFilterName
propagate error code, return NULL loading table for filter aFilterName from valid file with tag MUSE_TAG_FILTER_LIST failed

Definition at line 905 of file muse_utils.c.

References muse_processing::inframes, muse_cpltable_new(), muse_frameset_find_master(), and muse_processing_append_used().

Referenced by muse_postproc_cube_resample_and_collapse(), muse_postproc_process_exposure(), and muse_wcs_locate_sources().

cpl_error_code muse_utils_copy_modified_header ( cpl_propertylist *  aH1,
cpl_propertylist *  aH2,
const char *  aKeyword,
const char *  aString 
)

Copy a modified header keyword from one header to another.

Parameters:
aH1 input header
aH2 output header
aKeyword header keyword to copy
aString string to be used for the modification
Returns:
CPL_ERROR_NONE on success or another CPL error on failure.

The keyword is modified by appending " (aString)" to it.

Exceptions:
return CPL_ERROR_NULL_INPUT one of the input arguments is NULL
return CPL_ERROR_ILLEGAL_INPUT the string in the input header cannot be read

Definition at line 2566 of file muse_utils.c.

Referenced by muse_datacube_save(), muse_datacube_save_recimages(), and muse_postproc_cube_resample_and_collapse().

cpl_error_code muse_utils_fit_moffat_2d ( const cpl_matrix *  aPositions,
const cpl_vector *  aValues,
const cpl_vector *  aErrors,
cpl_array *  aParams,
cpl_array *  aPErrors,
const cpl_array *  aPFlags,
double *  aRMS,
double *  aRedChisq 
)

Fit a 2D Moffat function to a given set of data.

Parameters:
aPositions input image to use for the fit
aValues input values to use for the fit
aErrors input errors to use for the fit (can be NULL)
aParams parameter array (type double)
aPErrors parameter error double array (can be NULL)
aPFlags parameter flags integer array (can be NULL)
aRMS root mean square of the fit (can be NULL)
aRedChisq reduced chi^2 of the fit (can be NULL)
Returns:
CPL_ERROR_NONE on success any other CPL error code on failure.

This fits a Moffat (1969 A&A 3, 455, Eq. 7) function in two-dimensional cartesian form allowing for non-circular isophotes

    moffat(x,y) = B + A (beta - 1) / (pi alphax alphay sqrt(1 - rho^2))
                  [ 1 + { ((x - xc) / alphax)^2
                         + 2 rho (x-xc)(y-yc) / (alphax alphay)
                         + ((y - yc) / alphay)^2} / {1 - rho^2} ]^(-beta)

to the input data. The parameters and their starting values are

  • aParams[0]: B, constant background level; median of the dataset
  • aParams[1]: A, volume of the function (flux); integrated value of the dataset in excess of the median
  • aParams[2]: xc, horizontal center; marginal centroid of the dataset
  • aParams[3]: yc, vertical center; see xc
  • aParams[4]: alphax, related to horizontal HWHM; computed from the HWHM of the dataset, using at least three data values near the half peak around the (marginal) centroid
  • aParams[5]: alphay, related to vertical HWHM; see alphax
  • aParams[6]: beta, seeing-related Moffat parameter; 2.5
  • aParams[7]: rho, the x-y correlation parameter; 0.0

Valid inputs in aParams override the first-guess parameters given above. If only one valid alpha parameter was given, the other one is used as starting value.

In case of uniform data, no error will be returned but a flat Moffat function with undefined center and widths will be created.

References:

Exceptions:
return CPL_ERROR_NULL_INPUT aPositions, aValues, or aParams are NULL
return CPL_ERROR_INCOMPATIBLE_INPUT aPositions does not give the same number of positions as aValues
return CPL_ERROR_INCOMPATIBLE_INPUT aPositions does not contain two columns
return CPL_ERROR_INCOMPATIBLE_INPUT aErrors is given but does not have the same size as aValues
return CPL_ERROR_INVALID_TYPE aParams is not of type double
return CPL_ERROR_INVALID_TYPE aPErrors is given but not of type double
return CPL_ERROR_INVALID_TYPE aPFlags is given but not of type int
return CPL_ERROR_DATA_NOT_FOUND aPErrors and/or aRedChisq are given but aErrors is NULL
return CPL_ERROR_SINGULAR_MATRIX input data has less than 8 positions
return CPL_ERROR_ILLEGAL_INPUT aPFlags did not leave any parameter free
return CPL_ERROR_ILLEGAL_INPUT aPFlags was set to freeze a parameter but this parameter does not have an input value in aParams
propagate return code of cpl_fit_lvmq() the actual fit fails

Definition at line 1874 of file muse_utils.c.

References muse_cpl_optimize_lvmq(), MUSE_UTILS_CENTROID_MEDIAN, and muse_utils_get_centroid().

Referenced by muse_dar_check(), and muse_wcs_centroid_stars().

cpl_error_code muse_utils_fit_multigauss_1d ( const cpl_vector *  aX,
const cpl_bivector *  aY,
cpl_vector *  aCenter,
double *  aSigma,
cpl_vector *  aFlux,
cpl_vector *  aPoly,
double *  aMSE,
double *  aRedChisq,
cpl_matrix **  aCovariance 
)

Carry out a multi-Gaussian fit of data in a vector.

Parameters:
aX Positions to fit
aY Values and associated errors to fit
aCenter centers of the Gaussian peaks
aSigma the common Gaussian sigma of all peaks; use a negative value to have sigma be a fixed parameter in the fit
aFlux fluxes of the Gaussian peaks
aPoly coefficients of the background polynomial
aMSE computed mean squared error of the fit
aRedChisq reduced chi square of the fit
aCovariance output covariance matrix of the fit
Returns:
CPL_ERROR_NONE on success, another CPL error code on failure.

This function fits multiple Gaussians plus a background polynomial to the dataset given by aX and aY. The number of Gaussian peaks is determined by the length of the vector aCenter. It is mandatory to use it to give first-guess values for the centers of the peaks and an estimate of the expected Gaussian sigma in aSigma. aFlux has to be of the same length as aCenter, if given its values are also taken as first guesses of the areas of the Gaussian peaks (the fluxes). The background polynomial is defined using the aPoly vector, its contents are first-guess values for the polynomial coefficients, its length is used to define the order of the polynomial. If aPoly is NULL, the background is assumed to be a constant zero level.

If successful, fit results are returned in aCenter, aSigma, and -- if given -- aFlux. If aSigma was negative on input, the absolute value returned is same as the input, but positive. Then, the covariance matrix aCovariance is created and filled; it has to be deallocated using cpl_matrix_delete() after use. The order of parameters in the covariance matrix is the following: polynomial coefficients, sigma, centers, fluxes (where the number of elements, except for sigma, is determined by the lengths of the input objects).

This function is loosely modeled after cpl_vector_fit_gaussian(), it also uses cpl_fit_lvmq() to do that actual fit. But since computing first-guess parameters from the data is not possible in a meaningful way for multi-Gaussians, at least not without knowing the number of peaks, this function requires first guesses to be given, with the exception of the fluxes.

Exceptions:
return CPL_ERROR_NULL_INPUT aX, aY, aCenter, or aSigma are NULL
return CPL_ERROR_INCOMPATIBLE_INPUT aY contains a different number of points as aX
return CPL_ERROR_INCOMPATIBLE_INPUT aFlux is given but contains a different number of parameters (peaks) than aCenter
return CPL_ERROR_ILLEGAL_INPUT aRedChisq is not NULL but there are less points than parameters, so that it cannot be computed
propagate error cpl_fit_lvmq() fails

Definition at line 1554 of file muse_utils.c.

Referenced by muse_wave_line_fit_multiple().

cpl_error_code muse_utils_frameset_merge_frames ( cpl_frameset *  aFrames,
cpl_boolean  aDelete 
)

Merge IFU-specific files from a frameset to create multi-IFU outputs.

Parameters:
aFrames the frames list
aDelete if CPL_TRUE, delete input files from framesete after merging
Returns:
CPL_ERROR_NONE on success another CPL error code on failure

This function groups all frames in the input frameset regarding the base of the filenames (without -nn.fits), and then merges them, taking care to put IFU-specific information into the extension header (like QC and DRS parameters). The output filename for each group is the common basename of files (usually the PRO.CATG tag given to it by the pipeline during processing).

After all products were merged, the related files in the input frameset are physically removed from the filesystem and purged from aFrames.

The merged files in the frameset aFrames are set to the cpl_frame_group of CPL_FRAME_GROUP_PRODUCT, even if the input frames were not.

Note:
Files tagged with "PIXTABLE_*" are not merged, but silently ignored!
Exceptions:
set and return CPL_ERROR_NULL_INPUT aFrames is NULL
set and return CPL_ERROR_ILLEGAL_INPUT aFrames is empty

Definition at line 588 of file muse_utils.c.

cpl_error_code muse_utils_get_centroid ( const cpl_matrix *  aPositions,
const cpl_vector *  aValues,
const cpl_vector *  aErrors,
double *  aX,
double *  aY,
muse_utils_centroid_type  aBgType 
)

Compute centroid of a two-dimensional dataset.

Parameters:
aPositions matrix containing the positions
aValues vector containing the data values
aErrors vector containing the data errors (1 sigma, can be NULL)
aX computed horizontal centroid position
aY computed vertical centroid position
aBgType specifies how to handle the background
Returns:
CPL_ERROR_NONE on success, another cpl_error_code on failure.

This computes the center of gravity, using the data values and optionally the data errors as weights.

The input aPositions matrix must be for two-dimensional data, i.e. contain two columns, and the number of rows must be equal to the number of entries in both vectors.

Exceptions:
return CPL_ERROR_NULL_INPUT aPositions or aValues are NULL
return CPL_ERROR_INCOMPATIBLE_INPUT aPositions does not contain two columns
return CPL_ERROR_INCOMPATIBLE_INPUT aPositions does not give the same number of positions as aValues
return CPL_ERROR_INCOMPATIBLE_INPUT aValues does not contain the same number of positions as aErrors
return CPL_ERROR_NULL_INPUT both aX and aY are NULL so that the centroid cannot be returned
return CPL_ERROR_ILLEGAL_INPUT aBgType does not contain a valid centroid type

Definition at line 1324 of file muse_utils.c.

References MUSE_UTILS_CENTROID_MEAN, MUSE_UTILS_CENTROID_MEDIAN, and MUSE_UTILS_CENTROID_NORMAL.

Referenced by muse_dar_check(), and muse_utils_fit_moffat_2d().

int muse_utils_get_extension_for_ifu ( const char *  aFilename,
unsigned char  aIFU 
)

Return extension number that corresponds to this IFU/channel number.

Parameters:
aFilename name of the FITS file
aIFU the IFU/channel number
Returns:
Corresponding extension number, or -1 if not found.

Definition at line 117 of file muse_utils.c.

References muse_pfits_has_ifu().

Referenced by muse_frameset_check_raw(), muse_frameset_find(), and muse_table_load().

unsigned char muse_utils_get_ifu ( const cpl_propertylist *  aHeaders  ) 
char* muse_utils_header_get_lamp_names ( cpl_propertylist *  aHeader,
char  aSep 
)

Concatenate names of all active calibration lamps.

Parameters:
aHeader the FITS header to search for lamp entries
aSep the separator to use for name concatenation
Returns:
A newly allocated string with the filter name(s) or NULL on error or if no lamps are switched on.

This function iterates through all lamp shutters found in the header, and for those where the lamp is switched on and the shutter is open appends the name to the output string. Prefixes of lamp names (currently only "CU-LAMP-") are cut off, e.g. "CU-LAMP-HgCd" becomes "HgCd". XXX to aid AIT, lamp names like "CU-LAMP[3-6]" are converted to the respective element names (Ne, Xe, HgCd).

The returned string has to be deallocated with cpl_free().

Exceptions:
set CPL_ERROR_NULL_INPUT, return NULL aHeader is NULL

Definition at line 985 of file muse_utils.c.

References muse_pfits_get_lamp_name(), muse_pfits_get_lamp_status(), muse_pfits_get_lampnum(), and muse_pfits_get_shut_status().

Referenced by muse_wave_calib_lampwise().

cpl_array* muse_utils_header_get_lamp_numbers ( cpl_propertylist *  aHeader  ) 

List numbers of all active calibration lamps.

Parameters:
aHeader the FITS header to search for lamp entries
Returns:
A cpl_array of type CPL_TYPE_INT, or NULL on error or if no lamps are switched on.

This function iterates through all lamp shutters found in the header, and for those where the lamp is switched on and the shutter is open appends the lamp number to the output array.

The lamp numbers are the i in the ESO.INS.LAMPi keywords in the MUSE FITS headers.

The returned array has to be deallocated with cpl_array_delete().

Exceptions:
set CPL_ERROR_NULL_INPUT, return NULL aHeader is NULL

Definition at line 1052 of file muse_utils.c.

References muse_pfits_get_lamp_status(), muse_pfits_get_lampnum(), and muse_pfits_get_shut_status().

Referenced by muse_wave_calib_lampwise().

cpl_image* muse_utils_image_fit_polynomial ( const cpl_image *  aImage,
unsigned short  aXOrder,
unsigned short  aYOrder 
)

Create a smooth version of a 2D image by fitting it with a 2D polynomial.

Parameters:
aImage input image to fit
aXOrder polynomial order to use in x direction
aYOrder polynomial order to use in y direction
Returns:
a new cpl_image * constructed from the polynomial fit or NULL on error

This function transfers all pixels (their positions and values) into suitable structures and calls cpl_polynomial_fit(). If that polynomial fit succeeds, cpl_image_fill_polynomial() is used to create the output image. Rejected (bad) pixels in the input image are marked as rejected in the output image as well.

Exceptions:
set CPL_ERROR_NULL_INPUT, return NULL aImage is NULL
set CPL_ERROR_DATA_NOT_FOUND, return NULL aImage does not contain good pixels
propagate error code, return NULL cpl_polynomial_fit() fails

Definition at line 1143 of file muse_utils.c.

cpl_error_code muse_utils_image_get_centroid_window ( cpl_image *  aImage,
int  aX1,
int  aY1,
int  aX2,
int  aY2,
double *  aX,
double *  aY,
muse_utils_centroid_type  aBgType 
)

Compute centroid over an image window, optionally marginalizing over the background.

Parameters:
aImage input image to use
aX1 lower left x position of window
aY1 lower left y position of window
aX2 upper right x position of window
aY2 upper right y position of window
aX computed centroid in x-direction
aY computed centroid in x-direction
aBgType specifies how to handle the background
Returns:
CPL_ERROR_NONE on success, another CPL error code on failure

This computes the ("marginal") centroid over an image window, similar to IRAF's imcentroid algorithm but without iterations. Before the normal centroid is actually computed, the average level of the image is subtracted. Only the positions with positive values are then used in the computation of the output centroid.

Exceptions:
return CPL_ERROR_NULL_INPUT aImage or both aXCen and aYCen are NULL
propagate error code cpl_image_extract() fails for the given coordinates
return CPL_ERROR_ILLEGAL_INPUT aBgType does not contain a valid centroid type

Definition at line 1230 of file muse_utils.c.

References MUSE_UTILS_CENTROID_MEAN, MUSE_UTILS_CENTROID_MEDIAN, and MUSE_UTILS_CENTROID_NORMAL.

Referenced by muse_dar_check(), and muse_wcs_centroid_stars().

cpl_polynomial* muse_utils_iterate_fit_polynomial ( cpl_matrix *  aPos,
cpl_vector *  aVal,
cpl_vector *  aErr,
cpl_table *  aExtra,
const unsigned int  aOrder,
const double  aRSigma,
double *  aMSE,
double *  aChiSq 
)

Iterate a polynomial fit.

Parameters:
aPos matrix with input positions
aVal vector with input values
aErr vector with input errors (optional, currently unused)
aExtra table with extra information (optional, same number of rows as aVal)
aOrder polynomial order to use for the fit
aRSigma rejection sigma
aMSE output mean squared error of final fit (optional)
aChiSq output chi square of final fit (optional)
Returns:
CPL_ERROR_NONE on success any other CPL error code on failure.

The position matrix aPos contains the same number of columns as the values vector aVal. The number of rows in aPos defines the number of dimensions of the output polynomial.

The table aExtra contains extra information, with each matrix row related to each entry in the aVal vector.

Infinite entries (NANs and INFs) in aVal are rejected at the start, so can be used as "bad pixel" markers. The procedure will fail, if only infinite values are present.

Note:
All input structures (i.e. aPos, aVal, aErr, and aExtra) are changed by this routine, so that entries rejected during the iterations are erased. This means that pointers to the structures may be changed afterwards.

If an error occurs, both aChiSq and aMSE are set to high values (DBL_MAX).

Exceptions:
set CPL_ERROR_NULL_INPUT, return NULL aPos and/or aVal are NULL
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULL the number of aPos does not match the size of aVal
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULL aErr was specified but does not match the size of aVal
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULL aExtra was specified but the number of its rows does not match the size of aVal
set CPL_ERROR_ILLEGAL_INPUT, return NULL aVal only contains infinite values
set CPL_ERROR_ILLEGAL_OUTPUT, return NULL the iterative procedure tries to remove the last vector/matrix element

Definition at line 2230 of file muse_utils.c.

References muse_cplvector_erase_element().

Referenced by muse_dar_check(), muse_quadrants_overscan_polyfit_vertical(), muse_quadrants_overscan_stats(), muse_trace_iterate_fit(), muse_wave_calib_lampwise(), and muse_wave_line_fit_iterate().

void muse_utils_memory_dump ( const char *  aMarker  ) 

Display the current memory usage of the given program.

Parameters:
aMarker marker string to use in the debug output
Note:
This function prints CPL memory info to stderr and other data to stdout!
This function only outputs anything if an executable name was given using the environment variable MUSE_DEBUG_MEMORY_PROGRAM.

This function uses the cpl_memory_dump() function to list pointers allocated through CPL and the Unix ps command to display system information about the process.

Definition at line 2698 of file muse_utils.c.

Referenced by muse_resampling_cube(), and muse_xcombine_tables().

double muse_utils_pixtable_fit_line_gaussian ( muse_pixtable aPixtable,
double  aLambda,
double  aHalfWidth,
double  aBinSize,
float  aLo,
float  aHi,
unsigned char  aIter,
cpl_array *  aResults,
cpl_array *  aErrors 
)

Fit a 1D Gaussian to a given wavelength range in a pixel table.

Parameters:
aPixtable input pixel table
aLambda the wavelength around which to extract the range
aHalfWidth the half width of the range in wavelength to use
aBinSize the size of the bins in wavelength for the spectrum
aLo low sigma-clipping limit for the spectrum
aHi high sigma-clipping limit for the spectrum
aIter number of iterations for sigma-clipping the spectrum
aResults parameter error double array (can be NULL)
aErrors parameter flags integer array (can be NULL)
Returns:
the center of the Gaussian on success or 0. on error.

This fits a 1D Gaussian of the form

    gauss(x) = A / sqrt(2 pi sigma^2) * exp( -(x - xc)^2/(2 sigma^2)) + B

to the input pixel table. It does this by resampling the pixel table in the specified wavelength range into a temporary spectrum, sampled at aBinSize, using muse_resampling_spectrum(), which is then given to cpl_vector_fit_gaussian().

This function directly returns the center xc of the Gaussian fit. If the other properties are required, the optional inputs aResults (for the values) and aErrors (for the sigma values) need to be passed as CPL arrays of type CPL_TYPE_DOUBLE. These arrays are resized to 4 elements and overwritten with output. The Gaussian parameters are always written to aResults (if given), the errors returned in aErrors may be invalid, except for the 0th element (the centroid error) which is always written. The order of the elements is:

  • aParams[0]: xc, the Gaussian center
  • aParams[1]: sigma
  • aParams[2]: A, the area under the Gaussian curve
  • aParams[3]: B, the background level

First-guess parameters cannot be given, but the wavelength range should be given to restrict the data to a set of data that contains one Gaussian-like peak.

Note:
The input pixel table is preserved, except for the table selection flags, which are reset to none selected when the function returns.
Exceptions:
set CPL_ERROR_NULL_INPUT, return 0. aPixtable or one of its components is NULL
set CPL_ERROR_DATA_NOT_FOUND, return 0. aPixtable does not have data in the range |aLambda| +/- aHalfWidth
propagate error code, return 0. muse_resampling_spectrum() fails

Definition at line 2438 of file muse_utils.c.

References muse_pixtable::header, muse_resampling_spectrum_iterate(), muse_utils_get_ifu(), and muse_pixtable::table.

Referenced by muse_basicproc_shift_pixtable().

cpl_error_code muse_utils_set_hduclass ( cpl_propertylist *  aHeader,
const char *  aClass2,
const char *  aExtData,
const char *  aExtDQ,
const char *  aExtStat 
)

Set HDU headers for the ESO FITS data format.

Parameters:
aHeader the FITS headers to modify
aClass2 type of class to set, i.e. contents of HDUCLAS2
aExtData extension name for the data extension
aExtDQ extension name for the bad pixel extension (or NULL)
aExtStat extension name for the variance extension (or NULL)
Returns:
CPL_ERROR_NONE on success, another CPL error code on failure.

This function adds special FITS headers to support the ESO format. The information was taken from v2.5.1 (dated Feb. 15th, 2012) of the document "FITS format description for pipeline products with data, error and data quality information" and further info by Martin Kuemmel and Harald Kuntschner.

This function tries to set these header keywords directly after EXTNAME, if available, otherwise at the end of the input header.

Quality Assessment:
This function is used by muse_image_save() and muse_datacube_save(). Tests of their functionality include tests of the headers that are created using this function.
Exceptions:
return CPL_ERROR_NULL_INPUT aHeader, aClass2, or aExtData are NULL
return CPL_ERROR_ILLEGAL_INPUT aClass2 is neither "DATA", "ERROR", nor "QUALITY"

Definition at line 2607 of file muse_utils.c.

Referenced by muse_datacube_save(), muse_datacube_save_recimages(), and muse_image_save().


Variable Documentation

Initial value:
 {
  { "lambda", CPL_TYPE_DOUBLE, "Angstrom", "%7.2f", "wavelength", CPL_TRUE},
  { "throughput", CPL_TYPE_DOUBLE, "", "%.4e",
    "filter response (in fractions of 1)", CPL_TRUE},
  { NULL, 0, NULL, NULL, NULL, CPL_FALSE }
}

MUSE filter table definition.

A MUSE filter table has the following columns:

  • 'lambda': the wavelength in Angstrom
  • 'throughput': the filter response in fractions of 1

Definition at line 874 of file muse_utils.c.


Generated on 26 Jan 2017 for MUSE Pipeline Reference Manual by  doxygen 1.6.1