UVES Pipeline Reference Manual  5.4.0
Functions
Substep: Extraction

Functions

static int extract_order_simple (const cpl_image *image, const cpl_image *image_noise, const polynomial *order_locations, int order, int minorder, int spectrum_row, double offset, double slit_length, extract_method method, const cpl_image *weights, bool extract_partial, cpl_image *spectrum, cpl_image *spectrum_noise, cpl_binary *spectrum_badmap, cpl_table **info_tbl, double *sn)
 Extract one order using linear, average or weighted extraction.
static double area_above_line (int y, double left, double right)
 Calculate the area of a pixel that is above a line.
static cpl_table * opt_define_sky (const cpl_image *image, const cpl_image *weights, uves_iterate_position *pos)
 Define sky/object rows.
static cpl_image * opt_extract_sky (const cpl_image *image, const cpl_image *image_noise, const cpl_image *weights, uves_iterate_position *pos, cpl_image *sky_spectrum, cpl_image *sky_spectrum_noise)
 Extract and subtract sky.
static cpl_image * opt_subtract_sky (const cpl_image *image, const cpl_image *image_noise, const cpl_image *weights, uves_iterate_position *pos, const cpl_table *sky_map, cpl_image *sky_spectrum, cpl_image *sky_spectrum_noise)
 Measure and subtract sky.
static cpl_table ** opt_sample_spatial_profile (const cpl_image *image, const cpl_image *weights, uves_iterate_position *pos, int stepx, int sampling_factor, int *nbins)
 Sample spatial profile.
static uves_extract_profile * opt_measure_profile (const cpl_image *image, const cpl_image *image_noise, const cpl_image *weights, uves_iterate_position *pos, int chunk, int sampling_factor, int(*f)(const double x[], const double a[], double *result), int(*dfda)(const double x[], const double a[], double result[]), int M, const cpl_image *sky_spectrum, cpl_table *info_tbl, cpl_table **profile_global)
 Measure spatial profile (all orders)
static cpl_table * opt_measure_profile_order (const cpl_image *image, const cpl_image *image_noise, const cpl_binary *image_bpm, uves_iterate_position *pos, int chunk, int(*f)(const double x[], const double a[], double *result), int(*dfda)(const double x[], const double a[], double result[]), int M, const cpl_image *sky_spectrum)
 Measure spatial profile (analytical)
static void revise_noise (cpl_image *image_noise, const cpl_binary *image_bpm, const uves_propertylist *image_header, uves_iterate_position *pos, const cpl_image *spectrum, const cpl_image *sky_spectrum, const uves_extract_profile *profile, enum uves_chip chip)
 Refine error bars.
static int opt_extract (cpl_image *image, const cpl_image *image_noise, uves_iterate_position *pos, const uves_extract_profile *profile, bool optimal_extract_sky, double kappa, cpl_table *blemish_mask, cpl_table *cosmic_mask, int *cr_row, cpl_table *profile_table, int *prof_row, cpl_image *spectrum, cpl_image *spectrum_noise, cpl_image *weights, cpl_image *sky_spectrum, cpl_image *sky_spectrum_noise, double *sn)
 Optimally extract order using the given the profile.
static int opt_get_order_width (const uves_iterate_position *pos)
 Get width of order.
static double estimate_sn (const cpl_image *image, const cpl_image *image_noise, uves_iterate_position *pos)
 Estimate the S/N of the input frame.
static double opt_get_sky (const double *image_data, const double *noise_data, const double *weights_data, uves_iterate_position *pos, const cpl_table *sky_map, double buffer_flux[], double buffer_noise[], double *sky_background_noise)
 Measure sky level (median)
static double opt_get_noise_median (const double *noise_data, const cpl_binary *image_bpm, uves_iterate_position *pos, double noise_buffer[])
 Measure median noise level of extraction bin.
static double opt_get_flux_sky_variance (const double *image_data, const double *noise_data, double *weights_data, uves_iterate_position *pos, const uves_extract_profile *profile, bool optimal_extract_sky, double median_noise, double *variance, double *sky_background, double *sky_background_noise)
 Get flux, sky and variances of current bin.
static bool opt_reject_outlier (const double *image_data, const double *noise_data, cpl_binary *image_bpm, double *weights_data, uves_iterate_position *pos, const uves_extract_profile *profile, double kappa, double flux, double sky_background, double red_chisq, cpl_table *cosmic_mask, int *cr_row, int *hot_pixels, int *cold_pixels)
 Find and reject outlier pixel.
