/ ciao4.17 / ahelp / bkg_fixed_counts.html

Jump to: Description · Examples · Parameters · Changes in scripts 4.16.1 (April 2024) release · Changes in scripts 4.15.2 (April 2023) release · Relation to acis_extract · About Contributed Software · Bugs · See Also

AHELP for CIAO 4.17

bkg_fixed_counts

Context: tools::region

Synopsis

Create a background region with a fixed number of counts

Syntax

bkg_fixed_counts  infile outroot pos min_counts [src_region] [fovfile]
[max_radius] [inner_ecf] [energy] [verbose] [clobber]

Description

'bkg_fixed_counts' will create a annular background region at each input source position that encloses a minimum number of counts. The inner annulus radius is determined from the size of the PSF at that location, which encloses the inner_ecf fraction of the PSF at the specified value of energy. Users can specify a maximum radius to keep the background region from becoming too large (and thus possibly becoming non-representative of the source region).

The background excludes other overlapping inner_ecf regions. If the src_region's are specified, the background regions will also exclude those source regions.

The background is also bound by the input fovfile which is needed if any of the regions intersect the edge of the detector.

The output will be one file for each input source position. The output will be a FITS region file (in physical coords, as all FITS region files are). The output file names will look like ${outroot}_i${src_number}_bkg.reg, where outroot is the user supplied output root file name, and src_number is the source number matching the input positions (going from 1 to N, where N is the number of positions).

Examples

Example 1

% bkg_fixed_counts infile=acis_evt.fits outroot=my_catalog
pos=my_catalog.fits min_counts=100

This will create annular background regions centered at each RA and Dec position from the input table: my_catalog.fits. Each background region will include 100 counts (as determined from the input event file: acis_evt.fits), and will be written out into individual FITS region files my_catalog_${n}_bkg.reg; where ${n} is the row number in the input catalog. The inner radius of the annulus will be computed as as the radius of a circle that encloses 95% of PSF at 1.0keV (default parameters).

Example 2

% bkg_fixed_counts infile=acis_evt.fits"[energy=500:7000]"
outroot=my_catalog pos=my_catalog.fits min_counts=100

Same as the previous example, but only consider events in the energy range from 500 to 7000 eV.

Example 3

% bkg_fixed_counts infile=acis_evt.fits outroot=my_catalog
pos=my_catalog.fits min_counts=100 \
energy=2.0 inner_ecf=0.98 max_radius=128

Same as Example 1, but the inner radius will be the size of the PSF at 2.0keV that encloses 98% of the PSF. Also, there is an 128 pixel outer radius threshold applied; that is the maximum radius allowed, meaning that there may be some regions with fewer than 100 counts.

Example 4

% bkg_fixed_counts infile=acis_evt.fits outroot=my_catalog
pos=my_catalog.fits min_counts=100 \
src_region=@my_catalog_src.lis

where the input stack: my_catalog_src.lis looks like

% cat my_catalog_src.lis
my_catalog_i0001_src.reg
my_catalog_i0002_src.reg
my_catalog_i0003_src.reg
my_catalog_i0004_src.reg

This is similar to Example 1, but now a stack of source region files has been provided. These source regions will also be excluded from the background regions, in addition to the inner 95% ECF region.

Example 5

% bkg_fixed_counts infile=acis_evt.fits outroot=my_catalog
pos="12.34,-56.789" min_counts=100

This is similar to Example 1, except a single source position has been specified in decimal degrees. The pos parameter can also be specfied in color-separated sexagesimal format, eg "12:34:56.7 -8:9:10.11".

Parameters

name	type	ftype	def	min	max	units	reqd	stacks
infile	file	input					yes
outroot	file	output					yes
pos	file	input					yes
min_counts	integer		10				yes
src_region	file	input						yes
fovfile	file	input
max_radius	real		INDEF			pixels
inner_ecf	real		0.95	0.9	0.99
energy	real		1.0	0.3	10.0	keV
verbose	integer		1	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input event file.

The input event file is used to determine the number of counts in the background region. Users can filter the background event file if they wish to only consider events in certain energy bands.

Parameter=outroot (file required filetype=output)

The root of the output file names

If the output root contains a directory, then that directory must already exist.

Parameter=pos (file required filetype=input)

Input position.

The input position can either be a pair of celestial coordinates or can be a table with RA and DEC columns.

Parameter=min_counts (integer required default=10)

The target minimum number of counts in the background region

The minimum number of counts may not be met if the user specifies a value for the max_radius parameter.

The user may also see small differences in the number of background counts when filtering an image vs filtering an event file.

Parameter=src_region (file filetype=input stacks=yes)

A stack of source regions to exclude.

In addition to excluding the inner ECF PSF fraction radius, users can exclude source regions from the background.

The input stack can also contain other regions that the users wishes to exclude such as for the readout streak.

Parameter=fovfile (file filetype=input)

Field-of-view file name

The background regions will be intersected with the FOV region if supplied. It is necessary to include the FOV when the background regions intersect the edge of the detector to ensure that the area of the region can be computed correctly. Otherwise the FOV file does not affect how the background region is created.

Parameter=max_radius (real default=INDEF units=pixels)

The maximum allowed outer radius, in pixels.

The background region should be located close to the source region. However, for low count observations the background radius needed to obtain the requested number of background counts may grow very large. If this parameter is set, then it will limit the outer radius size to this value.

Setting this parameter to 'INDEF' removes any limit on the background radius.

Parameter=inner_ecf (real default=0.95 min=0.9 max=0.99)

The PSF ECF size to use for the inner annulus radius.

The background region is an annulus located at the source position. The inner radius is obtained by finding the size of the PSF at that location which encloses this fraction of the PSF at the specified energy. The outer radius then is computed to enclose the specified minimum number of counts.

Parameter=energy (real default=1.0 min=0.3 max=10.0 units=keV)

The energy used for the PSF size lookup, in units of keV.

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

Amount of tool chatter level.

Parameter=clobber (boolean default=no)

Overwrite output files if they already exist?

Changes in scripts 4.16.1 (April 2024) release

Fixed an issue when the stack of input source regions contains empty/NULL regions; for example when a source region is entirely outside the field-of-view.

Changes in scripts 4.15.2 (April 2023) release

Internal rework of coordinate parsing.

Relation to acis_extract

This script is inspired by the acis_extract tool developed by the ACIS IPI team at PSU.

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.

Bugs

There are no known bugs for this tool.