arfcorr

Synopsis

Determine the approximate fraction of the point spread function (PSF) enclosed by a region.

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

Description

arfcorr calculates the energy-dependent point-source aperture correction for an ACIS source within a user-supplied physical-coordinate region, and optionally applies the correction to the ARF file.

In normal use, the user supplies an input image, a source position in sky coordinates, a region (which does not have to include the source position) and an ARF. arfcorr 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.

Instead of supplying an arf, the user can supply a single energy value in keV; in this case the output file is the simulated circular PSF image at that energy, and the corresponding aperture correction value 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 set to a non-zero value, 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.

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 second mode (energy=0, ARF file specified), calculating the PSF ECF at each ARF specified energy (e_step=1) 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

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.

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

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.

Parameter=arf (file required filetype=input)

Input Auxiliary Response File (ARF)

The ARF is used to define the energies at which the symmetrical PSF model is calculated and as a basis for the output ARF when the input energy parameter is set to 0. If a specific energy is specified, the ARF parameter is not used and can be blank.

Parameter=outfile (file required filetype=output)

Output file

The output file is either the approximate PSF image when a specific energy has been input, or a modified copy of the input ARF file when energy is specified as 0.

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 must be in physical pixel coordinates; for this release of arfcorr, we do not support regions given in RA and Dec. See the tool dmmakereg for a command-line method of converting regions from celestial to physical coordinates.

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 location for the calibration data-based symmetrical model PSF in the SKY coordinate system of the input image file.

Parameter=y (float required default=INDEF)

Calculate model PSF at this SKY y location

Specifies the y location for the calibration data-based symmetrical model PSF in the SKY coordinate system of the input image file.

Parameter=energy (float not required default=INDEF)

Energy at which the PSF ECF is calculated

Specifies the desired energy (keV) at which the approximate PSF model is calculated. If energy = 0, ECFs are calculated at energies read from the input ARF at intervals of input parameter e_step, and always include the first and last energy. ECFs at intervening ARF energies are still reported, but interpolated.

Parameter=e_step (integer not required min=1)

Energy stepsize.

When the energy parameter is set to 0, the symmetrical PSF model can be calculated at all the energies in the ARF (e_step = 1) or some subset of energies. The PSF model is always calculated at the first energy, and then calculated only at every subsequent 'e_step' energy in the ARF. An ECF is determined from the symmetrical PSF model at each energy read from the ARF. ECFs for other energies are interpolated from calculated ECF values. The symmetrical PSF model is always calculated at the first and last energy regardless of the value of e_step.

Parameter=radlim (float not required)

Radius factor to calculate finite PSF model boundary

The PSF is modeled as a finite distribution in arfcorr. The outer edge of the PSF which encloses 100% of the counts is set equal to the radius which encloses 99% of the counts multiplied by radlim.

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 counts that a PSF pixel at the edge of the input region contribute to the enclosed counts calculation is determined by nfracpix. nfracpix by nfracpix subareas of the edge pixel are individually examined, and the counts represented by that fraction subarea of a pixel are added to the enclosed counts total only when the subarea's center is within the region. For the default nfracpix value of 1, all the counts represented by that pixel are included in the enclosed counts total if the center of the pixel is within the region.

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

Enclosed counts fraction (ECF) calibration file

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.4

• The tool has been rewritten in Python. The functionality of the tool is unchanged.

Bugs

Tool does not add a history entry to the header.

The tool does not add a history entry to the output file header, which means the dmhistory tool cannot be used to recall the command.

See Also

tools

aconvolve, acrosscorr, arestore, dmcoords, dmfilth, dmregrid, make_psf_asymmetry_region, mkpsf, psf_project_ray