static double opt_get_redchisq (const uves_extract_profile *profile, const uves_iterate_position *pos)
 Get reduced chi^2 for current bin.
static polynomialrepeat_orderdef (const cpl_image *image, const cpl_image *image_noise, const polynomial *guess_locations, int minorder, int maxorder, slit_geometry sg, cpl_table *info_tbl)
 Refine order definition using the science frame.
static double detect_ripples (const cpl_image *spectrum, const uves_iterate_position *pos, double sn)
 Try to detect and warn about any optimal extraction ripples (happening if oversampling factor is too small)
cpl_parameterlist * uves_extract_define_parameters (void)
 Define recipe parameters used for extraction.
extract_method uves_get_extract_method (const cpl_parameterlist *parameters, const char *context, const char *subcontext)
 Read extraction method from parameter list.
cpl_image * uves_extract (cpl_image *image, cpl_image *image_noise, const uves_propertylist *image_header, const cpl_table *ordertable, const polynomial *order_locations_raw, double slit_length, double offset, const cpl_parameterlist *parameters, const char *context, const char *mode, bool extract_partial, bool debug_mode, enum uves_chip chip, uves_propertylist **header, cpl_image **spectrum_noise, cpl_image **sky_spectrum, cpl_image **sky_spectrum_noise, cpl_table **cosmic_mask, cpl_image **cosmic_image, cpl_table **profile_table, cpl_image **weights, cpl_table **info_tbl, cpl_table **order_trace)
 Extract a spectrum.

Detailed Description

This module implements simple (i.e. linear, average, weighted) and optimal extraction of echelle spectra.


Function Documentation

static int extract_order_simple ( const cpl_image *  image,
const cpl_image *  image_noise,
const polynomial order_locations,
int  order,
int  minorder,
int  spectrum_row,
double  offset,
double  slit_length,
extract_method  method,
const cpl_image *  weights,
bool  extract_partial,
cpl_image *  spectrum,
cpl_image *  spectrum_noise,
cpl_binary *  spectrum_badmap,
cpl_table **  info_tbl,
double *  sn 
)
static

Extract one order using linear, average or weighted extraction.

Parameters:
imageThe input image in (pixel,pixel)-space
image_noiseThe input image noise. If NULL, a constant noise level is assumed.
order_locationsBivariate polynomial defining the positions of the relative orders
orderThe relative order number
minorderThe relative order number minimum
spectrum_rowRow of spectrum to extract. This is often not, but might be, offset with a few rows from the relative order number.
offsetOffset (in pixels) of slit
slit_lengthLength (in pixels) of area to extract
methodThe extraction method
weightsWeight image used for weighted extraction. Must be non-NULL
extract_partialFlag indicating if an extraction bin which is partially outside the image should be extracted (true) or rejected (false) iff method is EXTRACT_WEIGHTED.
spectrum(output) The output spectrum
spectrum_noise(output) If non-NULL, the noise of the extracted spectrum is computed and returned through this parameter. Requires input noise image to be specified.
spectrum_badmap(output) Spectrum bad pixel map (un-extracted bins)
info_tbl(output) tabel with object position, fwhm
sn(output) signal-to-noise
Returns:
number of bins extracted

For linear and average extraction, the flux profile is interpolated in a way that conserves the total flux (refer to code for details).

Definition at line 1686 of file uves_extract.c.

References area_above_line(), check, check_nomsg, passure, and uves_polynomial_evaluate_2d().

Referenced by uves_extract().

static double area_above_line ( int  y,
double  left,
double  right 
)
static

Calculate the area of a pixel that is above a line.

Parameters:
yVertical center of the pixel
leftIntersection of line and left pixel boundary (y-coordinate)
rightIntersection of line and right pixel boundary (y-coordinate)
Returns:
The area of the pixel that is above the line, or undefined on error

The line slope must be between 0 and 1, otherwise an error is set.

To extend this function to also work with negative line slopes, a few cases more cases must be handled (see code). The extraction algorithm itself doesn't depend on the slope being positive.

Definition at line 2084 of file uves_extract.c.

Referenced by extract_order_simple().

