arfcorr

Synopsis

Calculate a point source aperture correction, either as a single-energy image or as an energy-dependent correction to the ARF file.

arfcorr  infile arf outfile region x y [energy] [e_step] [radlim]
[nsubpix] [nfracpix] [ecffile] [tmpdir] [verbose] [clobber]

Description

arfcorr calculates the energy-dependent point-source aperture correction for a source within a user-supplied region. It can be used in two ways.

In the first method (ARF correction), the user supplies an ARF, and provides a corresponding input image, a source position in sky coordinates, and a region (which does not have to include the source position). The arfcorr tool uses the CALDB enclosed counts fraction calibration to estimate the fraction of the source's counts lying in the region at each energy, and creates a copy of the ARF with the energy-dependent correction applied.

In the second method (ECF image), the user supplies the input image, sky coordinate source position and region, and specifies an energy value in keV. The arfcorr tool then generates an image with a simulated circularly symmetric PSF, generated to have the correct encircled count fraction at each radius, using the CALDB enclosed counts fraction for the given input energy. The region is then applied to the generated image to determine the aperture correction value, which is printed. This mode may be useful to estimate the alpha and beta parameters used in the aprates tool.

When should arfcorr be used?

An aperture correction should be applied to the ARF unless the source is extended compared to the local PSF; however if the source extraction region is much larger than the the local PSF, then the correction is unity at all energies and may be omitted. That is:

• pointlike source on-axis: create the response with mkarf, then correct it with arfcorr
• extended source: create the response with mkwarf, do not apply arfcorr. Note that even for a small extraction region covering a small fraction of an extended source, an aperture correction is unsuitable because the flux lost from the region due to PSF spillover is compensated by flux spilling into the region from the rest of the source.
• pointlike source off-axis: create the response with mkwarf, then correct it with arfcorr (you may wish to experiment as the correction may be omitted as negligible if the extraction region is sufficiently large). Note that use of mkwarf rather than mkarf is recommended to average the detector response since the PSF is spread over many pixels.
• arfcorr should not be applied to background ARFs, since the background is an extended component.

Types of Output

When the energy parameter is zero, an input ARF must be supplied and the ARF correction mode is used. The PSF fraction (ECF) within the region is calculated for every Nth energy value in the ARF and applied to each entry in the ARF by linear interpolation. The value of N is controlled by the e_step parameter whose default is 50 (this is a compromise between accuracy and a reasonable computation time; note that the first and last energy values in the ARF are always calculated rather than interpolated). The output file in this case is a copy of the input ARF with two column changes:

When the energy parameter is zero, an input ARF must be supplied. The PSF fraction within the region is calculated at each energy value in the ARF. The output file in this case is a copy of the input ARF with two column changes:

• an additional column, "PSF_FRAC", lists the fraction of PSF counts within the input region at each energy (i.e., the ECF at each energy).
• the "SPECRESP" column values have been multiplied by the PSF_FRAC value, resulting in column values of effective area scaled by the ECF.

When using this mode (energy=0, ARF file specified), calculating the PSF ECF at each energy specified in the ARF can be time consuming. An alternative approach is to calculate the ECF at specific energies and linearly interpolate between the calculated values to determine the intermediate ECFs. For instance, e_step=50 (the default) reads every 50 energies from the ARF and interpolates the ECF at the intermediate 49 energy values. Note that for any value of e_step, the ECF at the first and last energies is always calculated instead of interpolated.

The Approximate PSF Image

When the energy parameter is set to a non-zero value, the ECF image mode is used. The calculated PSF fraction for that energy is printed to the screen (for verbose > 0 ) and an image of the circular approximation to the PSF is created in the output file, matching the image size of the input image.

The value of each pixel in the approximate PSF image is the fraction of counts enclosed by the area of that pixel. The image is generated from a symmetrical model of the PSF built from calibration data that list the radial distances at which each successive one percent of PSF counts are encircled. Since the PSF is infinite, an approximation is needed to define an artificial outer boundary to constrain the model PSF to be finite. The radlim parameter governs the distance of this boundary. The outer edge of the generated PSF will be equal to the distance enclosing 99% of the PSF counts multiplied by radlim.

