# Photometry Calibration

A photometry calibration.

## Synopsis

`munipack phcal [.. parameters ..] file(s)[,result(s)]`

## Description

Purpose of this routine is the photometry calibration of CCD frames. The calibration establish an exact relation between observed instrumental counts and expected amount of photons by using a (small) set of known calibration stars. On base of the calibration, all known objects and the image itself should be transformed from instrumental counts to aboslute fluxes of photons, energy or magnitudes.

## Detailed Description

Every single picture elements exposed by light for a time period is collecting electrons created due to photo-electric effect from photons. Counts of the electrons is digitised and stored in output images. One can be directly used for additional light analysis. We will use term (instrumental) count(s) for their calculated amount (widely used by astronomers).

For a non-ideal detector, amount of digitised electrons will less than for photons. These counts will depends on the instrumental equipment (quality of optical path, lenses, mirrors, weather, quantum efficiency of CCD camera, etc). As consequence of the measurement process, the counts is unique per an apparatus and observation conditions. Two telescopes equipped with the same instrumentation will not product the same counts due to atmospheric conditions. The different apparatus (filters, detectors) generally produces different counts. To compare and to process observations from different observatories, we need unify all observations to same scales. Traditionally, in various parts of physics, the calibration is done with setting of calibration scale on a priory known calibrated sources. The sources are calibration stars for astronomers. The scale is relation between observed counts and produced photons.

More detailed description of the calibration can be found in Photometry Overview.

The calibration implemented by Munipack follows these steps:

- Detected stars are merged using of coordinates against to a reference photometric catalogue.
- With known filter and photometry system, expected count of photons is determined from magnitudes in the catalogue.
- Instrumental counts are transformed from an instrumental to a standard (photometry system) filter using of provided transformation matrix. (This step is optional.)
- By using of a telescope area, gain and exposure time are observed counts normalised on count rates.
- The calibration itself is determined as the ratio of reference amount of photons and observed rates.

Image data values are converted on a physical quantity (like photons, fluxes, magnitudes). The conversion is applied on frame data as well as on photometric tables. The conversion requires known astrometry and photometry calibration.

The conversion is very useful for converting observed quantities to a derived ones. One is ideal for construction of multi-spectral pictures of objects.

## Algorithm

The calibration is computed by the way:

- Reference catalogue and frames are merged in spherical coordinates and by search in close neighbourhood.
- From known filter and photometry system, from catalogue magnitudes photon fluxes are computed.
- Observed counts are normalised to rates by knowing of telescope area and exposure time.
- The calibration ratio between expected photons and observed counts is determined by a robust method.
- All values in frames and tables are recomputed on photons.

When photometry transformation table from instrumental to standard system is available `--tratab`, the counts are transformed from instrumental to a relative standard counts and the calibration is performed on the kind of counts.

## Operational modes

Photometry calibration is a very complex task so various ways are implemented:

Reference Catalogue
  Reference sources are stars provided as a table. The table can be prepared by hand or a photometrical catalogue can be used. Precision of calibration is given by quality of the catalogue and also by true colour transformation of instrumental to the catalogue. Usually, the calibration has small systematical offsets but larger random errors.
Reference Frame
  Reference stars are pulled from previsouly calibrated frame. Relative precision is generally better than in previous case because no colour transformation is required.
Manual Calibration
  The calibration values are provided by an user.

The choice suitable for specific situation would be very difficoult.

## Prerequisites

Needs both astrometry and instrumental photometry of frames.

Headers would contain all the exposure time, filter, telescope area and photometry system keywords.

Specify photometric system (a conventional set of filters). Default is used value from frame header, use it when value is missing or needs correction. The option is important while determining of photometry calibration.

Specify filter. Default is used value from frame header, use it when value is missing or needs correction. The filter is important while determining of photometry calibration.

When calibrated frame contains FWHM parameter, the first aperture larger then the radius is used. When the parameter missing, the first aperture or user provided aperture is used.

Important.

The exposure time, filter, gain, area and an instrumental photometry system are absolutely necessory for calibration and none of them can not be omitted. At first, all values are obtained by reading of headers of FITS files. If at least one is not found, the calibration process is stopped (a wrong calibration which looks as valid is much more worse than any fail).

The situation can be solved by the ways:

- The values can be provided by editing of input files with help of `fits` module:

      $ munipack fits --key-update AREA=1,'[m] telescope area' huge.fits

  for all missing parameters.
- Also convenience options for most frequent missing parameters are provided: area and instrumental photosystem:

      $ munipack phcal ... --area 1 --photsys-instr 'MONTEBOO' ... frames.fits

  The convenience options doesn't supply common keywords (exptime, filter and gain) which can be usually found in frames.

While common values of exposure times, filters etc. are included to every header, the keywords can differ from Munipack's defaults. In the case, set ones via environment variables.

## Results

Output calibrated fits frames contains a new extension described in Photometry Calibrated File. Its table contains coordinates of stars on frames and various photometric quantities.

## Parameters

### Reference Catalogue:

`-C,--cal`
  The calibration is specified by an exterior entity. The values are saved to a PHOTOMETRY extension header and counts are converted to photons for both image and table values.
