Munipack ‒ Flat-field frame

# Flat-field frame

The `flat` utility is designed to constructs of an average flat-field frame by a set of individual flat-field frames.

## Synopsis

`munipack flat [.. parameters ..] file(s)`

## Description

A flat-field frame is a map of the photometric response of an instrument (both detector and optical configuration together). Flat-fields are used to remove all imperfections like variable light sensitivity of pixels, dust grains, vignetting and similar effects on per-pixel basis. Flat-fields can be acquired on sky during twilight, as night sky images, the dome flats or by another technique.

This routine creates a new flat-field frame by averaging of a set of such flat-fields. The averaging improves precision of the flat-field by factor of square root of input frames count (sixteen input frames increases precision by factor 4×). Moreover, all defects presented on any single frame (like random cosmics) are softly cleared.

The output flat-field Fij is computed as the massive sequence of non-linear implicit equations for every pixel of every input frame, which needs a lot of both computer power and time. Amount of frames is limited only by available memory (width × height × 4 × 2 bytes per frame). One hundred of 1000×1000 frames takes 800MB.

Relative precision of a final flat-field increase as square root of amount of input frames √N. Implemented robust methods works well when amount of input frames is over thirteen frames N > 13. A single frame on input is normalised only.

The input flat-fields should be preparatory corrected for all of these gain, bias and dark:

Fij → g(Fij - x Dij - Bij).

The meaning of x and the algorithm itself are the same as in photometric corrections.

It is strongly recommended to set of correct value of FITS_KEY_FILTER (environment variables), because the filter identification in the FITS header of the flat-field should be available for some later processing.

## Gain estimate

Flat-fielding can be used to estimate of gain g of a camera. The estimation determines variance σ2 and the mean value c of individual flat-field frames. Ratio satisfies the condition c/σ2 ≈ 1 only for Poisson distributed data, when other sources of noise are negligible. Values significantly violating the conditions indicates that g is differ to one. The recommended mean values for all c are about half of full well capacity of a detector.

The gain g is determined by the relation

g = c / σ²

The estimated values of variance σ2 and gain g are printed on the output as the last two columns:

      ...
      Filename,      mean level[ct],  std.err., reliable,  std.dev.,  gain:
                                                            [σ]        [g]
      ...
      flat-V_000002.fits:   1.15777E+05  58.5  T 339.14  1.007
      flat-V_000003.fits:   98909.  50.0  T 313.62  1.006
      ...

Gain is determined only on request by using of `--gain-estimate` switch (verbose mode is invoked), because it slows down computations.

A recommended way to determine of gain is preliminary set some value (g=1 if no the right value is already known) and invoke the estimate. Than use the newly determined value to set the gain again and repeat the procedure while estimated gain will remain on value near to one (with a few percent precision).

When gain keyword is available in the header, the values are initially scaled by the gain so results will be determined relative against to the value.

The estimation of value of gain is just indicative and to check by some alternative method (factory provided, …) is highly recommended.

## Input and output

On input, list of observed flat-fields is expected. Optionally, all gain, bias and dark corrections can by applied on every frame.

On output, just the flat-field frame is created.

## Parameters

`-gain g`
  provide value of gain (rather than FITS keyword) in [e-/ADU]
`-bias file`
  bias frame
`-dark file`
  dark frame
`-xdark x`
  dark frame multiplicative factor
`-bitmask file`
  mask frame (see phcorr for description). Only pixels, marked by this mask are processed.
`-st, --saturate s`
  Set saturate limit in units of input frames. All pixels with values out of the range th < flat < s (see also --threshold) are rejected from any processing. This switch is useful mainly for over-exposed flat-fields and elimination of non-linear parts of gradation curve. If leaved unset, the value is determined from FITS header (by FITS_KEY_SATURATE, see). If the keyword is not found and the frame contains an integer number type, the maximum value 2**BITPIX-1 is provided, otherwise the maximum value of the first frame on input is used (which practically switch-off the saturation bound check). The value is set in ADU (values reported by camera).
`-th, --threshold th`
  Set threshold limit in units of input frames. All pixels below the value are rejected from any processing. If unset, the value is zero. Threshold is minor significance parameter. It should help in case of faulty values in frames or filtering of bad flat-fields. Its recommended value is inside interval from zero to one quarter of full range. The value is set in ADU (values reported by camera).
`--gain-estimate`
  Rough estimate of gain.
`--approximation [basic|standard]`
  Basic approximation computes only robust mean of all flat-fields. It is only very rough estimate. The standard approximation provides more precise solution on base of the basic initial estimate.
`-B bitpix`
  Set numerical type of output images. Only the default -32 should be used. The mean value of outputs will be changed to 100, 104, 109 for BITPIX 8,16 and 32.
`-o filename`
  save to the output file

Also see Common options

## Environment variables

FITS_KEY_FILTER, FITS_KEY_DATEOBS, FITS_KEY_EXPTIME, FITS_KEY_IMAGETYP, FITS_KEY_GAIN, FITS_KEY_SATURATE (see Environment variables).

No one is mandatory, but remember, a flat-field with no filter identification is like heavy water without neutron.

## Examples

`$ munipack flat -o f_R.fits -gain 2.3 -dark d30.fits -st 6e4 f30_*R.fits`
A single flat-field frame.
A scaled robust mean of flat-field frames.

## See also

Flat-fielding, Light curve tutorial, Photometry corrections tutorial, Averaged bias frame, Averaged dark frame.