The PSF model amplitude may vary over the area of the pixel, but each pixel can have just a single value for counts fraction. To determine that value, the area of the pixel is divided into a regular n by n grid, where n is the value of the parameter nsubpix. The PSF model is sampled over this grid and the average of the samples is used to determine the PSF image pixel value.

The parameter nfracpix governs what portion of an approximate PSF image pixel is counted as inside the input region for pixels which lie at the edge of the region. If nfracpix=1 (the default), the entire counts fraction for the pixel is counted as inside the region if the center of pixel is within the region. If nfracpix is greater than 1, the image pixel is sampled at a regular grid of nfracpix by nfracpix locations. At each location within the region, the value 1/(nfracpix^2) of the counts fraction for the pixel is counted as inside the region.

Caveat: Analysis at the Chip Edge

The response tools for spectral extraction (specifically the ARF) assume that 100% of the PSF is enclosed - i.e. on the chip - all the time, which may not be the case. arfcorr does not correct for the amount of aperture that falls off the chip, as it doesn't know where the chip edges and gaps are.

For extended source analysis, the sky2tdet tool does correct for the weighted aperture area that falls off-chip.

Examples

Example 1

arfcorr infile=pstamp.fits arf="" outfile=image.fits
region="region(reg.fits)" x=5087.5 y=4330.2 energy=2.3 radlim=3.0
verbose=1

Create an approximate PSF image from data matching the size and scale of the input pstamp.fits file. The PSF will be centered at sky x,y coords = (5087.5, 4330.2). No ARF is required since a specific energy of 2.3keV has been input.

In creating the symmetrical PSF model, chose the artificial finite edge of the PSF to be 3 times the radius that encloses 99% of the counts (radlim=3). Print the energy and ECF to the screen (verbose=1) in addition to creating the PSF image.

Example 2

arfcorr infile=image.fits arf=arf.fits outfile=new_arf.fits
region="circle(4096.5,4096.5,10)" x=4096.5 y=4096.5 energy=0.0
e_step=100 verbose=0

Calculate the fraction of PSF counts enclosed (ECF) in the input region reg.fits at all energies specified in the input arf.fits file. Generate a calibration-based symmetrical PSF model for the first, last, and every 100 energies (e_step = 100) in the arf. Calculate the ECF at each energy step and then interpolate the ECF for each energy between the steps. The PSF will be centered at sky x,y = (4096.5,4096,5).

The output file, new_arf.fits, is a copy of arf.fits. A new columns, PSF_FRAC, shows ECF for each energy. The SPECRESP column in new_arf.fits is also scaled by the PSF_FRAC value for that energy.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input image file

In ECF image mode, the input image file is used as a template for the approximate PSF image. The PSF image will have the same size and scale as the image file. To reduce computation time, use of a cutout (or filtered) input image which is large compared to the PSF but small compared to the entire ACIS field is recommended.

In ARF correction mode, temporary versions of such approximate PSF images are made at each energy step, and used to derive the correction factor for that energy step. The input image is again used to determine the size and scale of these temporary images, and so use of an appropriate cutout size is recommended.

Parameter=arf (file required filetype=input)

Input Auxiliary Response File (ARF)

In ARF correction mode (energy parameter set to 0), the input ARF is used as a basis for the output ARF. It is also used, with the e_step parameter, to define the energies at which the symmetrical PSF model images are generated to calculate correction factors.

In ECF image mode (energy parameter positive), the value of the arf parameter is ignored and can be blank.

Parameter=outfile (file required filetype=output)

Output file

In ARF correction mode, the output file is a modified copy of the input ARF with corrected SPECRESP values and a correction factor column added.

In ECF image mode, the output file is the simulated PSF image generated using circularly symmetric encircled energy factors.

Parameter=region (string required default=)

The region used to calculate the PSF ECF

The region used to limit the spatial range over which the fraction of PSF counts is calculated.

The region can be supplied as a string, e.g. "", or in an ASCII or FITS file. If using a file, it must be wrapped in the Data Model region file syntax: "region(sources.fits)".

Parameter=x (float required default=INDEF)

Calculate model PSF at this SKY x location

Specifies the x pixel location (in the SKY coordinate system of the input image file) of the source position that will be used to generate the calibration data-based symmetrical model PSFs used in the calculation.

