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: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')[source]

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)[source]

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.