vircam_twilight_flat_combine
[Recipes]

Name:

vircam_twilight_flat_combine

Purpose:

Combine a series of twilight flat exposures into a single mean frame

Description:

A list of twilight flats are corrected with an appropriate master dark frame and then linearised. The dark corrected and linearised images are combined with rejection to form a mean twilight flat. If a master twilight flat is supplied, then a ratio image is formed between it and the combined result from the current frame list. This ratio image can be useful for looking at the evolution of the structure of the flat field. If a channel table is given, then the ratio image is broken into lots of little cells. The median value of the ratio image as well as the RMS in each cell is written to a ratio image statistics table.

Language:

C

Parameters:

• lthr (float): The low threshold below which an image is to be considered underexposed.
• hthr (float): The high threshold above which an image is to be considered overexposed.
• comb (int): Determines the type of combination that is done to form the output map. Can take the following values:
  • (1): The output pixels are medians of the input pixels
  • (2): The output pixels are means of the input pixels
• scale (int): Determines how the input data are scaled or offset before they are combined. Can take the following values:
  • (0): No scaling of offsetting
  • (1): All input frames are biassed additively to bring their backgrounds to a common mean.
  • (2): All input frames are scaled multiplicatively to bring their backgrounds to a common mean.
  • (3): All input frames are scaled to a uniform exposure time and then additively corrected to bring their backgrounds to a common mean.
• xrej (int): If set, then an extra rejection cycle will be run.
• thr (float): The rejection threshold in numbers of sigmas.
• ncells (int): If a ratio image statistics table is being done, then this is the number of cells in which to divide each readout channel. The value should be a power of 2, up to 64.
• ext (int): The image extension of the input files to be done on this run. If all of the extensions are to be processed, then this should be set to zero.

Input File Types:

The following list gives the file types that can appear in the SOF file. The word in bold is the DO category value.

• FLAT_TWILIGHT (required): A list of raw dark images for combining
• MASTER_DARK (required): A master dark frame. This is needed for the dark correction of the input twilight flat images.
• REFERENCE_TWILIGHT_FLAT (optional): A library twilight flat frame from a previous run. If this is given, then a ratio image will be formed and some basic statistics run on it.
• MASTER_BPM or MASTER_CONF (optional): If either is given, then it will be used to mask out bad pixels during and statistical analysis that is done. It will also be used to create an output confidence map with the bad pixels masked out.
• MASTER_CHANNEL_TABLE or CHANNEL_TABLE_INIT (optional): If this is given then the channels in ratio image will be broken up into a number of cells. Basic statistics will be done on the cells and written to the ratio image statistics table. If the table is not an initial channel table, then it will supply the linearity coefficients. As such, if this table is omitted altogether or if an initial table is supplied then no linearity correction will be done.

Output Products:

The following list gives the output data products that are generated by this recipe. The word in bold gives the DPR CATG keyword value for each product:

• The output mean/median twilight frame, formed by either a mean or median combination of the input raw frames with rejection (MASTER_TWILIGHT_FLAT).
• The output ratio image, formed by dividing the input master twilight frame into the current mean/median twilight frame. This is only done if a master twilight flat frame is specified from the outset. (RATIOIMG_TWILIGHT_FLAT)
• The output ratio image statistics table. The exact columns contained in this file are described at length in section 5.7 in the VIRCAM Data Reduction Library Design document (RATIOIMG_STATS_TWLIGHT_FLAT).
• The output master confidence map (MASTER_CONF).

Output QC Parameters:

• FLATRMS The RMS value of the mean twilight frame.
• FLATRATIO_MED The median of the twilight flat ratio image
• FLATRATIO_RMS The RMS of the twilight flat ratio image

Notes

None.

Fatal Error Conditions:

• NULL input frameset
• Input frameset headers incorrect meaning that RAW and CALIB frame can't be distinguished
• No twilight flat frames in the input frameset
• No master dark frame in input frameset
• Unable to save data products

Non-Fatal Error Conditions:

• No master twilight flat. No ratio image formed.
• No master bad pixel or confidence map. All pixels considered to be good.
• No channel table. No ratio image stats table created and no linearisation done.

Conditions Leading To Dummy Products:

• Twilight frame image extensions wouldn't load.
• The detector for the current image extension is flagged dead
• All images are either below the under-exposure threshold or above the over exposure threshold.
• Can't load the master dark image extension or master dark image is a dummy
• Combination routine failed
• Master twilight frame image extension won't load or is flagged as a dummy
• Channel table fits extension won't load, won't verify or is flagged as a dummy.

Author:

Jim Lewis, CASU

Code Reference:

vircam_twilight_flat_combine.c

---