UVES Pipeline Reference Manual  5.4.6
uves_utils.h
1 /*
2  * This file is part of the ESO UVES Pipeline
3  * Copyright (C) 2004,2005 European Southern Observatory
4  *
5  * This program is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation; either version 2 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program; if not, write to the Free Software
17  * Foundation, 51 Franklin St, Fifth Floor, Boston, MA 02111-1307 USA
18  */
19 
20 /*
21  * $Author: amodigli $
22  * $Date: 2013-04-16 15:35:24 $
23  * $Revision: 1.121 $
24  * $Name: not supported by cvs2svn $
25  *
26  */
27 #ifndef UVES_UTILS_H
28 #define UVES_UTILS_H
29 
30 
31 #ifdef HAVE_CONFIG_H
32 # include <config.h>
33 #endif
34 #include <uves_cpl_size.h>
35 /*-----------------------------------------------------------------------------
36  Includes
37  -----------------------------------------------------------------------------*/
38 
39 #include <uves_utils_polynomial.h>
40 #include <uves_extract_iterate.h>
41 #include <uves_extract_profile.h>
42 #include <uves_chip.h>
43 
44 #include <cpl.h>
45 #include <math.h>
46 
47 /*-----------------------------------------------------------------------------
48  Defines
49  -----------------------------------------------------------------------------*/
50 
51 /* If __func__ is not declared, use a default function name */
52 #if defined HAVE_DECL___FUNC__ && !HAVE_DECL___FUNC__
53 //static const char __func__[] = "<fctid>";
54 #ifndef __func__
55 #define __func__ "<fct.id>"
56 #endif
57 #endif
58 
59 /*
60  * The purpose of this target is to
61  * decrease the amount of messages
62  * printed at the debug level.
63  *
64  * If set to non-zero, even more messages
65  * are printed at the debug level
66  * (sometimes 50 - 100 MB)
67  *
68  */
69 #ifndef WANT_BIG_LOGFILE
70 #define WANT_BIG_LOGFILE 0
71 #endif
72 
73 /*
74  * Set to 1 to show timing
75  * information on msg-level = info
76  */
77 #ifndef WANT_TIME_MEASURE
78 #define WANT_TIME_MEASURE 0
79 #endif
80 
81 
82 #if WANT_TIME_MEASURE
83 #define UVES_TIME_START(what) uves_msg("Timing (%s, l%d) %s start", \
84  __FILE__, __LINE__, what)
85 #define UVES_TIME_END uves_msg("Timing (%s, l%d) end", \
86  __FILE__, __LINE__)
87 #else
88 #define UVES_TIME_START(what) uves_msg_debug("Timing (%s, l%d) %s start", \
89  __FILE__, __LINE__, what)
90 #define UVES_TIME_END uves_msg_debug("Timing (%s, l%d) end", \
91  __FILE__, __LINE__)
92 #endif
93 
94 
95 #ifndef stringify
96 #ifndef make_str
97 #define stringify(X) #X
98 #define make_str(X) stringify(X)
99 #endif
100 #endif
101 
102 #define TWOSQRT2LN2 2.35482004503095
103 
104 #ifndef M_PI
105 #define M_PI 3.1415926535897932384626433832795
106 #endif
107 
108 #define SPEED_OF_LIGHT 299792458 /* SI-units */
109 
110 #define COS_DEG(x) cos(((x)/180)*M_PI)
111 #define SIN_DEG(x) sin(((x)/180)*M_PI)
112 #define ACOS_DEG(x) (acos(x)*180/M_PI)
113 
114 /*-----------------------------------------------------------------------------
115  Prototypes
116  -----------------------------------------------------------------------------*/
117 
118 cpl_image *
119 uves_create_image(uves_iterate_position *pos, enum uves_chip chip,
120  const cpl_image *spectrum, const cpl_image *sky,
121  const cpl_image *cosmic_image,
122  const uves_extract_profile *profile,
123  cpl_image **image_noise, uves_propertylist **image_header);
124 cpl_frameset *
125 uves_frameset_extract(const cpl_frameset *frames,const char *tag);
126 
127 const char*
128 uves_string_tolower(char* s);
129 const char*
130 uves_string_toupper(char* s);
131 
132 double uves_gaussrand(void);
133 double uves_pow_int(double x, int y);
134 
135 /*----------------------------------------------------------------------------*/
144 /*----------------------------------------------------------------------------*/
145 static inline long
146 uves_round_double(double x)
147 {
148  return (x >=0) ? (long)(x+0.5) : (long)(x-0.5);
149 }
150 
151 /*----------------------------------------------------------------------------*/
160 /*----------------------------------------------------------------------------*/
161 static inline double
162 uves_max_double(double x, double y)
163 {
164  return (x >=y) ? x : y;
165 }
166 /*----------------------------------------------------------------------------*/
175 /*----------------------------------------------------------------------------*/
176 static inline int
177 uves_max_int(int x, int y)
178 {
179  return (x >=y) ? x : y;
180 }
181 
182 /*----------------------------------------------------------------------------*/
191 /*----------------------------------------------------------------------------*/
192 static inline double
193 uves_min_double(double x, double y)
194 {
195  return (x <=y) ? x : y;
196 }
197 /*----------------------------------------------------------------------------*/
206 /*----------------------------------------------------------------------------*/
207 static inline int
208 uves_min_int(int x, int y)
209 {
210  return (x <=y) ? x : y;
211 }
212 
213 /*----------------------------------------------------------------------------*/
224 /*----------------------------------------------------------------------------*/
225 static inline double
226 uves_error_fraction(double x, double y, double dx, double dy)
227 {
228  /* Error propagation:
229  * sigma(x/y)^2 = (1/y sigma(x))^2 + (-x/y^2 sigma(y))^2
230  */
231  return sqrt( dx*dx/(y*y) + x*x*dy*dy/(y*y*y*y) );
232 }
233 
234 
235 const char *uves_get_license(void);
236 cpl_error_code uves_get_version(int *major, int *minor, int *micro);
237 int uves_get_version_binary(void);
238 
239 char * uves_initialize(cpl_frameset *frames, const cpl_parameterlist *parlist,
240  const char *recipe_id, const char *short_descr);
241 cpl_error_code uves_end(const char *recipe_id, const cpl_frameset *frames);
242 
243 uves_propertylist *uves_initialize_image_header(const char *ctype1, const char *ctype2, const char *cunit1, const char *cunit2,
244  const char *bunit,const double bscale,
245  double crval1 , double crval2,
246  double crpix1 , double crpix2,
247  double crdelt1, double crdelt2);
248 
249 cpl_parameterlist*
250 uves_parameterlist_duplicate(const cpl_parameterlist* pin);
251 
252 cpl_image *uves_define_noise(const cpl_image *image, const uves_propertylist *image_header,
253  int ncom, enum uves_chip);
254 cpl_image *uves_average_images(const cpl_image *image1, const cpl_image *noise1,
255  const cpl_image *image2, const cpl_image *noise2,
256  cpl_image **noise);
257 
258 
259 cpl_error_code uves_subtract_bias(cpl_image *image, const cpl_image *master_bias);
260 cpl_error_code uves_subtract_dark(cpl_image *image, const uves_propertylist *image_header,
261  const cpl_image *master_dark,
262  const uves_propertylist *mdark_header);
263 
264 polynomial *
266  const char *X1, const char *X2, const char *Y,
267  const char *sigmaY,
268  const char *polynomial_fit,
269  const char *residual_square,
270  const char *variance_fit,
271  double *mean_squared_error, double *red_chisq,
272  polynomial **variance, double kappa,
273  int maxdeg1, int maxdeg2, double min_rms,
274  double min_reject,
275  bool verbose,
276  const double *min_val,
277  const double *max_val,
278  int npos, double positions[][2]);
279 
280 polynomial *
281 uves_polynomial_regression_2d(cpl_table *t,
282  const char *X1, const char *X2, const char *Y,
283  const char *sigmaY,
284  int degree1, int degree2,
285  const char *polynomial_fit, const char *residual_square,
286  const char *variance_fit,
287  double *mse, double *red_chisq,
288  polynomial **variance, double kappa,
289  double min_reject);
290 
292  const char *X, const char *Y, const char *sigmaY,
293  int degree,
294  const char *polynomial_fit, const char *residual_square,
295  double *mean_squared_error, const double kappa);
296 
297 const char *uves_remove_string_prefix(const char *s, const char *prefix);
298 
299 double uves_spline_hermite_table( double xp, const cpl_table *t, const char *column_x,
300  const char *column_y, int *istart );
301 
302 double uves_spline_hermite( double xp, const double *x, const double *y, int n, int *istart );
303 
304 double uves_spline_cubic(double xp, double *x, float *y, float *y2, int n, int *kstart );
305 
306 int uves_absolute_order(int first_abs_order, int last_abs_order, int relative_order);
307 
308 double uves_average_reject(cpl_table *t,
309  const char *column,
310  const char *residual2,
311  double kappa);
312 
313 
314 cpl_table *uves_ordertable_traces_new(void);
315 cpl_error_code uves_ordertable_traces_add(cpl_table *traces,
316  int fibre_ID, double fibre_offset, int fibre_mask);
317 bool uves_table_is_sorted_double(const cpl_table *t, const char *column, const bool reverse);
318 
319 int uves_moffat(const double x[], const double a[], double *result);
320 int uves_moffat_derivative(const double x[], const double a[], double result[]);
321 int uves_gauss(const double x[], const double a[], double *result);
322 int uves_gauss_derivative(const double x[], const double a[], double result[]);
323 int uves_gauss_linear(const double x[], const double a[], double *result);
324 int uves_gauss_linear_derivative(const double x[], const double a[], double result[]);
325 void uves_check_version(void);
326 void uves_frameset_dump(cpl_frameset* set);
327 cpl_error_code
328 uves_rcosmic(cpl_image* ima,
329  cpl_image** flt,
330  cpl_image** out,
331  cpl_image** msk,
332  const double sky,
333  const double ron,
334  const double gain,
335  const int ns,
336  const double rc);
337 
338 cpl_image *
339 uves_image_smooth_x(cpl_image * inp, const int r);
340 cpl_image *
341 uves_image_smooth_y(cpl_image * inp, const int r);
342 
343 cpl_image *
344 uves_image_smooth_mean_x(cpl_image * inp, const int r);
345 
346 cpl_image *
347 uves_image_smooth_median_x(cpl_image * inp, const int r);
348 cpl_image *
349 uves_image_smooth_fft(cpl_image * inp, const int fx);
350 
351 cpl_image *
352 uves_ksigma_stack(const cpl_imagelist *imlist, double klow, double khigh, int kiter);
353 
354 
355 cpl_image *
356 uves_flat_create_normalized_master(cpl_imagelist * flats,
357  const cpl_table *ordertable,
358  const polynomial* order_locations,
359  const cpl_vector* gain_vals,
360  double* fnoise);
361 
362 cpl_image *
363 uves_flat_create_normalized_master2(cpl_imagelist * flats,
364  const cpl_table *ordertable,
365  const polynomial* order_locations,
366  const cpl_image* mflat);
367 
368 cpl_vector *
369 uves_imagelist_get_clean_mean_levels(cpl_imagelist* iml, double kappa);
370 cpl_error_code
371 uves_imagelist_subtract_values(cpl_imagelist** iml, cpl_vector* values);
372 cpl_image *
373 uves_get_wave_map(cpl_image * ima_sci,
374  const char *context,
375  const cpl_parameterlist *parameters,
376  const cpl_table *ordertable,
377  const cpl_table *linetable,
378  const polynomial* order_locations,
379  const polynomial *dispersion_relation,
380  const int first_abs_order,
381  const int last_abs_order,
382  const int slit_size);
383 
384 cpl_image*
385 uves_image_mflat_detect_blemishes(const cpl_image* flat,
386  const uves_propertylist* head);
387 
388 
389 cpl_error_code
390 uves_table_remove_units(cpl_table **table);
391 cpl_error_code
392 uves_table_unify_units(cpl_table **table2, cpl_table **table1);
393 cpl_error_code
394 uves_tablenames_unify_units(const char* tname2, const char* tname1);
395 cpl_error_code
396 uves_tablename_remove_units(const char* tname);
397 
398 #endif
const char * uves_string_tolower(char *s)
Convert all uppercase characters in a string into lowercase characters.
Definition: uves_utils.c:1527
bool uves_table_is_sorted_double(const cpl_table *t, const char *column, const bool reverse)
Determine if a table is sorted.
Definition: uves_utils.c:3847
cpl_image * uves_get_wave_map(cpl_image *ima_sci, const char *context, const cpl_parameterlist *parameters, const cpl_table *ordertable, const cpl_table *linetable, const polynomial *order_locations, const polynomial *dispersion_relation, const int first_abs_order, const int last_abs_order, const int slit_size)
Generates wave map.
Definition: uves_utils.c:452
cpl_error_code uves_rcosmic(cpl_image *ima, cpl_image **flt, cpl_image **out, cpl_image **msk, const double sky, const double ron, const double gain, const int ns, const double rc)
Remove cosmic ray events on single ccd exposure and replace them by interpolation on neighbourhood pi...
Definition: uves_utils.c:162
cpl_image * uves_define_noise(const cpl_image *image, const uves_propertylist *image_header, int ncom, enum uves_chip)
Create noise image.
Definition: uves_utils.c:2226
cpl_image * uves_flat_create_normalized_master(cpl_imagelist *flats, const cpl_table *ordertable, const polynomial *order_locations, const cpl_vector *gain_vals, double *fnoise)
Stack images using k-sigma clipping.
Definition: uves_utils.c:702
int uves_absolute_order(int first_abs_order, int last_abs_order, int relative_order)
Get the absolute order number.
Definition: uves_utils.c:2491
const char * uves_get_license(void)
Get the pipeline copyright and license.
Definition: uves_utils.c:1676
int uves_gauss_linear(const double x[], const double a[], double *result)
Evaluate a gaussian with linear background.
Definition: uves_utils.c:4411
double uves_pow_int(double x, int y)
Calculate x to the y'th.
Definition: uves_utils.c:1593
cpl_table * uves_ordertable_traces_new(void)
Create the table that describes fibre traces.
Definition: uves_utils.c:3898
cpl_image * uves_flat_create_normalized_master2(cpl_imagelist *flats, const cpl_table *ordertable, const polynomial *order_locations, const cpl_image *mflat)
Stack images using k-sigma clipping.
Definition: uves_utils.c:551
cpl_error_code uves_tablename_remove_units(const char *tname)
Remove column units from a table.
Definition: uves_utils.c:3954
cpl_error_code uves_subtract_bias(cpl_image *image, const cpl_image *master_bias)
Subtract bias.
Definition: uves_utils.c:2394
int uves_gauss_derivative(const double x[], const double a[], double result[])
Evaluate the derivatives of a gaussian.
Definition: uves_utils.c:4346
double uves_average_reject(cpl_table *t, const char *column, const char *residual2, double kappa)
Get average with iterative rejection.
Definition: uves_utils.c:2513
cpl_image * uves_image_mflat_detect_blemishes(const cpl_image *flat, const uves_propertylist *head)
Flag blemishes in a flat image.
Definition: uves_utils.c:5176
cpl_error_code uves_table_unify_units(cpl_table **table2, cpl_table **table1)
Unify column units of table2 to table1.
Definition: uves_utils.c:4044
cpl_error_code uves_tablenames_unify_units(const char *tname2, const char *tname1)
Unify column units in tables.
Definition: uves_utils.c:3980
cpl_error_code uves_subtract_dark(cpl_image *image, const uves_propertylist *image_header, const cpl_image *master_dark, const uves_propertylist *mdark_header)
Subtract dark.
Definition: uves_utils.c:2438
uves_propertylist * uves_initialize_image_header(const char *ctype1, const char *ctype2, const char *cunit1, const char *cunit2, const char *bunit, const double bscale, double crval1, double crval2, double crpix1, double crpix2, double crdelt1, double crdelt2)
Initialize image header.
Definition: uves_utils.c:2174
double uves_gaussrand(void)
Pseudo-random gaussian distributed number.
Definition: uves_utils.c:3645
double uves_spline_hermite_table(double xp, const cpl_table *t, const char *column_x, const char *column_y, int *istart)
Spline interpolation based on Hermite polynomials.
Definition: uves_utils.c:3683
int uves_gauss(const double x[], const double a[], double *result)
Evaluate a gaussian.
Definition: uves_utils.c:4291
int uves_moffat(const double x[], const double a[], double *result)
Evaluate a Moffat.
Definition: uves_utils.c:4240
polynomial * uves_polynomial_regression_2d(cpl_table *t, const char *X1, const char *X2, const char *Y, const char *sigmaY, int degree1, int degree2, const char *polynomial_fit, const char *residual_square, const char *variance_fit, double *mse, double *red_chisq, polynomial **variance, double kappa, double min_reject)
Fit a 2d polynomial to three table columns.
Definition: uves_utils.c:2869
int uves_gauss_linear_derivative(const double x[], const double a[], double result[])
Evaluate the derivatives of a gaussian with linear background.
Definition: uves_utils.c:4470
polynomial * uves_polynomial_regression_2d_autodegree(cpl_table *t, const char *X1, const char *X2, const char *Y, const char *sigmaY, const char *polynomial_fit, const char *residual_square, const char *variance_fit, double *mean_squared_error, double *red_chisq, polynomial **variance, double kappa, int maxdeg1, int maxdeg2, double min_rms, double min_reject, bool verbose, const double *min_val, const double *max_val, int npos, double positions[][2])
Fit a 2d polynomial to three table columns.
Definition: uves_utils.c:3305
cpl_vector * uves_imagelist_get_clean_mean_levels(cpl_imagelist *iml, double kappa)
Computes kappa-sigma clean mean (free bad pixels) for each input image of the input imagelist...
Definition: uves_utils.c:5005
const char * uves_remove_string_prefix(const char *s, const char *prefix)
Remove named prefix from string.
Definition: uves_utils.c:3612
cpl_image * uves_create_image(uves_iterate_position *pos, enum uves_chip chip, const cpl_image *spectrum, const cpl_image *sky, const cpl_image *cosmic_image, const uves_extract_profile *profile, cpl_image **image_noise, uves_propertylist **image_header)
Reconstruct echelle image from spectrum.
Definition: uves_utils.c:4534
cpl_error_code uves_table_remove_units(cpl_table **table)
Remove column units from a table.
Definition: uves_utils.c:4012
cpl_image * uves_average_images(const cpl_image *image1, const cpl_image *noise1, const cpl_image *image2, const cpl_image *noise2, cpl_image **noise)
Optimally average images.
Definition: uves_utils.c:2046
char * uves_initialize(cpl_frameset *frames, const cpl_parameterlist *parlist, const char *recipe_id, const char *short_descr)
Recipe initialization.
Definition: uves_utils.c:1910
int uves_moffat_derivative(const double x[], const double a[], double result[])
Evaluate Moffat derivative.
Definition: uves_utils.c:4259
cpl_error_code uves_ordertable_traces_add(cpl_table *traces, int fibre_ID, double fibre_offset, int fibre_mask)
Add a trace.
Definition: uves_utils.c:3925
polynomial * uves_polynomial_regression_1d(cpl_table *t, const char *X, const char *Y, const char *sigmaY, int degree, const char *polynomial_fit, const char *residual_square, double *mean_squared_error, const double kappa)
Fit a 1d polynomial to two table columns.
Definition: uves_utils.c:2590
cpl_image * uves_ksigma_stack(const cpl_imagelist *imlist, double klow, double khigh, int kiter)
Stack images using k-sigma clipping.
Definition: uves_utils.c:356
cpl_error_code uves_end(const char *recipe_id, const cpl_frameset *frames)
Recipe termination.
Definition: uves_utils.c:1840
cpl_error_code uves_get_version(int *major, int *minor, int *micro)
Get UVES library version number.
Definition: uves_utils.c:1641
const char * uves_string_toupper(char *s)
Convert all lowercase characters in a string into uppercase characters.
Definition: uves_utils.c:1493
double uves_spline_hermite(double xp, const double *x, const double *y, int n, int *istart)
Spline interpolation based on Hermite polynomials.
Definition: uves_utils.c:3721
cpl_parameterlist * uves_parameterlist_duplicate(const cpl_parameterlist *pin)
Extract frames with given tag from frameset.
Definition: uves_utils.c:1461
int uves_get_version_binary(void)
Get UVES library binary version number.
Definition: uves_utils.c:1660
cpl_error_code uves_imagelist_subtract_values(cpl_imagelist **iml, cpl_vector *values)
Subtract from input imagelist values specified in input vector.
Definition: uves_utils.c:5046
double uves_spline_cubic(double xp, double *x, float *y, float *y2, int n, int *kstart)
Natural cubic-spline interpolation.
Definition: uves_utils.c:3793
cpl_frameset * uves_frameset_extract(const cpl_frameset *frames, const char *tag)
Extract frames with given tag from frameset.
Definition: uves_utils.c:1557