enen-evts - generate encircled energy function and radial profiles of an object
enen-evts [options] FITS event filename
enen-evts generates an encircled energy function (the fraction of
the total energy in circular apertures as a function of aperture
radius) and a radial profile from a set of events. If the events
contain a single, bright, source, then it should be able to find the
source, determine the center, and generate its products with little
user interaction. If the event file is more complex, the user will
need to provide some information to help it find the source to be
analyzed, and limit confusion with any nearby source.
It processes a FITS event list, assuming that there is a single, overwhelmingly bright source relative to the other objects in the frame. It optionally determines the object center, optionally determines a background rate and creates an encircled energy function and radial profile.
The latter two products are plotted and written to disk. (See OUTPUT for information on the format of the output file.)
The program implements the following aglorithm:
The center of the source is determined.
If --force_ctr is specified, the source center is provided by the --xc and --yc options.
If --force_ctr is not specified, the location and scale of the object is determined by iteratively centering on the events.
The iterative method requires an initial guess at the center, which is determined by one of the following methods:
Explicitly, via the --xc and --yc options.
Automatically, by binning the events into an image, and using the coordinates of the brightest pixel as the initial center. This is accomplished via the --pixcent option, which takes an optional integer argument specifying the size in pixels of the image (the image is square). This defaults to 256 pixels.
If none of the above methods is specified, the average event position is used.
An initial clip is performed about the initial center, with the clipping radius provided by the --clip parameter. Events outside of a clipping radius are discarded, and the average center is determined.
After this point, the iterations begin. Events outside of the radius specified via --nsigma (in units if the standard deviation of the events' distribution) are removed, and the average center and the distribution size are redetermined. This step is repeated until either the center hasn't changed, or the absolute change in the center is less than the tolerance specified by the --dtol option.
The --rmax option may be used to remove events further from the center than a specified distance.
The object, center, and the final clipping radius may be optionally displayed via ds9 by specifying --display.
The events are sorted by distance from the determined center.
A background rate is determined if not explicitly specified.
It is determined by counting events in either a user specified
Funtools compatible region, in an annulus, or not at all. The
various options are selected by the --bgsub parameter, which can
take the following values:
noneThe background is set to 0.
The background is set to the specified value, in counts per scaled input unit.
funcnts will be run on the original input file using the region specified via the --bgregion parameter. Note that the row filter specified by --rfilter will not be used. The --bgfilter option may be used to specify a row filter for funcnts.
aveThe background is determined from the event density in the annulus specified via the --bgmin and --bgmax parameters.
The algorithm does not adjust the area if the annulus extends beyond the detector boundaries. Make sure that the annulus is fully on the detector!
fitThe background is determined by fitting the cumulative sum of the
events in the annulus specified via the --bgmin and --bgmax
parameters with the function K + bg * PI * r^2.
The events may be binned into bins with a number of counts using
the --fitbin option.
The algorithm does not adjust the area if the annulus extends beyond the detector boundaries. Make sure that the annulus is fully on the detector!
iterfitThe background is determined by fitting the cumulative sum of the
events in the annulus specified via the --bgmin and --bgmax
parameters with the function K + bg * PI * r^2.
The events may be binned into bins with a number of counts using
the --fitbin option.
This option differs from fit in that the annulus is divided into
--bgnstep (possibly overlapping) regions of width --bgwidth,
running from --bgmin to --bgmax. The background is fit in each of
those regions, the resultant source count vs. radius curve is fit by a
spline, and the background value is interpolated at the radius
corresponding to the maximum of the splined source counts.
The source count background value vs. region position curves are plotted.
The algorithm does not adjust the area if the annulus extends beyond the detector boundaries. Make sure that the annulus is fully on the detector!
(Yes, this is a kludge.)
The sum of the events within each event radius is generated and an appropriate number of background events are subtracted from each sum.
These sums may not be monotonically increasing with radii in regions where the source event density is comparable to or less than the background event density. This may be the result of too high a background rate, or due to statistical flucuations in regions where source and background densities are comparable.
Binning the sums before background subtraction provides some protection against that noise, permitting one to delve deeper into the PSF wings. To that end, the the --bgbin option specifies that there be a minimum increase in the number of counts per bin.
The background subtracted sums (which may still not be montonically increasing even after pre-subtraction binning) may be "corrected" via one of the following methods (via the --enenmax option)
truncation at a given radius (--enenmax=float)
truncation at the first maximum in the background subtracted cumulative sum
(--enenmax=fmax)
deletion of bins where the background exceeds the source
(--enenmax=dneg)
Since the sums are cumulative, this doesn't actually change the sum, unless the last bin is deleted. What it effectively does is to increase the bin size in the noisy regions where the background exceeds source. Of course, if the background rate is too high, it'll over subtract the wings and all of the bins beyond the turn-over point will be deleted. But that's actually a feature, not a bug.
The sums may be binned to have a minimum increase of --bin events per bin.
The sums are normalized by the number of source events, which is either the maximum of the "corrected" sums, or if the background has been fit (see --bgsub), by the fit source counts.
These normalized sums are the base encircled energy fractions.
Typically the user would like the encircled energy enumerated at specific fractions, at specific radii, or at whatever comes out of the above algorithm (which is affected by the --bgbin and --bin options). enen-evts will produce one or more of these outputs, which are under control of the --enenf, --enenr, and --enenrbin options.
The radial profile of the source is generated by differentiating the encircled energy data. One or more options may be used to specify the radii at which to determine the profile: --profr, --profrbin, --profnt, and --profnbin.
enen-evts uses long-style options. Options which take values may
be separated from the values by whitespace or the = character.
This specifies the extension HDU in the FITS input file from which to extract events. By default the first HDU containing a table is read.
A CFITSIO compatible filter expression to weed out unwanted rows.
This specifies the X coordinate column in the FITS file. It
defaults to x.
This specifies the Y coordinate column in the FITS file. It
defaults to y.
If specified, event weights should be read from the given column in the FITS file. If not specified, events all have unit weight.
This specifies the radius for initial clipping of the data when enen-evts is performing an iterative centroid.
This must also be specified if --force_ctr is specified and --display is specified (else it isn't possible to know how large to make the image).
If true, the center specified by the --xc and --yc options will be used as the center. The --bgmin and --bgmax parameters must be specified in absolute units (rather than as a multiple of the image standard deviation, as this will not be determined).
Absolute convergence tolerance for the centering algorithm.
This specifies the number of iterations the centering routine should perform.
This specifies the clipping radius, in units of standard deviation, used during the iterative centering stage.
If set, this specifies an initial value (in scaled units) for the X coordinate of the center of the object. See --scale.
If set, this specifies an initial value (in scaled units) for the Y coordinate of the center of the object. See --scale.
If specified, choose the brightest pixel in the image as the initial center. This option optionally takes an integer argument specifying the image size in pixels (the image is square). This defaults to 256.
After determining the center, clip all events outside of this radius (in scaled units).
If specified, the cumulative sum is binned before being background subtracted so that there is a minimum increase of nevents per bin.
This option specifies which background is subtracted. It may
one of
fit,
ave,
none,
iterfit,
region,
number.
The default is none. See above for more details.
This specifies a region to be passed to funcnts. The count density
in that region will be used as the background. Be sure to set
--bgsub to region.
Use this option to specify a row filter to the input file for use when funcnts is run. Note that the --rfilter row filter will not be used. Note that this filter is in funtools format, not CFITSIO format.
These take arguments which specify the inner and outer radii of the
annulus in which to measure the background. The radii are specified
in position units, unless they have a suffix of s, in
which case they are specified in units of the standard deviation of
the event distribution. If not specified, it defaults to 10s,11s.
If specified, the cumulative sum is binned before being fit so that there is a minimum increase of nevents per bin.
The following options allow manipulation of the cumulative sum after background subtraction.
Bin the background subtracted encircled energy data into bins which have a minimum increase of nevents per bin. This occurs after the sum is "corrected".
This option specifies how the sum is "corrected" before being normalized. It takes one of the following values:
The number indicates the radius at which the sum should be
truncated. The exact comparison is <, not <=.
fmaxThis indicates that the sum should be truncated at its first maximum.
dnegThis indicates that bins where the background exceeds the source should be deleted.
It defaults to dneg.
This specifies a string which will prefix all output files. It is required. The encircled energy data will be written out to the file ${tag}_enen.rdb. The radial profile will be written out to the file ${tag}_prof.rdb.
Interpolate the data to determining the encircled energy and radial profile data at the requested points. Defaults to true.
See the individual options for more information on how interpolation affects their behavior.
If none of these options is specified, the default behavior is akin to running with the following options:
--enenf=0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.85,0.9,0.95,0.99 --interpolate
More than one means of specifying the output encircled energy grid may be specified.
This specifies a list of fractional encircled energies for which the corresponding radius should be determined. See Specifying lists of numbers for the valid format of the list.
This is possible only if the encircled energy data are montonically increasing. If interpolation is turned off, the greatest fractions less than the requested ones are output.
This is a list of radii for which the corresponding encircled energy fraction should be determined. See Specifying lists of numbers for the valid format of the list.
Interpolation to the exact radii is meaningful only if the encircled energy fractions are monotonically increasing with radii. If they are not, a warning is output, but the interpolation is performed.
If interpolation is not requested, the greatest radii less than the requested ones are used.
If specified, output the base encircled energy fractions as is. The --bgbin or --bin options effectively specify the bin width.
If none of these options is specified, the default behavior is akin to running with the following options:
--profnbin=10 --interpolate
This specifies the outer radii of the annuli which will be used to determine the radial profile. See Specifying lists of numbers for the valid format of the list.
Output the radial profile data at radii based upon the "corrected" encircled energy data (the base encircled energy data). The --bgbin or --bin options effectively specify the bin width.
Output the radial profile data at radii based on the uncorrected encircled energy data. The --bgbin option effectively specifies the bin width. This is rarely useful without some measure of binning.
Output the radial profile data at radii based on the uncorrected,
background subtracted sums. Negative going bins are discarded
(similar to setting --enenmax to dneg) and the data are rebinned
such that there each bin has at least the specified number of events.
The PGPLOT device to which plots should be output. Some useful devices are:
/xsThis is the default, and plots to a persistent X Windows window.
To have each plot show up in a separate window, use +/xs.
/cpsGenerate color PostScript output sent to files.
The PGPLOT /xs device id to start with (several are required).
If specified, an image of the source and final clipping region is displayed using ds9.
Take (or don't take) the log of the radius when plotting the encircled energy function. Defaults to --log_enen.
The size of a pixel in scaled units. Defaults to the value of --scale. This is only used when displaying the centered image with ds9. See --scale.
This specifies a scale factor to be applied to the event positions (they are multiplied by this factor). See --unit. It defaults to 1.
This specifies positional units. It defaults to pixel.
Print the version and exit.
Print a short help message and exit.
Print a longer help message and exit.
Several options (--enenf, --enenr, --profr) have values which are used to generate lists of numbers.
If the first character of the value is the @ character, the rest is
the name of a file containing numbers, one per line. Otherwise, the
value should be a comma separated list of numbers.
Numbers may be either simple (just a floating point number), or may describe a sequence. Sequences may have one of the following forms:
[min]:max:[op]step [min]:max:[op]step:nstep
where elements in square brackets are optional. If min is omitted,
the last number (either generated or provided by the user) is used as
the starting point. op may be one of -, +, or *. If it
is omitted, it defaults to +. The sequence ends either when the
number exceeds max or when nstep numbers are generated.
Some examples and their output:
1:10:1 => 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 1:10:1:5 => 1, 2, 3, 4, 5 1:10:*2 => 1, 2, 4, 8 10:1:-1 => 10, 9, 8, 7, 6, 5, 4, 3, 2, 1
The following plots are produced:
The uncorrected, background subtracted encircled energy is plotted,
along with the annular background regions (see --bgmin and
--bgmax).
Hardcopy is written to files with the prefix ${tag}_enen.
The cumulative, non-background subtracted sum is plotted, as well
as the source+background fit if specified with --bgsub.
Hardcopy is written to files with the prefix ${tag}_sum.
The residuals to the fit to the source+background are plotted,
if the background was fit (via --bgsub).
Hardcopy is written to files with the prefix ${tag}_resid.
If iterative fitting is requested, plots of the fits are generated.
Hardcopy is written to files with the prefixes ${tag}_bg_iter_cts and
bg_iter_bg.
The requested (via --profr, --proft, and --profnt radial
profiles are plotted.
Hardcopy is written to files with the prefix ${tag}_prof.
The encircled energy and radial profile data are written out as RDB tables.
The RDB table has the following columns
The fraction of the encircled energy
The radius of a circle enclosing the fractional energy.
The background subtracted number of counts inside the circle enclosing the fractional energy.
The statistical error in the encircled energy fraction. This does not take into account the error in the background determination. If events are weighted, this does not take into account the background at all.
The option which resulted in the output data. It is one of
enenf enenrbin enenr
The RDB table has the following columns
The background subtracted surface brightness
The statistical error in the surface brightness
The average radius of the annulus
the lower and upper bounds of the annulus
The counts used to determine the surface brightness.
The option which resulted in the output data. It is one of
profr proft profnt
enen-evts --profr=0.01:20:1.1:60 \
--force_ctr --xc=16267.5 --yc=16443.5
--tag=test --verbose \
--bgmin=500 --bgmax=600 --bgsub=fit hrcf01385N004_evt2.fits
enen-evts --tag=test \
--bgmin=200 --bgmax=400 --bin=500 --profrbin --enenrbin \
--scale=7.59 --unit=arcsec --clip=10 --fitbin>=50 \
hrcf01385N004_evt2.fits
enen-evts --tag=sim --verbose --bgsub=none \
--pix_size=0.024 --dtol=0.001 --unit=mm \
--extname=raytrace --xcol=rt_y --ycol=rt_z \
--display \
/data/fifi/dj/axaf/studies/PSF/arlac/01385/2001-04-23/many/rays/096_sim.fits
Diab Jerius ( djerius@cfa.harvard.edu )