# Photometric equalization for AstroDrizzle

A tool to adjust data values of images by equalizing each chip’s PHOTFLAM value to a single common value so that all chips can be treated equally by `AstroDrizzle`.

Authors: | Mihai Cara
License: | http://www.stsci.edu/resources/software_hardware/pyraf/LICENSE

`drizzlepac.photeq.``photeq`(files='*_flt.fits', sciext='SCI', errext='ERR', ref_phot=None, ref_phot_ext=None, phot_kwd='PHOTFLAM', aux_phot_kwd='PHOTFNU', search_primary=True, readonly=True, clobber=False, logfile='photeq.log')

  Adjust data values of images by equalizing each chip’s PHOTFLAM value to a single common value so that all chips can be treated equally by `AstroDrizzle`.

  Parameters:

  files : str (Default = `'*_flt.fits'`)

  > A string containing one of the following:

  > > - a comma-separated list of valid science image file names, e.g.: `'j1234567q_flt.fits, j1234568q_flt.fits'`;
  > > - an @-file name, e.g., `'@files_to_match.txt'`. See notes section for details on the format of the @-files.

  > Note

  > Valid science image file names are:

  > - file names of existing FITS, GEIS, or WAIVER FITS files;
  > - partial file names containing wildcard characters, e.g., `'*_flt.fits'`;
  > - Association (ASN) tables (must have `_asn`, or `_asc` suffix), e.g., `'j12345670_asn.fits'`.

  sciext : str (Default = ‘SCI’)

  > Extension name of extensions whose data and/or headers should be corrected.

  errext : str (Default = ‘ERR’)

  > Extension name of the extensions containing corresponding error arrays. Error arrays are corrected in the same way as science data.

  ref_phot : float, None (Default = None)

  > A number indicating the new value of PHOTFLAM or PHOTFNU (set by ‘phot_kwd’) to which the data should be adjusted.

  ref_phot_ext : int, str, tuple, None (Default = None)

  > Extension from which the `photeq` should get the reference photometric value specified by the `phot_kwd` parameter. This parameter is ignored if `ref_phot` is not `None`. When `ref_phot_ext` is `None`, then the reference inverse sensitivity value will be picked from the first `sciext` of the first input image containing `phot_kwd`.

  phot_kwd : str (Default = ‘PHOTFLAM’)

  > Specifies the primary keyword which contains inverse sensitivity (e.g., PHOTFLAM). It is used to compute conversion factors by which data should be rescaled.

  aux_phot_kwd : str, None, list of str (Default = ‘PHOTFNU’)

  > Same as `phot_kwd` but describes other photometric keyword(s) that should be corrected by inverse of the scale factor used to correct data. These keywords are not used to compute conversion factors. Multiple keywords can be specified as a Python list of strings: `['PHOTFNU', 'PHOTOHMY']`.

  > Note

  > If specifying multiple secondary photometric keywords in the TEAL interface, use a comma-separated list of keywords.

  search_primary : bool (Default = True)

  > Specifies whether to first search the primary header for the presence of `phot_kwd` keyword and compute conversion factor based on that value. This is (partially) ignored when `ref_phot` is not `None` in the sense that the value specified by `ref_phot` will be used as the reference but in all images primary will be searched for `phot_kwd` and `aux_phot_kwd` and those values will be corrected (if `search_primary=True`).

  readonly : bool (Default = True)

  > If `True`, `photeq` will not modify input files (nevertheless, it will convert input GEIS or WAVERED FITS files to MEF and could overwrite existing MEF files if `clobber` is set to `True`). The (console or log file) output however will be identical to the case when `readonly=False` and it can be examined before applying these changes to input files.

  clobber : bool (Default = False)

  > Overwrite existing MEF files when converting input WAVERED FITS or GEIS to MEF.

  logfile : str, None (Default = ‘photeq.log’)

  > File name of the log file.

  Notes

  By default, `photeq` will search for the first inverse sensitivity value (given by the header keyword specified by the `phot_kwd` parameter, e.g., PHOTFLAM or PHOTFNU) found in the input images and it will equalize all other images to this reference value.

  It is possible to tell `photeq` to look for the reference inverse sensitivity value only in a specific extension of input images, e.g.: 3, (‘sci’,3), etc. This can be done by setting `ref_phot_ext` to a specific extension. This may be useful, for example, for WFPC2 images: WF3 chip was one of the better calibrated chips, and so, if one prefers to have inverse sensitivities equalized to the inverse sensitivity of the WF3 chip, one can set `ref_phot_ext=3`.

  Alternatively, one can provide their own reference inverse sensitivity value to which all other images should be “equalized” through the parameter `ref_phot`.

  Note

  Default parameter values (except for `files`, `readonly`, and `clobber`) should be acceptable for most HST images.

  Warning

  If images are intended to be used with `AstroDrizzle`, it is recommended that sky background measurement be performed on “equalized” images as the `photeq` is not aware of sky user keyword in the image headers and thus it cannot correct sky values already recorded in the headers.

  Examples

  1. In most cases the default parameters should suffice:

         >>> from drizzlepac import photeq
         >>> photeq.photeq(files='*_flt.fits', readonly=False)

  2. If the re-calibration needs to be done on PHOTFNU rather than PHOTFLAM, then:

         >>> photeq.photeq(files='*_flt.fits', ref_phot='PHOTFNU',
         ... aux_phot_kwd='PHOTFLAM')

  3. If for WFPC2 data one desires that PHOTFLAM from WF3 be used as the reference in WFPC2 images, then:

         >>> photeq.photeq(files='*_flt.fits', ref_phot_ext=3) # or ('sci',3)

`drizzlepac.photeq.``help`(file=None)

  Print out syntax help for running skymatch

  Parameters:

  file : str (Default = None)

  > If given, write out help to the filename specified by this parameter Any previously existing file with this name will be deleted before writing out the help.