
wf3cte:

The charge transfer efficiency (CTE) of the UVIS detector has inevitably been declining over time as on-orbit radiation damage creates charge traps in the CCDs. Faint sources in particular can suffer large flux losses or even be lost entirely if observations are not planned and analyzed carefully. The CTE loss will depend on the morphology of the source, the distribution of electrons in the field of view (from sources, background, cosmic rays, and hot pixels) and the population of charge traps in the detector column between the source and the transfer register. And the magnitude of the CTE loss increases continuously with time as new charge traps form.

CTE is typically measured as a pixel-transfer efficiency, and would be unity for a perfect CCD. One indicator of CTE is the Extended Pixel Edge Response (EPER). Inefficient transfer of electrons in a flat-field exposure produces an exponential tail of charge in the overscan region. Analysis of monitoring observations through January 2013 shows that CTE continues to decline linearly over time (`WFC3 ISR 2013-03 <http://www.stsci.edu/hst/wfc3/documents/ISRs/WFC3-2013-03.pdf>`_).

The CTE correction step uses it's own dark reference files which have themselves been corrected for CTE. The specific reference file used for any dataset may be found in the image header keyword DRKCFILE. This step also uses a special bias reference file as part of the CTE correction itself, referred to in the header by the BIACFILE keyword. This BIACFILE is only used to facilitate the CTE correction, the resulting corrected image then uses the normal BIASFILE to correct the science frame after the CTE correction has been performed. After the CTE correction has been performed and the data progresses through the rest of the pipeline, the special CTE corrected dark, DRKCFILE in the header, will be used for the dark current correction instead of the DARKFILE.

There is a PCTETAB refrence file which contains extensions of calibration images and tables of parameters used during the CTE correction stage. The header of this file also contains parameters for the CTE correction algorithm. These parameters, and important scalars which are used to correct the data are stored in the output image headers.
See the UVIS2.0 reference ISR for more information.



This routine performs the CTE correction on raw data files. The calibration step keyword is PCTECORR, if this is set to PERFORM then the CTE correction will be applied to the dataset. Some caveats for its use:

* CTE corrections can *ONLY* be performed on RAW data which has not been calibrated in any way.
* Data which have already been through BLEVCORR, BIASCORR or DARKCORR will be rejected.
* The CTE correction step in the pipeline is currently only implemented for FULL FRAME images

The standalone call will produce a RAC fits file by default. This contains only the CTE corrected data, no other calibrations have been performed.

For more information the the WFC3 CTE please see `the WFC3 CTE webpage <http://www.stsci.edu/hst/wfc3/ins_performance/CTE/>`_ .

Example:

    In Python without TEAL:

    >>> from wfc3tools import wf3cte
    >>> wf3cte(filename)

    In Python with TEAL:

    >>> from stsci.tools import teal
    >>> from wfc3tools import wf3cte
    >>> teal.teal('wf3cte')

    In Pyraf:

    >>> import wfc3tools
    >>> epar wf3cte

Parameters:

    input : str
        Name of input files

            * a single filename (``iaa012wdq_raw.fits``)
            * a Python list of filenames
            * a partial filename with wildcards (``\*raw.fits``)
            * filename of an ASN table (``\*asn.fits``)
            * an at-file (``@input``)

    -1 : value, as in minus one, this will make sure only 1 processor/thread is used during processing, otherwise all available are used.

    verbose: bool, optional
        Print verbose time stamps?


**The wf3cte function can also be called directly from the OS command line:**

>>> wf3cte.e input  [-options]

Where the OS options include:

* -v: verbose
* -1: turn off multiprocessing