static cpl_table * opt_define_sky ( const cpl_image *  image,
const cpl_image *  weights,
uves_iterate_position *  pos 
)
static

Define sky/object rows.

Parameters:
imageThe input image in (pixel,pixel)-space
weightsWeight image (defines bad pixels)
posimage iterator
Returns:
Table where selected rows (bins) are the sky bins.

The function

  • Defines sky/object rows.
  • Extracts+subtracts sky

Definition at line 2337 of file uves_extract.c.

References check, and opt_sample_spatial_profile().

Referenced by opt_extract_sky().

static cpl_image * opt_extract_sky ( const cpl_image *  image,
const cpl_image *  image_noise,
const cpl_image *  weights,
uves_iterate_position *  pos,
cpl_image *  sky_spectrum,
cpl_image *  sky_spectrum_noise 
)
static

Extract and subtract sky.

Parameters:
imageThe input image in (pixel,pixel)-space
image_noiseThe input image noise. May not be NULL.
weightsBad pixels (from previous iterations) will not contribute to the extraction
posimage iterator
sky_spectrum(output) This image will contain the sky spectrum.
sky_spectrum_noise(output) This image will contain the sky spectrum noise.
Returns:
sky subtracted image

The function

  • Defines sky/object rows.
  • Extracts+subtracts sky

Definition at line 2288 of file uves_extract.c.

References check, opt_define_sky(), opt_subtract_sky(), uves_msg, and uves_msg_low.

Referenced by uves_extract().

static cpl_image * opt_subtract_sky ( const cpl_image *  image,
const cpl_image *  image_noise,
const cpl_image *  weights,
uves_iterate_position *  pos,
const cpl_table *  sky_map,
cpl_image *  sky_spectrum,
cpl_image *  sky_spectrum_noise 
)
static

Measure and subtract sky.

Parameters:
imageThe input image in (pixel,pixel)-space
image_noiseNoise of input image
weightsweight image
posimage iterator
sky_mapMap of sky/object bins
sky_spectrum(output) The extracted sky
sky_spectrum_noise(output) The extracted sky error bars
Returns:
Sky subtracted image

The errors of the sky-subtracted image are not propagated as the error bars of the sky are assumed to be small. (If needed, noise propagation would be straight-forward to implement because we already compute the error of the estimated sky)

The sky subtracted image has the same bpm as the input image.

The sky is estimated as the median of the pixels defined by the sky map

Definition at line 2586 of file uves_extract.c.

References assure_mem, opt_get_sky(), uves_iterate_finished(), uves_iterate_increment(), and uves_iterate_set_first().

Referenced by opt_extract_sky().

static cpl_table ** opt_sample_spatial_profile ( const cpl_image *  image,
const cpl_image *  weights,
uves_iterate_position *  pos,
int  stepx,
int  sampling_factor,
int *  nbins 
)
static

Sample spatial profile.

Parameters:
imageThe input image in (pixel,pixel)-space
weightsweight image
posimage iterator
stepxArray of size 'nbins'. Measure only every stepx'th bin
sampling_factorBin width (pixels) is 1/sampling_factor.
nbins(output) Size of returned array (number of spatial bins)
Returns:
Array of tables, one table for each spatial bin. When there are bad pixels, a table can be empty.

This function measures the spatial profile from minorder to maxorder using the specified spatial resolution.

Bad pixels are taken into account

Definition at line 2444 of file uves_extract.c.

References assure_mem, passure, uves_iterate_finished(), uves_iterate_increment(), and uves_iterate_set_first().

Referenced by opt_define_sky(), and opt_measure_profile().

static uves_extract_profile * opt_measure_profile ( const cpl_image *  image,
const cpl_image *  image_noise,
const cpl_image *  weights,
uves_iterate_position *  pos,
int  chunk,
int  sampling_factor,
int(*)(const double x[], const double a[], double *result)  f,
int(*)(const double x[], const double a[], double result[])  dfda,
int  M,
const cpl_image *  sky_spectrum,
cpl_table *  info_tbl,
cpl_table **  profile_global 
)
static

Measure spatial profile (all orders)

Parameters:
imageThe sky-subtracted image to extract
image_noiseNoise of image
weightsweight image
posimage iterator
chunkChunk size for object localization
sampling_factoroversampling factor (virtual method)
fThe profile function
dfdaThe derivative of the profile function
MNumber of parameters for the profile function
sky_spectrumAn estimated of the extracted sky (experimental)
info_tbl(output) table with QC parameters for each order
profile_global(output) Table with information on measured profile. If virtual method an empty table is returned
Returns:
The inferred spatial profile

