Synopsis
Obtain the encircled counts fraction of an object as a function of radius.
Syntax
ecf_calc infile outfile radius xpos ypos binsize fraction [plot] [clobber]
Description
The ecf_calc tool takes an input event file (including ChaRT/MARX simulations), or image file and extracts the Encircled Counts Fraction (ECF). The ECF is the integrated fraction of the total number of counts (i.e. integrated flux) as a function of radius from the input position. The output is the radii at which the desired input ECFs are met. By definition, ECF=100% at the input radius.
The output radii are saved to the output file and can be plotted optionally with matplotlib when plot=yes.
The ECF data can be used to compare observed data with the point spread function (PSF) to search for extent.
Examples
Example 1
unix% ecf_calc infile=hrcf13182_evt2.fits outfile=ecf.fits radius=13 xpos=16405.337 ypos=16500.457 binsize=0.2
An events file with a source located at the sky coordinates (16405.33,16500.457) returns a ECF profile for a circular region of 13 sky pixels for an image binned with pixel size equal to 0.2.
Example 2
unix% ecf_calc hrcf13182_evt2.fits ecf.fits 13 16405.337 16500.457 0.2 plot=yes
The same example as above, except the profile will be plotted with matplotlib.
Example 3
unix% ecf_calc psf.img ecf_psf.fits radius=12 xpos=4162.7138 ypos=3688.3056 binsize=1
An image of a PSF is input and the ECF profile is computed around the input sky coordinates. Note that image files require binning with an integer value.
Parameters
| name | type | ftype | def | min | reqd | stacks |
|---|---|---|---|---|---|---|
| infile | file | input | yes | no | ||
| outfile | file | output | yes | |||
| radius | real | 20 | 0 | yes | ||
| xpos | real | 4096.5 | 0 | yes | ||
| ypos | real | 4096.5 | 0 | yes | ||
| binsize | real | 1.0 | 0 | yes | ||
| fraction | string | 0.01,0.025,0.05,0.075,0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.85,0.9,0.95,0.99 | yes | yes | ||
| plot | boolean | yes | no | |||
| clobber | boolean | no | no |
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input stacks=no)
Input file
An event file (observed of simulated) or image file.
Parameter=outfile (file required filetype=output)
Output file
Output file name that will contain "fraction" and radius ("r_mid") columns of the profiles. If possible, a transform from pixel radii to angular radii will be available.
Parameter=radius (real required default=20 min=0)
Extraction radius
Radius of the extraction region in pixels.
Parameter=xpos (real required default=4096.5 min=0)
The x-position of the source in sky coordinates.
Parameter=ypos (real required default=4096.5 min=0)
The y-position of the source in sky coordinates.
Parameter=binsize (real required default=1.0 min=0)
Image binning factor
The binning factor has units of pixels, where the value need not be an integer for an events file, and may be be less than 1. For image files, the binning factor must be integer-valued.
Parameter=fraction (string required default=0.01,0.025,0.05,0.075,0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.85,0.9,0.95,0.99 stacks=yes)
Encircled counts fraction.
The set of encircled energy fractions to determine radii. This can be specified using any of the stack syntax, including lgrid() or just a comma separated list (or just a single value). If unspecified - either with "", None, or Indef - the ECFs will automatically be determined using a set of binsize-spaced radii.
Parameter=plot (boolean not required default=yes)
Display encircled counts fraction profile. The user will be prompted to exit.
Parameter=clobber (boolean not required default=no)
Specifies if an existing output file should be overwritten.
Changes in the 4.15.2 (April 2023) release
Updated to skip plots if DISPLAY environment variable is not set.
Changes in the 4.11.4 (2019) release
matplotlib replaces ChIPS for optional plotting display.
Changes in the scripts 4.9.3 (May 2017) release
Fixed the problem when plot=yes is chosen when using Python 3.5.
Changes in the December 2012 release
The script is new for in CIAO 4.5.
About Contributed Software
This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions - such as how to ensure that the parameter file is available.