Last modified: March 2023

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/ecf_calc.html
AHELP for CIAO 4.16

ecf_calc

Context: Tools::Response

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.