/ ciao4.16 / ahelp / acis_bkgrnd_lookup.html

Jump to: Description · Examples · Parameters · Changes in the CIAO scrips 4.9.1 (December 2016) Release · Changes in the CIAO 4.8.1 (December 2015) Release · Changes in the CIAO 4.6.1 (December 2013) Release · About Contributed Software · Bugs · See Also

AHELP for CIAO 4.16

acis_bkgrnd_lookup

Context: Tools::Background

Synopsis

Find the matching ACIS "blank-sky" dataset for an observation

Syntax

acis_bkgrnd_lookup  infile [outfile] [blname] [verbose]

Description

The acis_bkgrnd_lookup script is used to find the ACIS background (i.e. "blank sky") dataset from the CALDB that matches your observation. It is suggested that you the read the following before using the background files in your analysis:

- ACIS Background Memos page

- Maxim Markevitch's ACIS background discussion

- The ACIS Background Subtraction thread

The results of the CALDB search are written to the outfile parameter as well as being written to the screen, making them accessible by calling

pget acis_bkgrnd_lookup outfile

Output

If more than one file is found then they are listed on the screen one to a line and written to the parameter file as a comma-separated list (i.e. a stack). This will be the case, for instance, if the input file contains data from more than one CCD. See "ahelp stack" for more information on handling stacks.

Examples

Example 1

unix% acis_bkgrnd_lookup evt2.fits
unix% set bfile = `pget acis_bkgrnd_lookup outfile`

The script finds the aimpoint, focal plane temperature, and details on the CTI correction from information in the header of the file and uses the ccd_id column of the event file to select the chips which contain data.

The matching file(s) are printed to the screen and stored in the outfile parameter of the script. We use the pget command to get this value from the parameter file.

Example 2

unix% acis_bkgrnd_lookup "evt2.fits[sky=region(source.reg)]"

The input file can include any Data Model expression (see "ahelp dmsyntax") as long as the resulting file is still a table with a ccd_id column. Here we use a spatial filter to filter the events file: the resulting background file(s) will be chosen to match only the CCDs that cover the region source.reg.

Example 3

unix% acis_bkgrnd_lookup img.fits

In this case the input file is an image, rather than an event file. The list of CCDs to use in the search is taken from the ccd_id filter recorded in the data subspace of the file; this can be seen by using the "subspace" option of dmlist, such as in this example

unix% dmlist img.fits subspace | grep ccd_id
   2 ccd_id               Int2                3:3
   2 ccd_id               Int2                2:2
   2 ccd_id               Int2                1:1
   2 ccd_id               Int2                0:0

See "ahelp subspace" for more information on the subspace information recorded in files.

Parameters

name	type	def	min	max	reqd	stacks
infile	file				yes
outfile	file					yes
blname	string	none
verbose	integer	0	0	5

Detailed Parameter Descriptions

Parameter=infile (file required)

The file for which you want background files

The file must contain a CTI_APP keyword.

If the input file is an image then the ccd_id subspace filter is used to determine which ACIS chips should be searched for. If the input file is a table then a combination of the ccd_id subspace and ccd_id column are used to determine which chips to use.

Parameter=outfile (file stacks=yes)

ACIS background file(s) to use

This parameter will be set to the name(s) of the ACIS background files selected from the CALDB to match your observation. The file names include the full path. If more than one file is selected then they will be stored as a comma-separated stack.

Parameter=blname (string default=none)

What block identifier should be added to the filename?

This parameter determines whether any block identifier should be included in the filename and, if so, what form should the identifier be in. The allowed values are:

blname=none

No identifier is added; this is the default value. The output will look something like

acis1sD2000-01-29bkgrnd_ctiN0005.fits

blname=name

Add the name of the block to the file, so the output will look something like

acis1sD2000-01-29bkgrnd_ctiN0005.fits[EVENTS]

blname=number

Add the number of the block to the file using the DataModel numbering scheme ([1] refers to the first block). The output will look something like

acis1sD2000-01-29bkgrnd_ctiN0005.fits[2]

blname=cfitsio

Add the number of the block to the file using the CFITSIO numbering scheme ([0] refers to the first block). The output will look something like

acis1sD2000-01-29bkgrnd_ctiN0005.fits[1]

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

Debug level (0=no debug information)

In most cases the default verbose level (of 0) is the correct value to use. Higher values may prove useful when trying to track down problems with the script. Two useful values are:

Verbose=2

Setting verbose=2 will display the version of the script being used together with basic information derived from the input file. It also lists the equivalent calquiz call (or calls) that you would need to make to select the files.

Verbose=5

Setting verbose=5 lists the CALDB lookup that the script is using to select the background file.

Changes in the CIAO scrips 4.9.1 (December 2016) Release

The code has been updated for changes in CIAO in this release.

Changes in the CIAO 4.8.1 (December 2015) Release

The code has been updated to avoid warning messages from NumPy version 1.9. There is no difference to how the script behaves.

Changes in the CIAO 4.6.1 (December 2013) Release

It is now possible to set infile to an image which contains data from multiple ACIS chips (bug fix).

About Contributed Software

Downloading the script

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.

Downloading the CALDB background files

The ACIS background files are packaged separately from the main CALDB download file and are available from the CALDB download page.

Bugs

There are no known bugs for this tool.