# Photometry Corrections

Corrections of light exposures for gain, bias, dark and flat-field frames.

## Synopsis

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

## Description

Photometry corrections are important for any further processing of astronomical images. Their proper applications ensures photometry calibration, eg. the constant ratio between detected electrons and expected photons.

The photometry corrections reduces instrumental effects on imaging detectors (CCDs):

- Gain scales instrumental values onto counts of captured electrons per pixel and one is crucial for proper estimation of errors of photometry.
- The bias corrects counts on images for a constant added by control electronic. Their subtraction is important when absolute photometry calibration is required.
- The dark correction reduces signal produced by the thermal noise of apparatus and improves photometry precision about thousandths or hundredths.
- The flat-field describes spatial (angular) variation in detector sensitivity. The flat-field correction is crutial for any valuable photometry work and improves precision from tenths to thousandths.

## Algorithm

A photometric corrected image Icij is computed for every input image Iij as

Icij = (g Iij - x Dij - Bij)/fij,

where i,j is an index of a pixel, g is gain, Dij is the dark frame, x is a multiplication factor (see below). Bij is the bias frame and fij is the normalised flat-field frame (with absolute photometry fluxes conserved):

fij = Fij / 〈Fij〉.

〈Fij〉 means averaged level determined by robust meaning.

In case, that bias or dark is undefined, their values are set to zero (in real numbers). When flat-field is missing, values are fij=1 (real). If |〈Fij〉| is under machine precision, the value fij=0 (real) is set for all pixels. When fij is (machine) zero, the Icij=0 (real).

The multiplication factor x is determined by the way: when parameter `-xdark` is provided, its value is used, otherwise ratio of exposure times T of the scientific exposure I and the dark frame D are used as x= TI / TD. Both exposure times are extracted from FITS header (given by FITS_KEY_EXPOSURE environment variable). When the ratio can not be determined by previous way, the x=1 is silently set (this choice is compatible to traditional methods).

It is recommended to use averaged values of all correction images B,D,F produced by bias, dark and flat.

When records with keys FITS_KEY_FILTER and FITS_KEY_TEMPERATURE (environment variables) are available, checking for compatibility of the parameters is also performed.

## Gain

A common CCD camera captures electrons produced by photons illuminating pixels. These electrons are usually not directly available, but the control electronics converts their counts to another counts via analogue to digital converter with a gain g. New values and original ones are related by the relation

(values provided by camera) = g* (count of electrons).

The reason for this is usually due to storing usuall capacity of about 200k electrons per pixel to two bytes (range 0-65565).

Because the primary quantity are electrons and we need acute the primary quantity for estimation of statistical errors, we must convert values reported by camera to electrons for proper function of all other utilities. The output frame is identical (on the first view), but values are multiplied by the gain so values of output frames will generally different to originals.

Output values are in counts not ADU!

Gain value is preferably get from FITS header where is identified by GAIN keyword. If the value is not found, the input frame is not corrected.

The gain can be specified on command line with `-gain`. In this case, the value is used rather than the value in header. However, the usage is primary designed to correct a potentially wrong values of the gain.

The parameter `--gain-ignore` can be used to surprise any manipulation with gain. In this case, the values are left in an ADU. Please, keep in mind, that the photometry errors may be useless.

The gain will modify ranges of values and if the SATURATE keyword is found, one is adequately modified.

## Strategies For Corrections

There are two basic strategies for photometry corrections:

- No bias, dark's duration is equal to scientific.
- Bias, dark's duration is equal to scientific.

The first case is the traditional approach. Because duration of both scientific and dark exposure are the same, also bias is the same and subtraction removes bias together with the dark. The benefit is simpler processing of many exposures with the same exposure time.

The second strategy requires little more processing, but it is ideal for many exposures with theirs different duration. A lot of biases is made and only a few long-duration darks is taken. This approach is more flexible (when many exposure times is available) and also may save some observation time.

## Masking

A array mask Mij can be applied on result image with photometry corrections applied. The mask sets suppressed pixels (where Mij=0) and other left unchanged (where Mij=1). The masking technique has been adopted from bitmap editors (in computer graphics fields) where masked values are intended to be not shown. The masking is not limited on regions, a single (hot) pixel can be masked as well as.

Two choices for replacing of pixels are implemented: the robust mean and zero.

The mask is a FITS image, which must contain zeros at pixels to be replaced and the number one for pixels without any change. The BITPIX=8 is sufficient. The mask must have same dimensions as other images.

A process for create of Mij is complex. One strongly depends on values intended to by masked and on a masked image itself. Therefore there is no an unique way, how to prepare it.

## Parameters

`-gain g`
  provide value of gain (rather than FITS keyword)
`-flat file`
  flat-field frame
`-bias file`
  bias frame
`-dark file`
  dark frame
`-xdark x`
  dark frame multiplicative factor
`-bitmask file`
  mask frame
`-xbitmask`
  the mask frame is used as ZERO (default) or MEAN (average), MEDIAN
`-box 5`
  Box size used to -xbitmask MEDIAN, 5 by default. The value should be decreased to 3 for sharper estimate if mask has no overlaping elements.
`--normalise-flat`
  Normalise flat-field prior to use. The normalisation keeps values of original frames (by multiplication of original flat-field level). Both frames must have the same gain. Averaged flat-field frames produced by flat utility are normalised on level one and the normalisation can be omited. Be careful with saving frames to integer values (in this case normalisation must be used else all values will be zeros).
`--enable-overwrite`
  overwrite existing files

Files are converted to _proc (indicating procesed immediate products) by default.

Note that we have similar parameters `-bitmask` and `--mask` with roughly different meaning!

Also see Common options. A temperature and exposure time parameteres are set via Environment variables.

## Examples

Subtract `dark120.fits` from set of files `halley_*.fits`. Originals are untouched, results are saved as `halley_*_corr.fits~`):

    $ munipack phcorr -dark dark120.fits halley_*.fits

Subtract `dark120.fits` from set of files `halley_*.fits` and store results, with identical filenames, in /tmp directory.

    $ munipack phcorr -t /tmp  -dark dark120.fits halley_*.fits

An raw exposure of blazar 0716+714.
An exposure of blazar 0716+714 with d120 dark-frame subtracted.
A fully corrected (dark and flat), image of blazar 0716+714.

## See Also

Light Curve Tutorial, Photometry corrections tutorial, Averaged bias frame, Averaged dark frame, Averaged flat-field frame.