/ ciao4.17 / ahelp / acis_fef_lookup.html

Jump to: Description · Examples · Parameters · How is the FEF Chosen? · Changes in the scripts 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.17

acis_fef_lookup

Context: Tools::Response

Synopsis

Find the FITS Embedded Function file for use by mkrmf

Syntax

acis_fef_lookup  infile chipid chipx chipy [outfile] [quality] [verbose]

Description

This tool returns the location of the FITS Embedded Function (FEF) file needed by mkrmf to make either a PI or a PHA RMF for a point source observed by ACIS. It is not needed if you are creating a weighted response (ie for an extended source) using mkwarf and mkrmf, since the CALDB can be automatically queried in this case.

When to use mkacisrmf

The script will warn you - if verbose is set to a non-zero value - if the data has been processed in such a way that you should be using mkacisrmf rather than mkrmf to create the response file. This condition is also indicated by setting the quality parameter to "no" on output. See the Creating ACIS RMFs with mkacisrmf why topic for more information.

Output

When run, the tool prints the location of the FEF file (including any necessary spatial filter) to the screen and to its outfile parameter. This makes it easy to use from the shell, or script, since pget can be used to access the file name:

unix% set feffile = `pget acis_fef_lookup outfile`

or the parameter redirection syntax (see "ahelp parameter") can be used:

unix% pset mkrmf infile=")acis_fef_lookup.outfile"

Using acis_fef_lookup

The script can be used in two modes:

Point source
Extended source

FEF for a point source

You must supply the location of the source in CHIP coordinates - ie the value of the ccd_id, chipx, and chipy columns from the event file. The returned file name includes a DM spatial filter which specifies the part of the FEF file to use.

Since the dither pattern of Chandra means that even a point source moves over a non-negligible number of pixels, and likely over multiple FEF tiles, the decision of what location to use is not a simple one, and depends on your science goals and the location of the source (eg is it near a chip gap or does it fall on more than one node).

FEF for an extended source

If you wish to use mkrmf with a weight map, created by mkwarf, then you need the location of the FEF file without the spatial filter used in the point source case. This is achieved by setting chipid to "none" (the values of the chipx and chipy parameters are ignored in this case). However, this step is not needed since mkwarf and mkrmf can accept a CALDB query (e.g. feffile=CALDB) for the FEF file when using weights files.

The CIAO thread pages discuss in greater detail the steps necessary to calculate the ARF and RMF for a source.

Examples

Example 1

unix% acis_fef_lookup evt2.fits 5 512 512
.../acisD2000-01-29fef_pha_ctiN0004.fits[FUNCTION][ccd_id=5,chipx=449:51
2,chipy=449:512]
(the full path has been excluded for brevity)
unix% pget acis_fef_lookup quality
yes

This gives the file name of the FEF file applicable for the observation and position on the detector. As the quality parameter is "yes", rather than "no", then it is okay to use mkrmf to calculate the response for your data.

In this example the input events file is for an obervation at a focal plane temperature of -120 degrees C and which has had the CTI correction algorithm (see acis_process_events) applied to it.

One can then run mkrmf by either explicitly setting its infile parameter to the output of this tool, for instance by using pget (using tcsh shell syntax and again ignoring the full path) -

unix% set feffile = `pget acis_fef_lookup outfile`
unix% echo $feffile
.../acisD2000-01-29fef_pha_ctiN0004.fits[FUNCTION][ccd_id=5,chipx=449:512,chipy=449:512]

- or by using the redirection capabilities of the parameter interface -

unix% mkrmf infile=")acis_fef_lookup.outfile" ...other parameters..

See "ahelp parameter" for more on the parameter interface.

Example 2

unix% acis_fef_lookup evt2.fits none
.../acisD2000-01-29fef_pha_ctiN0004.fits[FUNCTION]
(the full path has been excluded for brevity)

Find the name of the FEF file but without any spatial filter. This is useful when creating weighted responses for extended sources.

Example 3

unix% acis_fef_lookup spectrum_cti.pi none
.../acisD2000-01-29fef_pha_ctiN0004.fits[FUNCTION]
(the full path has been excluded for brevity)

Here we repeat the previous example but using a spectrum (PHA format; the column that was binned on - ie PHA or PI - is unimportant) which was extracted using dmextract from an events file that had been CTI corrected.

Parameters

name	type	ftype	def	min	max	reqd
infile	string	input				yes
chipid	string		none			yes
chipx	integer		1	1	1024	yes
chipy	string		1	1	1024	yes
outfile	string	output				no
quality	boolean		no			no
verbose	integer		0	0	5	no

Detailed Parameter Descriptions

Parameter=infile (string required filetype=input)

Source file (event or spectrum)

The infile parameter can accept any file that contains enough information in its header for the calquiz tool to work; event files (L1 and L2) and PHA-format files produced by dmextract are both suitable.

Parameter=chipid (string required default=none)

ACIS chip number

This parameter is used to define which ACIS chip you want the FEF for. The allowed parameters are 0-9 (for the 10 chips ACIS-0 to ACIS-9) or the string "none". This last option makes the tool ignore the values of the chipx and chipy parameters and just report the FEF file (with block number).

Parameter=chipx (integer required default=1 min=1 max=1024)

ACIS chip x coordinate

The spectral response of the ACIS chips depend on location within the chip (ie in which FEF tile the source falls). The chipid, chipx and chipy parameters specify this position, where chipx/y are in chip coordinates (ie 1 to 1024). If chipid=none then this value is neither prompted for nor used.

Parameter=chipy (string required default=1 min=1 max=1024)

ACIS chip y coordinate

Parameter=outfile (string not required filetype=output)

FEF file to use

This parameter is filled by the tool when it has run, and contains the name of the FEF file to use, including any spatial filter (if chipid was not set to none). See also the quality parameter, which indicates whether this file is valid.

The value can be accessed using pget/plist/pdump; for instance:

unix% set feffile = `pget acis_fef_lookup outfile`
unix% echo $feffile
.../acisD2000-01-29fef_pha_ctiN0004.fits[FUNCTION][ccd_id=5,chipx=449:512,chipy=449:512]

Parameter=quality (boolean not required default=no)

Should you use the FEF file (if no use mkacisrmf)?

There are a number of datasets for which responses should be calculated using mkacisrmf rather than mkrmf (i.e. for which this tool need not be run since mkacisrmf can use an infile of CALDB rather than a specific file, unlike mkrmf). If this is the case then the quality parameter will be set to no on output, and a warning message will be displayed to the screen if the verbose parameter is set to 1 or higher.

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

Verbose level

If set to a non-zero value then the tool will output extra information (other than the name of the FEF file) when run. This information is only likely to be useful when debugging the tool.

One exception to this is that if verbose is set to 1, or higher, then warnings will be displayed when the tool is being used on data that should be analyzed with responses calculated using mkacisrmf rather than mkrmf. The quality parameter will be set to "no" in this case.

How is the FEF Chosen?

There are separate FEF files for each focal plane temperature since the spectral response varies with chip temperature. As the CTI correction algorithm recovers much of the resolution lost due due to the radiation damage there are also separate FEF files for use with data that has and has not been CTI corrected.

Each ACIS chip is split up into a number of tiles and the response is assumed to be constant within each tile. The size of these tiles depends on the type of chip (whether it is front or back illuminated) and the focal-plane tempertature. The minimum size for a tile is 32 by 32 pixels and the largest size is 256 by 32 pixels (note that no tile crosses a node boundary).

Changes in the scripts 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

The script has been updated to run in CIAO 4.6.

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.