# Flat-field frame

This utility builds a flat field by scaling and averadging of a set of individual flat-field frames.

## Synopsis

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

## Description

A flat-field frame is a map of a photometric response of an instrument (all together detector, filter, and optical configuration). Flat-fields are intended to remove a light path non-uniformity as: the variable sensitivity of pixels, dust grains shadows, filter homogenity, or vignetting. Ones can be acquired on sky during twilight, as night sky images, the dome flats or by another technique.

Flat-fiels are build on base of principial properties of the statistic of photons: the bound relation between the mean c and the standard deviation σ², it is described in detail by Poisson's distribution . The properties are utilised to scale and to averadge of single flats. The averaging improves accuracy of the final flat-field, moreover, all defects, presented on any single frame (like random cosmics), are softly cleared.

The values of the final flat-field Fij are computed as the a solution of a non-linear implicit equation, pixel by pixel for every input frame. A lot of both computer power and memory is need. The required memory is width × height × 4 × 2 bytes per frame, one hundred of 1000×1000 frames takes 800MB.

Relative accuracy of a final flat-field increase as square root of amount of input frames √N (sixteen input frames increases accuracy by factor 4×). Implemented robust methods works well when amount of input frames is over thirteen frames N > 13.

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

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 gain estimate, values of variance σ2 and gain g are determined when `--verbose` printings are activated:

      ...
      Filename, mean level c, std.err., std.dev. σ, gain g, reliable:
      ...
      flat-V_000006.fits:   99142.  0.151 313.73  1.007  T
      flat-V_000007.fits:   81895.  0.137 285.10  1.008  T
      flat-V_000008.fits:   67706.  0.125 259.86  1.003  T
      ...

A recommended way to determine of gain is initialy set to some value (g=1 if no other approximation 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 desired accuracy.

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. The file has STDERR extension with standard errors.

## Parameters

`-gain g`
  provides value of gain (rather than one by 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. Any pixel out of the range th < pixel < s (see also --threshold) is rejected the processing. This switch is useful mainly for over-exposed parts of frames and elimination of non-linear parts of gradation curve. If 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 given data-type 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. Any pixel below the value is rejected from the processing. If unset, the value is number one. Threshold is minor significance parameter. It should help for faulty values or filtering of bad pixels. The value is set in ADU (values reported by camera).
`--approximation [basic|standard]`
  Basic level of approximation computes only robust mean of all flat-fields; it is considered as very rough estimate. The standard approximation level provides the most accurate solution as possible, limited by the photon noise only.
`-B bitpix`
  Set numerical type of output images. Only the default -32 should be used. The mean value of outputs will be changed to be order of 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, yet keep in mind: a flat-field with no some filter identification is like the heavy water without neutrons.

## Examples

    $ munipack flat -o f_R.fits -gain 2.3 -dark d30.fits -st 6e4 f30_*R.fits

A single flat-field frame.
An averadge of flat-field frames.

## See also

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