lim_sens

Synopsis

Create an output limiting sensitivity map with the same blocking factor, dimensions and WCS

lim_sens  infile psffile outfile [expfile] [rbkfile] [bscale]
[snr_limit] [const_r] [clobber] [verbose]

Description

Limiting sensitivity is the flux of a point source that meets but does not exceed the flux significance threshold. It is a function of source position, background, and the algorithm used to calculate flux and flux significance. It differs from and is higher than the source detection limit (e.g., a 5 count source in a low background observation can be detected at high confidence, but its flux significance is less than 3sigma).

Limiting sensitivity is a "field property" (like the exposure map). It can be used to provide a simple x-ray flux limit for individual sources detected at other wavelengths, and is required to calculate sky coverage histograms (solid angle surveyed as a function of limiting flux), which are themselves needed to calculate luminosity functions and logN-logS.

Examples

Example 1

lim_sens bkg.fits psf.fits output.fits exp=exp.fits rbkfile= bscale=5
snr_limit=3 const_r=no clobber=yes

In this example, bkg.fits will be used to generate randomized background map based on Poisson-distributed random numbers. The psf.fits file and exp.fits file will be used in determining the calculations based on a bscale of 5 and snr_limit of 3 in creating the limiting sensitivity map.

Example 2

lim_sens bkg.fits psf.fits output.fits exp=exp.fits rbkfile= bscale=5
snr_limit=3 const_r=yes clobber=yes

In this example, the parameter const_r is set to yes. This will set the Aperture Background Area / Aperture Source Area (Ab/As) to a fixed value of (bscale^2 - 1).

Example 3

lim_sens bkg.fits psf.fits output.fits exp= rbkfile= bscale=5
snr_limit=3 const_r=no clobber=yes

In this example, the parameter expfile is left blank. This will make the assumption that Average Background Aperture Exposure Map Value ~= Average Source Aperture Exposure Map Value (Eb ~= Es)

Example 4

lim_sens bkg.fits psf.fits output.fits exp= rbkfile= bscale=5
snr_limit=3 const_r=yes clobber=yes

In this example, the parameter expfile is left blank and the const_r parameter is set to yes. This will make the assumption that Average Background Aperture Exposure Map Value ~= Average Source Aperture Exposure Map Value (Eb ~= Es) and will set the Aperture Background Area / Aperture Source Area (Ab/As) to a fixed value of (bscale^2 - 1).

Example 5

lim_sens bkg.fits psf.fits output.fits exp= rbkfile=rbk_out.fits
bscale=5 snr_limit=3 const_r=yes clobber=yes

In this example, the parameter expfile is left blank and the const_r parameter is set to yes. This will make the assumption that Average Background Aperture Exposure Map Value ~= Average Source Aperture Exposure Map Value (Eb ~= Es) and will set the Aperture Background Area / Aperture Source Area (Ab/As) to a fixed value of (bscale^2 - 1). Also the rbkfile parameter has a value of rbk_out.fits. This will create an additional output of the generated random background map that is created using the Poisson-distributed random numbers.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The name of the input background file.

The input may be any background file, such as a level=3 background from the Chandra Source Catalog or one of the ACIS blank-sky background files. The background file is used to generate randomized background map based on Poisson-distributed random numbers with the background file values used as the means.

Caveat: the background output from the wavdetect tool is not appropriate for use here, in particular when an exposure map was used in the wavdetect run. The wavdetect background in this case was already exposure-corrected/normalized. Using such a file in lim_sens with an exposure will double-correct the exposure.

The infile, expfile, and psffile images should be the same size.

Parameter=psffile (file required filetype=input)

The name of the input psf file.The psf file is used to determine the inner annulus size at a particular pixel in the map.

If the PSF image was created with the mkpsfmap tool, ensure that the 'units' parameter was set to 'logical'.

The infile, expfile, and psffile images should be the same size.

Parameter=outfile (file required filetype=output)

The name of the output file. This will be the name of the created output limiting sensitivity map.

The output values are the flux of a point source that meets but does not exceed the flux significance threshold, assuming the input background and background scaling factor.

The units depend on the input files. If an exposure map is provided, the units are [photons/cm^2/sec]. Without an exposure map, the units are [counts].

Parameter=expfile (file not required filetype=input default=)

The name of the optional input exposure map file.

The exposure map file is used in calculating the r value with is the ratio of background to source. If expfile is set, const_r should be set to "no" (the default).

If the parameter is left blank, then the assumption is made that (Eb ~= Es).

Parameter=rbkfile (file not required filetype=output default=)

The name of the optional output random background map file. This will create an additional output of the generated random background map that is created using the Poisson-distributed random numbers. If this output is not desired leave the parameter with the default empty string.

Parameter=bscale (integer not required default=5)

The bscale parameter is the value of (alpha * Es). If the paramer is not specified the default value of five (5) will be used.

Parameter=snr_limit (real not required default=3)

The snr_limit parameter specifies the minimum for the signal to noise for the output limiting sensitivity map.

Parameter=const_r (boolean not required)

The boolean parameter const_r specifies by yes/no value whether to assume a constant r value. Which means the assumption r ~= (Ab/As) will be a constant value will be made.

Parameter=clobber (boolean not required default=no)

If clobber=yes and a file exists that has the same name as the name of the output file, then the existing file is overwritten. If clobber=no, then the existing file remains unchanged.

Parameter=verbose (integer not required default=0 min=0 max=5)

This parameter determines the amount of messages that is generated by lim_sens. If verbose=0, very few messages are reported. If verbose=5, the largest amount of messages is produced.

Bugs

There are no known bugs for this tool.

See Also

tools

aprates, dmstat, lim_sens, srcextent, srcflux