If f is non-NULL, the profile is measured using a 'Zero Resampling' algorithm as described in section 4 of

Mukai, Koji: "Optimal extraction of cross-dispersed spectra" Astronomical Society of the Pacific, Publications (ISSN 0004-6280), vol. 102, Feb. 1990, p. 183-189.

The center and width are allowed to vary as low-degree global polynomials as function of (x, order). For better statisics the signal is collapsed in chunks before applying the analytical fit.

If f is NULL, the "virtual resampling" algorithm is used, as described in section 3 of Mukai(1990).

Definition at line 2745 of file uves_extract.c.

References assure_mem, check, check_nomsg, opt_get_order_width(), opt_measure_profile_order(), opt_sample_spatial_profile(), passure, uves_error_reset, uves_iterate_finished(), uves_iterate_increment(), uves_iterate_set_first(), uves_msg, uves_msg_debug, uves_msg_low, uves_msg_warning, uves_polynomial_delete(), uves_polynomial_evaluate_1d(), uves_polynomial_evaluate_2d(), uves_polynomial_get_degree(), uves_polynomial_new_zero(), uves_polynomial_regression_1d(), uves_polynomial_regression_2d(), uves_polynomial_regression_2d_autodegree(), and uves_polynomial_shift().

Referenced by uves_extract().

static cpl_table * opt_measure_profile_order ( const cpl_image *  image,
const cpl_image *  image_noise,
const cpl_binary *  image_bpm,
uves_iterate_position *  pos,
int  chunk,
int(*)(const double x[], const double a[], double *result)  f,
int(*)(const double x[], const double a[], double result[])  dfda,
int  M,
const cpl_image *  sky_spectrum 
)
static

Measure spatial profile (analytical)

Parameters:
imageThe sky-subtracted image to extract
image_noiseNoise of image
image_bpmTemporary workaround for slow bpm handling in cpl2
poscurrent order
chunkSample x-size, 1 or more
fThe profile function
dfdaThe derivative of the profile function
MNumber of parameters for the profile function
sky_spectrumAn estimate of the extracted sky (experimental)
Returns:
The (possibly empty) order trace table for the current order.

This function fits a profile to chunks along each order.

Next, center(x,order) and width(x,order) are estimated as 2d polynomials while rejecting outliers.

Definition at line 3985 of file uves_extract.c.

References assure_mem, check, check_nomsg, passure, uves_error_reset, uves_iterate_finished(), uves_iterate_increment(), uves_iterate_set_first(), uves_msg_debug, uves_msg_error, uves_msg_warning, uves_polynomial_delete(), uves_polynomial_dump(), uves_polynomial_get_coeff_1d(), uves_polynomial_new_zero(), uves_polynomial_regression_1d(), uves_polynomial_shift(), and uves_pow_int().

Referenced by opt_measure_profile().

static void revise_noise ( cpl_image *  image_noise,
const cpl_binary *  image_bpm,
const uves_propertylist image_header,
uves_iterate_position *  pos,
const cpl_image *  spectrum,
const cpl_image *  sky_spectrum,
const uves_extract_profile *  profile,
enum uves_chip  chip 
)
static

Refine error bars.

Parameters:
image_noisethe noise image to be corrected (only the regions inside the slit are adjusted)
image_bpminput image bad pixels
image_headerheader with CCD noise characteristics
posimage iterator
spectrum(estimate of) extracted spectrum
sky_spectrum(estimate of) extracted sky (normalized to full slit)
profilethe spatial profile
chipCCD chip

The function simulates an image based on the previsouly inferred flux+sky+profile and uses this to improve the error bars

Definition at line 2183 of file uves_extract.c.

References assure_mem, check, uves_define_noise(), uves_iterate_finished(), uves_iterate_increment(), and uves_iterate_set_first().

Referenced by uves_extract().