Parameter=y (float required default=INDEF)

Calculate model PSF at this SKY y location

Specifies the y pixel location (in the SKY coordinate system of the input image file) of the source position that will be used to generate the calibration data-based symmetrical model PSFs used in the calculation.

Parameter=energy (float not required default=INDEF units=keV)

Energy in keV at which the PSF ECF is calculated

If this parameter is nonzero, ECF image mode is used and a PSF model image for this energy is generated.

If this parameter is zero, ARF correction mode is used and the ARF and e_step parameters are used to determine which energies will be used in the calculation.

Parameter=e_step (integer not required min=1)

Energy bin stepsize.

In ARF correction mode, a PSF correction is estimated for each energy in the input ARF. This is done by generating monochromatic simulated PSF images at a subset of the energies, evaluating the PSF correction within the region at those energies from the images, and then using linear interpolation to determine the correction for the remaining energies. If the ARF has n rows (n energies), the images are generated every e_step rows, i.e. for energy row 1, 1 + e_step, 1 + 2e_step,... 1 + m * e_step, where m ~ n/e_step. In addition, an image is always generated for the last row, row n.

While higher accuracy may be gained by setting e_step to 1, the uncertainties in the calibration and method do not warrant the expense in added computation time, and we recommend keeping e_step at a large value.

The e_step parameter is ignored in ECF image mode.

Parameter=radlim (float not required)

Radius factor to calculate finite PSF model boundary

In this tool the PSF is modeled as having finitely extended wings. The outer edge of the model PSF which encloses 100% of the counts is set equal to the calibrated radius which encloses 99% of the counts multiplied by radlim. So, for the default value of radlim = 2, if the 99 percent encircled count radius at the selected energy is r, then we truncate the PSF at a radius 2r and spread the remaining 1 percent of the counts between r and 2r.

Parameter=nsubpix (integer not required)

Subpixelization (1d) of PSF pixels to average pixel value from PSF model

To determine a value for each PSF image pixel the symmetrical PSF model is sampled using a grid of regularly spaced points in the pixel. nsubpix by nsubpix points are used, so that 25 points are sampled for the default nsubpix value of 5, and only the center is sampled if nsubpix is set to 1. The average over all points is used to calculate the PSF image pixel value. Larger values of nsubpix increase accuracy but also increase execution time.

Parameter=nfracpix (integer not required)

Subpixelization (1d) of ECF pixels when calculating enclosed PSF counts

The arfcorr nsubpix value is use when creating the model psf. For each pixel in the input image, it computes the "height" of the model psf on a 5x5 subpixel grid w/in the pixel and then uses the average of those values as "the" pixel value. The nfracpix value is then used when computing the PSF fraction. When checking for "insideness", the model pixel is broken up into nfracpix x nfracpix (default: 1x1) grid each with 1/(n^2) of the fraction of the pixel value and the fraction-subpixel values that are in the region then add to the final PSF fraction.

Parameter=ecffile (file not required filetype=input default=CALDB)

Enclosed counts fraction (ECF) calibration file

Parameter=tmpdir (file not required filetype=input default=${ASCDS_WORK_PATH})

The directory to use for temporary files.

Parameter=verbose (integer default=0 min=0 max=5)

How much output should be printed to the screen

Parameter=clobber (boolean default=no)

Overwrite output file if it exists?

Changes in CIAO 4.15

The header of the new file (the outfile parameter) will now contain the parameter settings for this tool. It can be retrieved with the dmhistory tool or the get_history_records method of the pycrates python library.

• The script now writes proper history records

Bugs

Caveats

ARF correction may be incorrect for small regions

When using an input arf file and region, the input infile image should be binned at a resolution smaller than the region size. For example, if using a circle with a 1 ACIS pixel radius (0.5"), the infile image should be binned at subpixel resolution.

Using an input image with a binsize comparable to the size of the region does not provide arfcorr enough pixels to compute an accurate model of the PSF and therefore the corrections to the ARF become inaccurate.

See Also

tools

aconvolve, acrosscorr, arestore, arfcorr, dmcoords, dmfilth, dmregrid, install_marx, make_psf_asymmetry_region, psf_project_ray, psfsize_srcs, simulate_psf, src_psffrac