IIINSTRUMENT Pipeline Reference Manual  1.3.12b
detmon_lg.h
1 /* $Id: detmon_lg.h,v 1.4 2013-06-18 13:34:19 jtaylor Exp $
2  *
3  * This file is part of the irplib package
4  * Copyright (C) 2002, 2003 European Southern Observatory
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02111-1307 USA
19  */
20 
21 /*
22  * $Author: jtaylor $
23  * $Date: 2013-06-18 13:34:19 $
24  * $Revision: 1.4 $
25  * $Name: not supported by cvs2svn $
26  */
27 
28 #ifndef IRPLIB_DETMON_LG_H
29 #define IRPLIB_DETMON_LG_H
30 
31 /*----------------------------------------------------------------------------
32  Includes
33  ----------------------------------------------------------------------------*/
34 
35 #include <cpl.h>
36 
37 /*----------------------------------------------------------------------------
38  Defines
39  ----------------------------------------------------------------------------*/
40 /* Define here the DO.CATG keywords */
41 #define DETMON_LG_ON_RAW_OLD "ON_RAW"
42 #define DETMON_LG_OFF_RAW_OLD "OFF_RAW"
43 #define DETMON_LG_ON_RAW_NEW "DETMON_LAMP_ON"
44 #define DETMON_LG_OFF_RAW_NEW "DETMON_LAMP_OFF"
45 
46 
47 #define NIR TRUE
48 #define OPT FALSE
49 
50 #define DETMON_QC_COUNTS_MIN "ESO QC COUNTS MIN"
51 #define DETMON_QC_COUNTS_MIN_C "Minimum median value used in linearity test (in a user defined region) [ADU]"
52 
53 #define DETMON_QC_COUNTS_MAX "ESO QC COUNTS MAX"
54 #define DETMON_QC_COUNTS_MAX_C "Maximum median value used in linearity test (in a user defined region) [ADU]"
55 
56 #define DETMON_QC_CONAD "ESO QC CONAD"
57 #define DETMON_QC_CONAD_C "Conversion from e- to ADUs [ADU/e-]"
58 
59 #define DETMON_QC_CONAD_CORR "ESO QC CONAD CORR"
60 #define DETMON_QC_CONAD_CORR_C "CONAD value taken QC.AUTOCORR into account [ADU/e-]"
61 
62 #define DETMON_QC_GAIN "ESO QC GAIN"
63 #define DETMON_QC_GAIN_C "GAIN (see QC.METHOD) [e-/ADU]"
64 
65 #define DETMON_QC_GAIN_MSE "ESO QC GAIN MSE"
66 #define DETMON_QC_GAIN_MSE_C "Measured Squared error in GAIN computation"
67 
68 #define DETMON_QC_RON "ESO QC RON"
69 #define DETMON_QC_RON_C "RON obtained as independent term (PTC method)"
70 
71 #define DETMON_QC_AUTOCORR "ESO QC AUTOCORR"
72 #define DETMON_QC_AUTOCORR_C "Autocorrelation factor computed as sum of " \
73  "all pixels in autocorrelation image"
74 #define DETMON_QC_GAIN_CORR "ESO QC GAIN CORR"
75 #define DETMON_QC_GAIN_CORR_C "GAIN taken QC.AUTOCORR into account [e-/ADU]"
76 
77 #define DETMON_QC_LAMP_FLUX "ESO QC LAMP FLUX"
78 #define DETMON_QC_LAMP_FLUX_C "Lamp flux"
79 
80 #define DETMON_QC_NUM_BPM "ESO QC NUM BPM"
81 #define DETMON_QC_NUM_BPM_C "Number of bad pixels detected according to "\
82  "polynomial information"
83 
84 #define DETMON_QC_NUM_BPM_AVG "ESO QC NUM BPM AVG"
85 #define DETMON_QC_NUM_BPM_AVG_C "Avg of ESO QC NUM BPM"
86 
87 #define DETMON_QC_LAMP_STAB "ESO QC LAMP STAB"
88 #define DETMON_QC_LAMP_STAB_C "Lamp stability"
89 
90 #define DETMON_QC_METHOD "ESO QC METHOD"
91 #define DETMON_QC_METHOD_C "Method applied to compute GAIN"
92 
93 #define DETMON_QC_LIN_EFF "ESO QC LIN EFF"
94 #define DETMON_QC_LIN_EFF_C "Effective non-linearity correction"
95 
96 #define DETMON_QC_LIN_EFF_FLUX "ESO QC LIN EFF FLUX"
97 #define DETMON_QC_LIN_EFF_FLUX_C "FLux level at which effective non-linearity correction is computed"
98 
99 #define DETMON_QC_LIN_COEF "ESO QC LIN COEF"
100 #define DETMON_QC_LIN_COEF_C "Linearity coefficient value"
101 
102 
103 #define DETMON_QC_LIN_COEF_ERR "ESO QC LIN EFF ERR"
104 #define DETMON_QC_LIN_COEF_ERR_C "Linearity coefficient error value"
105 #define DETMON_QC_LIN_COEF_MSE_ERR_C "Linearity coefficient measured square error value"
106 
107 
108 #define DETMON_QC_ERRFIT "ESO QC ERRFIT"
109 #define DETMON_QC_ERRFIT_C "Error of fit"
110 #define DETMON_QC_ERRFIT_MSE_C "Measured square error of fit"
111 
112 #define DETMON_QC_CONTAM "ESO QC CONTAM"
113 #define DETMON_QC_CONTAM_C "Detector contamination in a region"
114 
115 #define DETMON_QC_FPN "ESO QC FPN"
116 #define DETMON_QC_FPN_C "Flat pattern noise"
117 
118 #define DETMON_QC_FPN_FRAC "ESO QC FPN FRAC"
119 #define DETMON_QC_FPN_FRAC_C "QC.FPN / QC.SIGNAL.MEAN"
120 
121 #define DETMON_QC_SIGMA_PH "ESO QC SIGMA PH"
122 #define DETMON_QC_SIGMA_PH_C "RMS of raw frame photon noise (SIG_ON_DIF)"
123 
124 #define DETMON_QC_SIGNAL_MEAN "ESO QC SIGNAL MEAN"
125 #define DETMON_QC_SIGNAL_MEAN_C "Mean signal (from MEAN_ON1)"
126 
127 
128 #define DETMON_QC_CONAD_AVG "ESO QC CONAD AVG"
129 #define DETMON_QC_CONAD_AVG_C "Avg measured e- -> ADU (from GAIN)"
130 
131 #define DETMON_QC_CONAD_RMS "ESO QC CONAD RMS"
132 #define DETMON_QC_CONAD_RMS_C "RMS of measured e- -> ADU (from GAIN)"
133 
134 #define DETMON_QC_GAIN_AVG "ESO QC GAIN AVG"
135 #define DETMON_QC_GAIN_AVG_C "Avg gain across detectors"
136 
137 #define DETMON_QC_GAIN_RMS "ESO QC GAIN RMS"
138 #define DETMON_QC_GAIN_RMS_C "RMS of gain across detectors"
139 
140 #define DETMON_QC_CONTAMi_NORM "ESO QC CONTAM%zd NORM"
141 #define DETMON_QC_CONTAMi_NORM_C "QC.CONTAM%01d / (gain)QC.SIGNAL.MEAN"
142 
143 #define DETMON_QC_GAIN_ERR_AVG "ESO QC GAIN ERR AVG"
144 #define DETMON_QC_GAIN_ERR_AVG_C "Avg QC GAIN ERR"
145 
146 #define DETMON_QC_GAIN_ERR_RMS "ESO QC GAIN ERR RMS"
147 #define DETMON_QC_GAIN_ERR_RMS_C "RMS of QC GAIN ERR"
148 
149 #define DETMON_QC_COUNTS_MIN_AVG "ESO QC COUNTS MIN AVG"
150 #define DETMON_QC_COUNTS_MIN_AVG_C "Avg of QC COUNTS MIN"
151 
152 #define DETMON_QC_COUNTS_MIN_RMS "ESO QC COUNTS MIN RMS"
153 #define DETMON_QC_COUNTS_MIN_RMS_C "RMS of QC COUNTS MIN"
154 
155 #define DETMON_QC_COUNTS_MAX_AVG "ESO QC COUNTS MAX AVG"
156 #define DETMON_QC_COUNTS_MAX_AVG_C "Avg of QC COUNTS MAX"
157 
158 #define DETMON_QC_COUNTS_MAX_RMS "ESO QC COUNTS MAX RMS"
159 #define DETMON_QC_COUNTS_MAX_RMS_C "RMS of QC COUNTS MAX"
160 
161 #define DETMON_QC_LIN_EFF_AVG "ESO QC LIN EFF AVG"
162 #define DETMON_QC_LIN_EFF_AVG_C "Avg of QC LIN EFF"
163 
164 #define DETMON_QC_LIN_EFF_RMS "ESO QC LIN EFF RMS"
165 #define DETMON_QC_LIN_EFF_RMS_C "RMS of QC LIN EFF"
166 
167 #define DETMON_QC_LIN_EFF_FLUX_AVG "ESO QC LIN EFF FLUX AVG"
168 #define DETMON_QC_LIN_EFF_FLUX_AVG_C "Avg of QC LIN EFF"
169 
170 #define DETMON_QC_LIN_EFF_FLUX_RMS "ESO QC LIN EFF FLUX RMS"
171 #define DETMON_QC_LIN_EFF_FLUX_RMS_C "RMS of QC LIN EFF FLUX"
172 
173 #define DETMON_QC_CONTAMi_AVG "ESO QC CONTAM%zd AVG"
174 #define DETMON_QC_CONTAMi_AVG_C "Avg of ESO QC CONTAM%zd"
175 
176 #define DETMON_QC_CONTAMi_RMS "ESO QC CONTAM%zd RMS"
177 #define DETMON_QC_CONTAMi_RMS_C "RMS of ESO QC CONTAM%zd"
178 
179 // The next four accept strings, rather than ints, due to the
180 // structure of the functions setting them
181 
182 #define DETMON_QC_LIN_COEFF_AVG "ESO QC COEFF%s AVG"
183 #define DETMON_QC_LIN_COEFF_AVG_C "Avg of ESO QC COEF%s"
184 
185 #define DETMON_QC_LIN_COEFF_RMS "ESO QC COEFF%s RMS"
186 #define DETMON_QC_LIN_COEFF_RMS_C "RMS of ESO QC COEF%s"
187 
188 #define DETMON_QC_LIN_COEFF_ERR_AVG "ESO QC COEFF%s ERR AVG"
189 #define DETMON_QC_LIN_COEFF_ERR_AVG_C "Avg of ESO QC COEF%s ERR"
190 
191 #define DETMON_QC_LIN_COEFF_ERR_RMS "ESO QC COEFF%s ERR RMS"
192 #define DETMON_QC_LIN_COEFF_ERR_RMS_C "RMS of ESO QC COEF%s ERR"
193 
194 /* Macros to generate the recipe(s) description(s) */
195 #define detmon_lg_get_description(RECIPE_NAME, PIPE_NAME, \
196  DETMON_LG_ON_RAW_NEW, \
197  DETMON_LG_OFF_RAW_NEW, \
198  DETMON_LG_ON_RAW_OLD, \
199  DETMON_LG_OFF_RAW_OLD) \
200  RECIPE_NAME " -- " PIPE_NAME " linearity/gain recipe for OPT/IR.\n" \
201  "The files listed in the Set Of Frames must be tagged:\n" \
202  "the raw-on-file.fits "DETMON_LG_ON_RAW_NEW" and\n" \
203  "the raw-off-file.fits "DETMON_LG_OFF_RAW_NEW"\n" \
204  "For backward compatibility are alternatively still supported the following tags:\n" \
205  "the raw-on-file.fits "DETMON_LG_ON_RAW_OLD" and\n" \
206  "the raw-off-file.fits "DETMON_LG_OFF_RAW_OLD"\n" \
207  "The recipe requires at least order+1 valid pairs of ON frames\n" \
208  "and order+1 valid pairs of OFF frames, \n" \
209  "where order is the value of the 'order' parameter.\n" \
210  "There is no requirement for pairs of OFF frames if collapse parameter " \
211  "is set to true.\n" \
212  "Frames with median flux over --filter will be excluded from the " \
213  "computation.\n" \
214  "To perform a stability check you need frames with at least 2 DIT " \
215  "values\n" \
216  "NOTE for multiextension cases: it is mandatory to modify the --exts " \
217  "parameter, either to -1 (all extensions) or to any valid extension nb.\n" \
218  "\n" \
219  "The output PRO.CATG are:\n" \
220  "GAIN_INFO - the gain table\n" \
221  "DET_LIN_INFO - the linearity table\n" \
222  "BP_MAP_NL - the bad pixel map (only produced with --pix2pix=TRUE)\n" \
223  "COEFFS_CUBE - the fit coefficient cube (only produced with --pix2pix=TRUE)\n"
224 
225 #define REGEXP "ARCFILE|MJD-OBS|ESO TPL ID|DATE-OBS|ESO DET DIT|ESO DET NDIT"
226 
227 typedef unsigned long irplib_gain_flag;
228 
229 #define IRPLIB_GAIN_PTC ((irplib_gain_flag) 1 << 1)
230 #define IRPLIB_GAIN_MEDIAN ((irplib_gain_flag) 1 << 2)
231 #define IRPLIB_GAIN_NO_COLLAPSE ((irplib_gain_flag) 1 << 3)
232 #define IRPLIB_GAIN_COLLAPSE ((irplib_gain_flag) 1 << 4)
233 #define IRPLIB_GAIN_WITH_AUTOCORR ((irplib_gain_flag) 1 << 5)
234 #define IRPLIB_GAIN_WITH_RESCALE ((irplib_gain_flag) 1 << 6)
235 #define IRPLIB_GAIN_OPT ((irplib_gain_flag) 1 << 7)
236 #define IRPLIB_GAIN_NIR ((irplib_gain_flag) 1 << 8)
237 
238 typedef unsigned long irplib_lin_flag;
239 
240 #define IRPLIB_LIN_NO_COLLAPSE ((irplib_lin_flag) 1 << 10)
241 #define IRPLIB_LIN_COLLAPSE ((irplib_lin_flag) 1 << 11)
242 #define IRPLIB_LIN_PIX2PIX ((irplib_lin_flag) 1 << 12)
243 #define IRPLIB_LIN_WITH_RESCALE ((irplib_lin_flag) 1 << 13)
244 #define IRPLIB_LIN_OPT ((irplib_lin_flag) 1 << 14)
245 #define IRPLIB_LIN_NIR ((irplib_lin_flag) 1 << 15)
246 
247 /*----------------------------------------------------------------------------
248  Prototypes
249  ----------------------------------------------------------------------------*/
250 
251 cpl_error_code
252 detmon_lg(cpl_frameset * frameset,
253  const cpl_parameterlist * parlist,
254  const char * tag_on,
255  const char * tag_off,
256  const char * recipe_name,
257  const char * pipeline_name,
258  const char * pafregexp,
259  const cpl_propertylist * pro_lintbl,
260  const cpl_propertylist * pro_gaintbl,
261  const cpl_propertylist * pro_coeffscube,
262  const cpl_propertylist * pro_bpm,
263  const cpl_propertylist * pro_corr,
264  const cpl_propertylist * pro_diff,
265  const char * package,
266  int (* compare) (const cpl_frame *,
267  const cpl_frame *),
268  int (* load_fset) (const cpl_frameset *,
269  cpl_type,
270  cpl_imagelist *),
271  const cpl_boolean opt_nir);
272 
273 
274 cpl_image * detmon_image_correlate(const cpl_image *,
275  const cpl_image *,
276  const int ,
277  const int );
278 
279 cpl_error_code
280 detmon_lg_fill_parlist_nir_default(cpl_parameterlist *,
281  const char *,
282  const char *);
283 
284 cpl_error_code
285 detmon_lg_fill_parlist_nir_default_mr(cpl_parameterlist * parlist,
286  const char *recipe_name,
287  const char *pipeline_name);
288 
289 cpl_error_code
290 detmon_lg_fill_parlist_opt_default(cpl_parameterlist *,
291  const char *,
292  const char *);
293 
294 cpl_error_code
295 detmon_lg_fill_parlist_opt_default_mr(cpl_parameterlist * parlist,
296  const char *recipe_name,
297  const char *pipeline_name);
298 
299 cpl_error_code
300 detmon_lg_fill_parlist(cpl_parameterlist * parlist,
301  const char *recipe_name, const char *pipeline_name,
302  const char *method,
303  int order,
304  double kappa,
305  int niter,
306  int llx,
307  int lly,
308  int urx,
309  int ury,
310  int ref_level,
311  const char * intermediate,
312  const char * autocorr,
313  const char * collapse,
314  const char * rescale,
315  const char * pix2pix,
316  const char * bpmbin,
317  int filter,
318  int m,
319  int n,
320  double tolerance,
321  const char * pafgen,
322  const char * pafname,
323  int llx1,
324  int lly1,
325  int urx1,
326  int ury1,
327  int llx2,
328  int lly2,
329  int urx2,
330  int ury2,
331  int llx3,
332  int lly3,
333  int urx3,
334  int ury3,
335  int llx4,
336  int lly4,
337  int urx4,
338  int ury4,
339  int llx5,
340  int lly5,
341  int urx5,
342  int ury5,
343  int exts,
344  cpl_boolean opt_nir);
345 
346 cpl_image *
347 detmon_autocorrelate(const cpl_image *,
348  const int, const int);
349 
350 cpl_table *
351 detmon_gain(const cpl_imagelist *,
352  const cpl_imagelist *,
353  const cpl_vector *,
354  const cpl_vector *,
355  double ,
356  int ,
357  int ,
358  int ,
359  int ,
360  double ,
361  int ,
362  int ,
363  int ,
364  cpl_propertylist *,
365  unsigned ,
366  cpl_imagelist **,
367  cpl_imagelist **);
368 
369 cpl_table *
370 detmon_lin(const cpl_imagelist *,
371  const cpl_imagelist *,
372  const cpl_vector *,
373  double ,
374  int ,
375  int ,
376  int ,
377  int ,
378  int ,
379  int ,
380  double,
381  cpl_boolean,
382  cpl_propertylist *,
383  unsigned ,
384  cpl_imagelist **,
385  cpl_image **);
386 
387 cpl_error_code
388 detmon_lg_set_tag(cpl_frameset* set, const char** tag_on, const char** tag_off);
389 
390 cpl_error_code
391 detmon_lg_qc_params(cpl_table* linear_table, cpl_propertylist* lint_qclist,
392  cpl_table* gain_table, cpl_propertylist* gaint_qclist,
393  cpl_imagelist* coeffs, cpl_propertylist* linc_qclist,
394  cpl_image* bpm, cpl_propertylist* bpm_qclist,
395  const char * recipe_name);
396 
397 cpl_error_code
398 detmon_lg_qc_params_global_gain(const char * recipe_name, int nsets);
399 
400 cpl_error_code
401 detmon_lg_qc_params_global_gain_update(const char * fn,
402  const char * recipe_name);
403 
404 cpl_error_code
405 detmon_lg_qc_params_global_lin(const char * recipe_name, int nsets);
406 
407 cpl_error_code
408 detmon_lg_qc_params_global_lin_update(const char * fn,
409  const char * recipe_name);
410 
411 cpl_error_code
412 detmon_lg_qc_params_global_bpm(const char * recipe_name, int nsets);
413 
414 cpl_error_code
415 detmon_lg_qc_params_global_bpm_update(const char * fn,
416  const char * recipe_name);
417 
418 cpl_error_code
419 detmon_lg_qc_params_global_coeffs(const char * recipe_name, int nsets);
420 
421 cpl_error_code
422 detmon_lg_qc_params_global_coeffs_update(const char * fn,
423  const char * recipe_name);
424 
425 cpl_error_code
426 detmon_lg_qc_set_kw_from_table_column(cpl_table* table,
427  const char * column,
428  const char * op,
429  cpl_propertylist* header,
430  const char * kw,
431  const char * kw_comment);
432 
433 #endif