static int opt_extract ( cpl_image *  image,
const cpl_image *  image_noise,
uves_iterate_position *  pos,
const uves_extract_profile *  profile,
bool  optimal_extract_sky,
double  kappa,
cpl_table *  blemish_mask,
cpl_table *  cosmic_mask,
int *  cr_row,
cpl_table *  profile_table,
int *  prof_row,
cpl_image *  spectrum,
cpl_image *  spectrum_noise,
cpl_image *  weights,
cpl_image *  sky_spectrum,
cpl_image *  sky_spectrum_noise,
double *  sn 
)
static

Optimally extract order using the given the profile.

Parameters:
imageThe image to extract. Outlier pixels will be marked as bad
image_noiseNoise of image
poscurrent order
profileSpatial profile
optimal_extract_skyExtract sky as part of the optimal extraction?
kappaUsed for outlier rejection
blemish_mask(input) Table of blemish pixels locations
cosmic_mask(output) Table of hot pixels
cr_row(output) Pointing to next unused row of cosmic_mask
profile_table(output) Table with detailed profile information
prof_row(output) Pointing to next unused row of profile_table
spectrum(output) The extracted spectrum
spectrum_noise(output) Noise (1 sigma) of spectrum
weights(output) Weight map
sky_spectrum(output) The extracted sky (only used if optimal_extract_sky is set)
sky_spectrum_noise(output) The extracted sky error bars (only used if optimal_extract_sky is set)
sn(output) The approximate S/N ratio of the current order
Returns:
The number of bins extracted

Extract the spectrum using the formulas given by Horne (1986), and do kappa-sigma clipping. Iterate until there are no more outliers.

During extraction hot/cold pixels (usually cosmic rays and 'dead' detector columns) are defined as pixels deviating more than kappa*sigma*sqrt(chi^2/N) from the inferred profile, where sigma is the uncertainty of pixel flux, chi^2/N is the (globally modelled) reduced chi square at the current bin, and kappa is a dimensionless parameter. (Note: if chi^2/N == 1 (a good fit), this is just standard kappa-sigma-clipping. The extra factor sqrt(chi^2/N) is there to make the kappa-sigma-clipping robust against systematically over-/underestimated uncertainties.)

For more details and pseudo-code, refer to the source code.

Definition at line 5276 of file uves_extract.c.

References check, check_nomsg, opt_get_flux_sky_variance(), opt_get_noise_median(), opt_get_order_width(), opt_get_redchisq(), opt_reject_outlier(), uves_iterate_finished(), uves_iterate_increment(), uves_iterate_set_first(), uves_msg_debug, and uves_tostring_cpl_type().

Referenced by uves_extract().

static int opt_get_order_width ( const uves_iterate_position *  pos)
static

Get width of order.

Parameters:
poscurrent order
Returns:
The maximum x-distance of any two pixels in the current order

This function does not take a non-zero extraction offset into account

Definition at line 5129 of file uves_extract.c.

References passure, uves_error_reset, uves_msg_debug, uves_msg_warning, uves_polynomial_evaluate_2d(), and uves_polynomial_solve_2d().

Referenced by opt_extract(), and opt_measure_profile().

static double estimate_sn ( const cpl_image *  image,
const cpl_image *  image_noise,
uves_iterate_position *  pos 
)
static

Estimate the S/N of the input frame.

Parameters:
imagethe input image
image_noisethe input image noise
posimage iterator
Returns:
the S/N estimate or undefined on error

The signal to noise ratio is estimated by calculating the average S/N of central bins across the chip (using linear extraction and sky subtraction)

Definition at line 1550 of file uves_extract.c.

References passure, uves_iterate_finished(), uves_iterate_increment(), uves_iterate_set_first(), and uves_msg_debug.

Referenced by uves_extract().

static double opt_get_sky ( const double *  image_data,
const double *  noise_data,
const double *  weights_data,
uves_iterate_position *  pos,
const cpl_table *  sky_map,
double  buffer_flux[],
double  buffer_noise[],
double *  sky_background_noise 
)
static

Measure sky level (median)

Parameters:
image_dataImage data array
noise_dataNoise of image_data
weights_dataweights array
poscurrent bin
sky_mapRow = 0 (first bin) corresponds to y=ylow
buffer_fluxwork space, large enough to hold the values of all pixels in this bin
buffer_noisework space, as above
sky_background_noise(output) Noise (1 sigma) of returned value
Returns:
The sky level for this bin

The sky level is computed as the median of the sky pixels (as defined by selected rows in the sky_map table). If no such pixel exists, the sky is set to the minimum flux along slit.

