|ACS Data Handbook v. 9.0|
An overview of HST image data analysis software is available in the Introduction to the HST Data Handbooks. STScI no longer supports IRAF/PyRAF for data analysis, and instead recommends the use of Python.The AstroConda conda channel incorporates many of the Python tools used to calibrate and analyze HST data including calacs and AstroDrizzle. Documentation and installation instructions are found at:
Before any recalibration can be done, the directory location for calibration reference files must be defined. For ACS, this directory is referred to as "jref", and is used as a prefix in the reference file names in the image header (i.e., jref$qb12257gj_pfl.fits). In a Bash shell, export is used to set "jref" to a directory location. For example:
export jref="/mydisk/myjref/"Verify your jref location using echo $jref prior to using these examples.By default, the Archive provides calibrated images processed with the latest available reference files at processing time. In order to use non-default reference files and calibration switch settings, manual recalibration is required. These non-default settings have to be manually updated in the uncalibrated data (the raw FITS files) before running calacs. The table below gives a list of all of the calibration switches in the primary header.Table 3.7: Calibration Switch Selection CriteriaThe first column shows calibration switch header keywords. The second column is a description of the keyword, and the third column shows the default values.
DEFAULT = "OMIT" DEFAULT = "OMIT" ("PERFORM" if image was post-flashed) If CRSPLIT >= 2 then "PERFORM" else "OMIT" DEFAULT = "OMIT" DEFAULT = "OMIT" ("PERFORM" for WFC full-frame, subarray requires manual re-calibration using acs_destripe_plus) If NRPTEXP > 1 then "PERFORM" else "OMIT" DEFAULT = "PERFORM" for WFC only after January 15, 2015, "OMIT" for all other data DEFAULT = "PERFORM" (SBC only) DEFAULT = "PERFORM" (SBC only)Certain artifacts present in post-SM4 WFC subarray images, including bias striping, bias shift, and CTE trailing, are not fully handled by calacs. The amplitude of the bias shift and the CTE trailing in the 512- and 1024-pixel subarrays of HST Cycles 17–23 are not well characterized. However, the 2K subarray CTE trailing is near-identical to full-frame readout, and is corrected in calacs with the full-frame algorithm. All the new subarray modes introduced for use in Cycle 24 onwards will have calacs correction of bias shift and CTE trailing.Bias striping in post-SM4 subarray images is not corrected within calacs. Subarray stripe removal requires fitting across the entire image region, as discussed in Section 3.4.1, using the stand-alone task acs_destripe_plus in the AstroConda acstools suite. (See also Example 5 in Section 3.5.2)During the doPhot step, pixel values and units are not changed. This step only calculates the values of the calibrated image's photometric header keywords, such as the inverse sensitivity conversion factor (PHOTFLAM). Please refer to Section 3.4.4 "doPhot – Photometry Keyword Calculation" for more information.When populating the photometric keywords during the doPhot step, calacs uses the CRDS reference file IMPHTTAB. Some users find it cumbersome to keep up with the updates, and prefer to simply copy the photometric keyword values from the original calibrated data into the raw image's primary header, then run calacs with the PHOTCORR switch set to OMIT.3.5.2 calacs ExamplesIn these examples, Python is used to run calacs. These Python functions are simply wrappers around the C code that comprises calacs, and as such they may also be run outside of the Python environment.The following example uses WFC data from the Cycle 23 CAL/ACS program 14398 (PI: Chiaberge), which monitors the ACS/WFC CTE using observations of the globular cluster NGC 104 (47 Tucanae) in the F502N filter. The dataset names are JD1Y04RLQ and JD1Y04RNQ, and are part of the association JD1Y04010. In our examples, we have stored the FITS files in a subdirectory called cal_fits/ so that we can copy the files to the current working directory while preserving the original files for other examples.
For the purposes of this first example, assume that the observations are not part of an association. This example will illustrate the steps required to reprocess a single exposure (JD1Y04RLQ) after changing the bias reference file from the default value to a file specified by the user. Note that we will also CTE correct this image, but we will omit this for future examples. The CTE correction is computationally expensive and thus may take a long time to run on your machine. By default, it will use all of your machine's processors.
1. Make sure that the jref keyword is set to the ACS reference files as described earlier in this section.
Python OUTPUT: jref$09k2026tj_bia.fits
4. Edit the primary header of the raw image to enter the name of the new bias file called mybias.fits (for this example, mybias.fits is a copy of the default bias reference file listed in the header).
5. Set the PHOTCORR processing step to OMIT and copy the values of two useful photometric keywords from the calibrated image (retrieved from the Archive) to the raw image (see "Bypassing the PHOTCORR" for more information.) The PHOTFLAM keyword will be useful for photometric calibration during image analysis, and PHOTMODE is useful as a concise description of the observation mode. (Note: For WFC images, the keywords need to be edited for both SCI extensions, however the values in the extensions are identical.)
6. The pixel-based CTE correction algorithm was updated in July 2017, and not all files in the Archive have been reprocessed using the new method. Additionally, any files you may have downloaded from the Archive prior to August 3, 2017 will not have the new PCTETAB file in the header. In these cases, calacs will not run on files with PCTETAB set to an old reference file unless either PCTECORR is set to OMIT or PCTETAB is set to the latest reference file (alternatively, one can force calacs to run with the old method as well). In this example, we edit PCTETAB to point to the most recent *_cte.fits file in the jref directory.
7. We can now run calacs on the raw FITS file, which will be processed with the user-specified bias reference file mybias.fits. The result will be two calibrated images: one with the flt.fits extension; and a CTE-corrected one with the flc.fits extension. A trailer file with the .tra extension describing the steps taken by calacs is also produced.NOTE: Importing calacs will print a message (see the code block below). This is done on import only and not every time calacs is run.
The following tasks in the acstools package can be run with TEAL:The cell below cleans up the current working directory by removing the files created by this example. Only run this when you are finished with this example.
This example uses the same data from Example 1 and illustrates the steps required to reprocess an ACS association after changing the bias reference file from the default value to a file specified by the user. The steps required are similar to the previous example, with a few modifications.
2. Copy the images from the cal_fits/ directory to the current working directory and edit the headers to point BIASFILE to mybias.fits and update the PHOTCORR, PHOTFLAM, and PHOTMODE keywords appropriately as in Example 1. As mentioned previously, in this and future examples, we will set the PCTECORR keyword to OMIT for the sake of expediency. Then run calacs.
The products are three calibrated images: 1) two flt.fits files, one for each of the EXP-CRJ images in the association; and 2) one cosmic-ray cleaned image that is the combination of the two input images using the acsrej algorithm with no CTE correction applied.The cell below cleans up the current working directory by removing the files created by this example. Only run this when you are finished with this example.
This example illustrates the steps required to combine two sets of repeated observations to create a cosmic ray-rejected combined image. The data for this exercise comes from the ACS calibration program, 9662, that observed NGC 104 (47 Tucanae) using the HRC with a clear filter. The associations J8IS01020 and J8IS01040. Each association comprises of two 1-second exposures, and share the same target pointing.
3. As in the other examples, set PHOTCORR to OMIT and copy the PHOTFLAM and PHOTMODE keywords from the calibrated files. As this is HRC data, there is only one science extension, and thus we do not need to update the headers of multiple extensions.
The products are five images: 1) four flt.fits calibrated images; and 2) one crj.fits cosmic-ray cleaned stack of the four flt.fits files.The cell below cleans up the current working directory by removing the files created by this example. Only run this when you are finished with this example.
The following example uses WFC data from the GOODS program 9425. These observations are from visit 54, exposure 219; the target name was "CDF-South," observed with the F606W filter. The images were part of a 2-point line dither pattern with an exposure time of 480 seconds each, with rootnames J8E654C0Q and J8E654C4Q.This example illustrates the steps needed to reprocess data that are part of a dither pattern using a non-default dark reference file.
2. Edit the global image header for all the raw images to insert the name of the new dark reference file, mydark.fits (as in Example 1, we have copied the original dark file from the jref directory to the current working directory and renamed it mydark.fits).
3. Edit the PHOTCORR, PHOTFLAM, and PHOTMODE keywords as in previous examples.
4. Since mydark.fits does not have a counterpart CTE-corrected dark reference file, set PCTECORR to OMIT so that CTE-corrected images are not generated.
The result of this calacs run will be two calibrated images, one for each exposure in the association. This time, there will only be flt.fits files, not CTE-corrected flc.fits files, as we have set PCTECORR to OMIT. These files can then be used in AstroDrizzle to create a drizzled image.
The ACS Instrument Team implemented new flight software in Cycle 24 that changed the way CCD sub-array images are read out. This change makes it possible to apply the pixel based CTE correction to sub-array images. Here we illustrate the steps necessary to implement the correction in post processing.The correction is implemented by using a tool within the acstools python package called acs_destripe_plus. This tool is useful for when built-in calacs de-striping algorithm using overscans is insufficient or unavailable. The use of this tool to apply CTE correction is limited to the following cases:As a reminder, in order to get the latest CTE correction you will need to install the AstroConda environment. This will include acstools and other python packages that you will need. Instructions on how to install AstroConda can be found in the Astroconda website.For this example we will use the observation of the 47 Tuc calibration field with rootname JD5702JPQ, which we have copied to a file called filename.fits in the following example. These data were taken using the WFC1B-1K aperture. This is a 1024 x 2048 pix sub-array.
The tool will take some time to run. In an 8 core machine it takes 3 minutes for the CTE correction to complete.This tool will give you and FLT and an FLC file. The FLC file is the one that has been CTE corrected.The subarray products produced by this process do not have the proper WCS information in the header. This is normally done by the pipeline via an additional call to AstroDrizzle. You can do this yourself with two python commands:
from stwcs import updatewcsWith that, you should have calibrated files ready for scientific analysis or to process using Astrodrizzle.