`-c,--cat`
  Reference photometric catalogue. A fits table with coordinates and magnitudes of reference stars. One can be a selection from a "real" catalogue or a table prepared by oneself. See section Preparation of Photometric Catalogue, how create this table by hand.
`-r,--ref`
  Reference frame is used. The reference frame usually created by `-c,-C` options. Useful for relative photometry.
`-f,--filters`
  Filters used for calibration.
`-F,--filter-ref`
  Reference filter for calibration.
`--col-ra`
  Right Ascension column. Default is RAJ2000.
`--col-dec`
  Declination column. Default is DEJ2000.
`--col-mag`
  Magnitude column(s). Default is the filter (-f option) with 'mag' suffix like `-f V --col-mag Vmag` (?).
`--col-magerr`
  Magnitude std. error column(s) (no default). If this parameter is omited, errors are estimated as the square of photons derived from magnitudes.
`--tol`
  search radius for object identification in degrees (default 5*FWHM)

### Calibration specific:

`--photsys-ref`
  reference (standard) photometric system (catalogue)
`--photsys-instr`
  instrumental photometric system (frames)
`-q, --quantity`
  calibrated quantities by default: PHRATE, FLUX, FNU, FLAM, MAG, ABMAG, STMAG (see description), multiple quantities can be used, separated by colon

### Photometric system:

`--tratab`
  Table describing conversion from instrumental to reference photo-system. Usually product of phfotran.
`--phsystab`
  A table with photometric system definitions (specification)
`--list`
  Lists available photometric systems. Their identifiers are names of extensions in (photometric system definitions) file.

### Common:

`-th, --threshold`
  Select stars on both reference and calibrated frames (not applied on catalogues) with its stellar flux to a sky noise (signal to noise) ratio greater then the threshold value. Both the values are determined in the same aperture. The proper choice is crucial for photometry precision because it helps to select only bright stars with minimal pollution by the sky noise. The default value 5 is very conservative setup. It is suitable for bad conditions (like urban or a full moon light observations). Standard and good conditions will allow lower ratios. In an ideal case, it can be under one for best results.
`-e, --maxerr`
  Select stars on both reference and calibrated frame (not applied on catalogues) with its relative flux error smaller than the error limit. The value does not limits the final precision, but limits fluency of noisy data. The default value 0.1 (ten percents, about tenth of magnitude) will also include relative imprecise stars into both calibration and calibrated set. The values under 0.01 and lower will select only precise and suitable calibration stars.
`--area`
  Area of telescope aperture in square meters [m2].
`--saper`
  selects appropriate aperture from PHOTOMETRY extension. By default, flux in infinite aperture is used.
`--apcorr`
  sets the aperture correction. This correction converts fluxes in an aperture to the total flux (infinite aperture). The value of correction should be obtained by gphot.
`--advanced`
  Advanced format. Additional extensions (results of star find, photometry and residuals) are included. This format is not used by default because result FITS is twice or more bigger.

See Common options for input/output filenames.

When options for the area and the reference and instrumental systems are used, FITS header is updated according to provided values.

Default values for coordinates will be usually unsatisfactory.

See Common options for input/output filenames. If advanced parameters `-O` are not set, default `-O --mask '!\1_XXX.\2'` is used according to some selected quantity. For example, `-q MAG` and the input file `blazar_01R.fits` will produce the output file `blazar_01R_MAG.fits`. Be warned, that output files are overwritten in any case by default.

## Preparation Of Photometry Catalogue

The table is a fits table and must contains columns with Right Ascension, Declination, reference magnitudes (and optionally with standard errors of the magnitudes). The column naming is by default RA, DEC, MAG and can be changed with --col-* options.

The table may be prepared by any standard FITS utility (for example fcreate utility of FTOOLS).

To save the time, you can just edit file `mtable.lst` in Munipack distribution (carefully handle with NAXIS1 and NAXIS2, etc.) and create a table

    $ munipack fits --restore mtable.lst

The output in mtable.fits can be used to a right frame as

    $ munipack phcal -c mtable.fits frame.fits

## A Low-Precision Calibration

We are using just one filter. No transformation matrix is used.

## A High-Precision Calibration

We are using multiple filters. Transformation matrix is used, we get the maximum possible precision.

## Examples

Calibrate against to UCAC5 catalogue:

    $ munipack cone -c UCAC5 -o 0716cat.fits -r 0.1 110.47 71.34
    $ munipack phcal -c 0716cat.fits --col-ra RAJ2000 --col-dec DEJ2000 \
      --col-mag Gmag  --photosys Johnson 0716_?R.fits
    $ munipack phcal -c T_Phe.fits --tratab phfotran.fits  --col-mag B,V,R,I \
       TPhe_B.fits,b.fits TPhe_V.fits,v.fits TPhe_R.fits,r.fits TPhe_I.fits,i.fits

    munipack phcal --verbose -r grb140423-2_C_0002_cal.fits --photsys-ref Johnson  grb140423-2_C_0003.fits

## See Also

Photometic System Transformation, Common Options, Photometry Format, Photometry Overview.