The computed sky level is not normalized to the full slit (which makes it easier to subtract the sky from each pixel).

If there are no good pixels, the sky is set to zero, and the noise to 1.

Definition at line 5636 of file uves_extract.c.

References uves_tools_get_median().

Referenced by opt_subtract_sky().

static double opt_get_noise_median ( const double *  noise_data,
const cpl_binary *  image_bpm,
uves_iterate_position *  pos,
double  noise_buffer[] 
)
static

Measure median noise level of extraction bin.

Parameters:
noise_dataNoise data array
image_bpmimage bad pixel map
poscurrent bin
noise_bufferarray large enough to hold all values across the slit
Returns:
The median of the errorbars

Definition at line 5752 of file uves_extract.c.

References uves_tools_get_median().

Referenced by opt_extract().

static double opt_get_flux_sky_variance ( const double *  image_data,
const double *  noise_data,
double *  weights_data,
uves_iterate_position *  pos,
const uves_extract_profile *  profile,
bool  optimal_extract_sky,
double  median_noise,
double *  variance,
double *  sky_background,
double *  sky_background_noise 
)
static

Get flux, sky and variances of current bin.

Parameters:
image_dataImage data array
noise_dataNoise data array
weights_dataWeights data array This is updated to contain the new weight. Pixels with already negative weight (i.e. bad pixels) are ignored.
poscurrent bin
profileSpatial profile
optimal_extract_skyAlso optimally extract sky (true) or just the object flux (false)
median_noiseIf positive, the 'raw' pixel flux errorbars are raised to this value. If negative, the 'raw' errorbars are used unmodified. (This is to allow robustness against cold pixels which would otherwise get too much weight before they are rejected.)
variance(output) Variance of returned value
sky_background(output) Extracted sky (if optimal_extract_sky is set)
sky_background_noise(output) Error (1 sigma) of estimated sky (if optimal_extract_sky is set)
Returns:
The optimally extracted flux

If the optimal_extract_sky flag is not set, the current bin is extracted using Horne(1986)'s optimal extraction formulas:

F = [ sum_i (profile_i^2/variance_i * flux_i/profile_i) ] / [ sum_i (profile_i^2/variance_i) ]

Variance = 1 / [ sum_i (profile_i^2/variance_i) ]

If the optimal_extract_sky flag is set, generalized formulas are used for the optimal object and sky flux. Horne's formulas were derived by minimizing

chi^2 = sum_i (flux_i - F * profile_i)^2/variance_i

with respect to F, then using the error propagation formula to get the Variance while noting that Variance(flux_i) = variance_i. (profile_i and variance_i are assumed exactly known, i.e. to have zero variance).

To generalize the formulas to include the optimal determination of the sky, we simply add a constant sky background, S, to the model and repeat the calculation. Then, minimization of

chi^2 = sum (flux_i - (S + F * profile_i))^2/variance_i

with respect to F and S leads to (the calculation is somewhat tedious but straightforward)

F = [ (sum_i 1/variance_i ) sum_i profile_i flux_i / variance_i - (sum_i profile_i/variance_i) sum_i flux_i / variance_i ] / Denominator

S = [ (sum_i profile_i^2/variance_i) sum_i flux_i / variance_i - (sum_i profile_i/variance_i) sum_i profile_i flux_i / variance_i ] / Denominator

Variance(F) = (sum_i 1 / variance_i) / Denominator Variance(S) = (sum_i profile_i / variance_i) / Denominator

where Denominator is short for

(sum_i 1/variance_i) sum_i profile_i^2/variance_i - (sum_i profile_i/variance_i)^2

These formulas has been shown to give the same results as a two-parameter LM chi^2 minimization

Definition at line 5856 of file uves_extract.c.

Referenced by opt_extract().

static bool opt_reject_outlier ( const double *  image_data,
const double *  noise_data,
cpl_binary *  image_bpm,
double *  weights_data,
uves_iterate_position *  pos,
const uves_extract_profile *  profile,
double  kappa,
double  flux,
double  sky_background,
double  red_chisq,
cpl_table *  cosmic_mask,
int *  cr_row,
int *  hot_pixels,
int *  cold_pixels 
)
static

Find and reject outlier pixel.

Parameters:
image_dataImage data array
noise_dataNoise data array
image_bpmImage bad pixels map. Outliers will be marked as bad.
weights_dataWeights data array
poscurrent bin,
profileSpatial profile
kappaRejection parameter
fluxThe extracted flux
sky_backgroundThe extracted sky, (zero if input frame was already sky-subtracted)
red_chisqreduced chi square, must be positive
cosmic_maskTable of cosmic ray hits. Will be updated if a positive outlier was found.
cr_rowFirst unused row of cosmic_mask
hot_pixelsCurrent number of hot pixels in this order
cold_pixelsCurrent number of cold pixels in this order
Returns:
True iff an outlier pixel was found.

If an outlier is found, its weight is set to negative.

Definition at line 6007 of file uves_extract.c.

References check, and uves_msg_debug.

Referenced by opt_extract().

static double opt_get_redchisq ( const uves_extract_profile *  profile,
const uves_iterate_position *  pos 
)
static

Get reduced chi^2 for current bin.

Parameters:
profileobject spatial profile
poscurrent bin
Returns:
reduced chi^2 for this bin, as previously inferred from global fit (but always 1 or more). If virtual method, return 1.

Definition at line 6127 of file uves_extract.c.

References uves_polynomial_evaluate_1d(), and uves_polynomial_evaluate_2d().

Referenced by opt_extract().

static polynomial * repeat_orderdef ( const cpl_image *  image,
const cpl_image *  image_noise,
const polynomial guess_locations,
int  minorder,
int  maxorder,
slit_geometry  sg,
cpl_table *  info_tbl 
)
static

Refine order definition using the science frame.

Parameters:
imageobject frame
image_noiseimage error bars
guess_locationsprevious solution
minorderminimum order number
maxordermaximum order number
sgslit length
info_tbltable with QC parameters for each order
Returns:
improved solution

This function repeats the order definition step usually performed by the order-definition recipe.

This implementation is very much simpler than the order-definition recipe, because we already know the approximate order location across the entire chip. (On the contrary, the order-definition recipe works ab nihil).

Definition at line 6173 of file uves_extract.c.

References check, uves_error_reset, uves_gauss(), uves_gauss_derivative(), uves_msg, uves_msg_debug, uves_msg_warning, uves_polynomial_delete(), uves_polynomial_duplicate(), uves_polynomial_evaluate_2d(), and uves_polynomial_regression_2d_autodegree().

Referenced by uves_extract().

static double detect_ripples ( const cpl_image *  spectrum,
const uves_iterate_position *  pos,
double  sn 
)
static

Try to detect and warn about any optimal extraction ripples (happening if oversampling factor is too small)

Parameters:
spectrumextracted spectrum
posimage iterator containing current order
snS/N for this order
Returns:
ratio of estimated ripple amplitude to spectrum error bars, or -1 if estimation failed

Definition at line 1407 of file uves_extract.c.

References check, uves_msg_debug, and uves_polynomial_derivative_2d().

Referenced by uves_extract().

cpl_parameterlist* uves_extract_define_parameters ( void  )

Define recipe parameters used for extraction.

Returns:
The parameters for this step

The parameters defined are method, kappa. See source code or 'esorex –man-page' for a description of each parameter.

Definition at line 264 of file uves_extract.c.

extract_method uves_get_extract_method ( const cpl_parameterlist *  parameters,
const char *  context,
const char *  subcontext 
)

Read extraction method from parameter list.

Parameters:
parametersThe parameter list
contextContext of parameter (or NULL)
subcontextSubcontext of parameter
Returns:
The extraction method as read from the parameter context.subcontext.method

Definition at line 462 of file uves_extract.c.

References check.

Referenced by uves_extract(), and uves_reduce().

cpl_image* uves_extract ( cpl_image *  image,
cpl_image *  image_noise,
const uves_propertylist image_header,
const cpl_table *  ordertable,
const polynomial order_locations_raw,
double  slit_length,
double  offset,
const cpl_parameterlist *  parameters,
const char *  context,
const char *  mode,
bool  extract_partial,
bool  debug_mode,
enum uves_chip  chip,
uves_propertylist **  header,
cpl_image **  spectrum_noise,
cpl_image **  sky_spectrum,
cpl_image **  sky_spectrum_noise,
cpl_table **  cosmic_mask,
cpl_image **  cosmic_image,
cpl_table **  profile_table,
cpl_image **  weights,
cpl_table **  info_tbl,
cpl_table **  order_trace 
)

Extract a spectrum.

Parameters:
imageThe input image in (pixel,pixel)-space. If optimal extraction, outlier pixels will be marked as bad
image_noiseThe input image noise. Will be improved during an optimal extraction. If NULL, a constant noise level is assumed.
image_headerthe input image FITS header (optimal extraction only), or NULL.
ordertableThe order table
order_locations_rawBivariate polynomial defining the positions of the relative orders Will be refined for method = optimal/virtual.
slit_lengthLength (in pixels) of area to extract
offsetOffset (in pixels) of slit. Ignored if 2d extraction
parametersParameter list defining the extraction method and kappa (rejection threshold for optimal extraction). Add parameters by calling uves_propagate_parameters_step() from the recipe_create() function
contextUse parameters belonging to this context
extract_partialFlag indicating if an extraction bin which is partially outside the image should be extracted (true) or rejected (false)
debug_modedebug_mode mode ? if yes generate extra output
chipCCD chip (optimal extraction only)
header(output) If non-NULL, FITS header of returned spectrum
spectrum_noise(output) If non-NULL, the noise of the extracted spectrum is computed and returned through this parameter. Requires input noise image to be specified.
sky_spectrum(output) Used only in optimal extraction. This is the extracted sky.
sky_spectrum_noise(output) Used only in optimal extraction. This is the noise (1 sigma) of the extracted sky. optimal extraction
cosmic_mask(output) Used only in optimal extraction. A table of cosmic ray hits is returned.
cosmic_image(output) Used only in optimal extraction. The cosmic ray table converted to an image
profile_table(output) Used only in optimal extraction. If non-NULL, table containing detailed profiled information. (warning: this table has a row for each combination of (order, bin, slit-position) and as such is often rather big)
weights(output) Used only in optimal+weighted extraction. If this points to NULL, a new weight image is created, otherwise the existing weight image is used when extracting.
info_tbl(output) table with info to QC log. Computed if optimal, average or linear extraction. May be NULL
order_trace(output) Used only in optimal extraction. Table containing the order trace.
Returns:
The extracted spectrum in (pixel, order)-space

The minimum and maximum (relative) order numbers are read from the order table. The order locations are inferred from the polynomial order_locations_raw .

Bad pixel handling: In average extraction mode, bad pixels are ignored (i.e. don't contribute to the average). In linear extraction mode, the good pixels are summed, and the flux is always normalized to the slit length. In optimal extraction mode, pixels with residuals larger than kappa sigma are rejected (sigma is the uncertainty of the pixel flux)

If the flag extract_partial is true, an extraction bin which lies partially outside the image will be extracted (and the flux normalized to the full slit length in case of linear extraction). This flag should be set to false if the object spatial profile is not nearly constant across the extraction slit, otherwise an artificial increase/drop in flux will appear near the edge of the image. This flag is ignored for optimal extraction.

Bins which are not extracted (outside the image) are set to 'bad' in the final spectrum image.

  • The extraction area is a parallelogram. The length of the two vertical sides is still slit_length, but the slope of the two (nearly) horizontal sides is equal to the local order line slope.
  • Extraction bins that are partially outside of the image are not extracted (i.e. the flux is set to zero).
  • When extracting a fraction (less than 1) of a pixel, the (unknown) order profile is approximated using a linear interpolation of the fluxes of the current pixel and the two neighbouring pixels. This reduces artificial ripples (periodic variation of the flux) in the extracted spectrum.

Definition at line 569 of file uves_extract.c.

References assure_mem, check, check_nomsg, detect_ripples(), estimate_sn(), extract_order_simple(), opt_extract(), opt_extract_sky(), opt_measure_profile(), passure, repeat_orderdef(), revise_noise(), uves_create_image(), uves_gauss(), uves_gauss_derivative(), uves_get_extract_method(), uves_initialize_image_header(), uves_iterate_delete(), uves_iterate_finished(), uves_iterate_increment(), uves_iterate_new(), uves_iterate_set_first(), uves_moffat(), uves_moffat_derivative(), uves_msg, uves_msg_debug, uves_msg_low, uves_msg_warning, uves_polynomial_delete(), uves_polynomial_duplicate(), and uves_polynomial_get_dimension().

Referenced by extract_ff_rebin_merge(), and test_extract().