/ ciao4.17 / ahelp / tg_create_mask.html

Jump to: Description · Examples · Parameters · Bugs · See Also

AHELP for CIAO 4.17

tg_create_mask

Synopsis

Create a region file to define spectrum sky boundaries

Syntax

tg_create_mask infile outfile input_pos_tab grating_obs [opt_parameters]

Description

tg_create_mask infile outfile input_pos_tab grating_obs [input_psf_tab]
[detector] [radius_factor_zero] [width_factor_hetg] [width_factor_letg]
[r_astig_max_hetg] [r_astig_max_letg] [r_mask_max_hetg]
[r_mask_max_letg] [geompar] [verbose] [clobber] [use_user_pars]
[last_source_toread] [sA_id] [sA_zero_x] [sA_zero_y] [sA_zero_rad]
[sA_width_heg] [sA_width_meg] [sA_width_leg] [sB_id] [sB_zero_x] ...
[sC...] ... [sD...] ... [sE...] ... [sF...] ... [sJ_id] [sJ_zero_x]
[sJ_zero_y] [sJ_zero_rad] [sJ_width_heg] [sJ_width_meg] [sJ_width_leg]

Before wavelengths can be computed from diffracted event positions, each event is assigned to a part of the spectrum according to its spatial location. The parts are zero-order or diffracted order. If diffracted order, HETG has two diffracted parts, one for HEG and the other MEG. If LETG, there is only one diffracted part. The output of tg_create_mask is a FITS region file which enumerates the parts and specifies the region shape, size, and orientation in sky pixel-plane coordinates. If ACIS was in CC-mode, then the sky image is a line, and we call the part MEG, but use a rotation angle of zero.

The spatial region is determined via error budget calculations incorporating the affects of the mirror point spread function vs. off axis angle, defocus, and Rowland spectrograph astigmatism. The results are by default scaled to generous dimensions compared to the one-sigma characteristic size so that sub-selection can be applied later into source and background regions when binning a spectrum (see "ahelp tgextract"; the factors are parameters and subject to user control). Prior to binning, rigorous conversion of event coordinates to diffraction coordinates is done from chip coordinates and the aspect solution (see "ahelp tg_resolve_events"); sky coordinates are only used for spatial filtering.

Regions are in sky pixels, which are approximately 0.24 mm/pix or 0.49 arcsec/pix for ACIS, and 0.0064 mm/pix or 0.13 arcsec/pix for HRC (using the imaging focal length). Pixel sizes and focal lengths may be found in the CALDB "geom" file, e.g. telD1999-07-23geomN0004.fits).

Regions for up to 10 sources may be computed at a time. Regions may be determined automatically, or may be set explicitly. The roll, however, must come from the observational parameters.

In manual mode ("use_user_pars=yes"), you must set the zero order position parameters (sX_zero_x and sX_zero_y) for at least one source. If input_pos_tab is undefined, it is also necessary to specify the radius and the grating width parameters. In order to use the parameter sX_width_heg/meg/leg to set the output width, sX_zero_rad must also be set. If sX_zero_rad is not set, a warning will be displayed to tell the users that the radius and the width are computed by using input_psf_table.

For CC-mode with HETG, the mask is considered to be "MEG". This is particularly necessary if the zero order was not imaged on the array, since the sky coordinates are arbitrary and do not pass through the nominal source position. In this case, the zero order position should be set to the x,y coordinates corresponding to the source celestial location (e.g. as determined with dmcoords or ds9) and the MEG mask made large enough to reach the events' actual x,y distribution.

Examples

Example 1

tg_create_mask sample1_evt1a.fits sample1_evt1a.reg
input_pos_tab=table1_src1a.tab radius_factor_zero=75
radius_factor_arms=30

Single input and output files; change the width factors to be bigger than the defaults. The result is sample1_evt1a.reg.

Example 2

tg_create_mask @input_par.lis @outfile.lis
input_pos_tab=@input_table.lis

Use stacks of input event file header parameters and output region files. The result will be region file names listed one-per-line in the outfile.lis.

Example 3

tg_create_mask sample1_evt1a.par sample1_evt1a.reg use_user_pars=yes
last_source_toread=B sA_id=3 sA_zero_x=4832.93 sA_zero_y=6327.47
sA_zero_rad=76 sA_width_heg=47 sA_width_meg=59 sB_id=5
sB_zero_x=3218.735 sB_zero_y=5382.63 sB_zero_rad=93 sB_width_heg=62
sB_width_meg=78

Customize mask sizes for a single data set. There are two HETG sources of interest with ID 3 and 5. The result is sample1_evt1a.reg.

Parameters

name	type	ftype	def	min	max	reqd	stacks
infile	file	input				yes	yes
outfile	file	output				yes	yes
input_pos_tab	file	input					yes
grating_obs	string		header_value			yes
input_psf_tab	file	ARD	CALDB
detector	string		header_value
radius_factor_zero	real		50	1	400
width_factor_hetg	real		35	1	200
width_factor_letg	real		300	1	300
r_astig_max_hetg	real		0.56	0	2
r_astig_max_letg	real		1.10	0	4
r_mask_max_hetg	real		0.992	0	2
r_mask_max_letg	real		2.1	0	4
geompar	file		geom
verbose	integer		0	0	5
clobber	boolean		no
use_user_pars	boolean		no
last_source_toread	string		A
sX_id	integer			1	32767
sX_zero_x	real			1	65536
sX_zero_y	real			1	65536
sX_zero_rad	real			0	16384
sX_width_heg	real			0	16384
sX_width_meg	real			0	16384
sX_width_leg	real			0	16384

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=yes)

Input event file or stack.

Each input file could be an event file or the ASCII header of the event file in parameter format (see "ahelp dmmakepar"). If using a file, there must be an EVENTS extension in order to access the proper header.

A stack can contain a list of event files or event header parameter files. For each file in the infile stack, there should be a file specified in the input_pos_tab stack and a file specified in the outfile stack. If the number of files listed in the input stack is different from that of the input_pos_tab stack or the outfile stack, the tool will report an error.

If using the user specific mask characteristics (see the use_user_pars parameter), you can only have one input header file and one output file, stack lists are not permitted.

Parameter=outfile (file required filetype=output stacks=yes)

Output region file or stack of region files.

If the input to outfile is a stack, for each file in the outfile stack, there should be a file specified in the infile stack and a file specified in the input_pos_tab stack. If the number of files listed in the outfile stack is different from that of the infile stack or the input_pos_tab stack, the tool will report an error.

If using the user specific mask characteristics, you can only have one output region file name, stack lists are not permitted.

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

Input FITS source table (e.g., src1a.fits) with zero order positions (see "ahelp tgdetect").

This file/stack is only required if use_user_pars="no".

For stack input, the number of files listed in the input_pos_tab stack has to be equal to that of the infile stack and the outfile stack, otherwise, the tool will report an error.

If using the user specific mask characteristics, stack lists are not permitted.

Parameter=grating_obs (string required default=header_value)

Observed grating type: [HETG|HEG|MEG|LETG|header_value]

If the the value is "header_value", then the value of the header keyword GRATING from the input header file is used.

NOTE: ACIS CC HETG mode data is processed using the grating_type="MEG"; since there is no spatial resolution across the dispersion, both parts are merged. They are resolved later by tg_resolve_events, if possible.

NOTE: Extended sources may require the use of HEG and MEG independently to create wide masks. Wide masks with type HETG will produce masks with very overlapping regions near zero order (or not so near), and event resolution will fail in the overlap in tg_resolve_events.

Parameter=input_psf_tab (file filetype=ARD default=CALDB)

Calibration file with a table of mirror point-spread-function characteristic width (FWHM) vs. off axis angle.

Required if use_user_pars="no", or when the use_user_pars="yes" but the radius of the zero order source(s) and the width of the HEG, MEG, or LEG grating mask are not set.

Users can specify "CALDB" to automatically look up the file appropriate for the observation date.

Parameter=detector (string default=header_value)

Detector: [ACIS|HRC-I|HRC-S|header_value]

Detector type used in the observation: ACIS | HRC-I | HRC-S. The string "header_value" can be used; this allows the tool to use the value of the DETNAME header keyword from the input header file. This is used for overall region extent and pixel scale determinations.

Parameter=radius_factor_zero (real default=50 min=1 max=400)

A scale factor which multiplies the approximate calculation of the one sigma zero order radius. The default provides a large zero order region. Extended sources may require greater values.

The resulting radii in sky pixels are 119 (LETG/HRC-S), 28 (HETG/ACIS-S), and 31 (LETG/ACIS-S). These scale approximately linearly with the radius_factor_zero (with zero intercept). (Pixel sizes and imaging focal lengths may be found in the CALDB "geom" file, e.g. telD1999-07-23geomN0004.fits).

Parameter=width_factor_hetg (real default=35 min=1 max=200)

A scale factor which multiplies the approximate one sigma width of the HEG/MEG mask in the cross-dispersion direction. The default is large enough to accommodate source and background regions when binning, but not so large that HEG and MEG overlap too much at short wavelengths (Fe K region is not compromised).

The default produces box widths of 73 and 98 sky pixels for HEG and MEG, respectively. A value of 5 results in HEG and MEG region widths of 13 and 17 pixels, respectively. The relation is linear (pixel sizes and imaging focal lengths may be found in the CALDB "geom" file, e.g. telD1999-07-23geomN0004.fits).

Parameter=width_factor_letg (real default=300 min=1 max=300)

A scale factor which multiplies the approximate one sigma width of the LETG mask in the cross-dispersion direction. The default is large enough to accommodate source and background regions when binning.

The default produces a box width of 11310 sky pixels for HRC-S, and 2940 for ACIS-S; essentially covering the full detectors. For a width factor of 5, the respective widths are 208 and 54. (Pixel sizes and imaging focal lengths may be found in the CALDB "geom" file, e.g. telD1999-07-23geomN0004.fits).

Parameter=r_astig_max_hetg (real default=0.56 min=0 max=2)

Maximum grating diffraction coordinate (tg_r) for HETG astigmatism calculation, which is a factor in the cross-dispersion region width. The default is for on-axis pointings. This need not be changed, except for sources far off-axis (> 3 arcmin), when the spectrum can extend to greater than the default 0.5 degrees.

Parameter=r_astig_max_letg (real default=1.10 min=0 max=4)

Maximum grating diffraction coordinate (tg_r) for LETG astigmatism calculation, which is a factor in the cross-dispersion region width. The default is for on-axis pointings. This need not be changed, except for sources far off-axis (> 3 arcmin), when the spectrum can extend to greater than the default 1.0 degrees.

Parameter=r_mask_max_hetg (real default=0.992 min=0 max=2)

Maximum grating diffraction coordinate (tg_r) for HETG mask, to support offset pointing and detector-edge truncation of the spectrum. (There is seldom reason to adjust this parameter.)

Parameter=r_mask_max_letg (real default=2.1 min=0 max=4)

Maximum grating diffraction coordinate (tg_r) for HETG mask, to support offset pointing and detector-edge truncation of the spectrum. (There is seldom reason to adjust this parameter.)

Parameter=geompar (file default=geom)

The name of the Pixlib Geometry parameter file.

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

Verbosity level for diagnostic output: 0 - minimum output to 5, maximum.

Parameter=clobber (boolean default=no)

Over-write existing outfile if "yes". Otherwise, terminate with an error if the named output file exists.

Parameter=use_user_pars (boolean default=no)

Must be set to "yes" if manual source position(s) are supplied in the zero order position parameters (sX_zero_x and sX_zero_y). If input_pos_tab is undefined, then it is also necessary to define the radius of the zero order source(s) and the width of the HEG, MEG, or LEG grating mask.

Parameter=last_source_toread (string default=A)

Last source name to be read. [char A|B|C|D|E|F|G|H|I|J]

A mask may specify up to 10 different sources. Manual mode requires the count to be given, via the index by letter A-J. (The "X" in the following 7 parameters is to be replaced by the letter index, and up to 10 blocks may be set.)

Parameter=sX_id (integer min=1 max=32767)

Source X - source number. The number corresponds to the index in the source table (see "ahelp tgdetect"). It may be greater than 10 (but no more than 10 different entries may be set at one time).

Parameter=sX_zero_x (real min=1 max=65536)

Source X - x position of zero-order centroid in sky x pixels.

Parameter=sX_zero_y (real min=1 max=65536)

Source X - y position of zero-order centroid in sky y pixels.

Parameter=sX_zero_rad (real min=0 max=16384)

Source X - radius of zero order region in sky pixels.

Parameter=sX_width_heg (real min=0 max=16384)

Source X - width (cross-dispersion direction) of HEG mask in sky pixels.

In order to use this parameter to set the output width, sX_zero_rad must also be set. If sX_zero_rad is not set, a warning will be displayed to tell the users that the radius and the width are computed by using input_psf_table.

Parameter=sX_width_meg (real min=0 max=16384)

Source X - width (cross-dispersion direction) of MEG mask in sky pixels in sky pixels.

Parameter=sX_width_leg (real min=0 max=16384)

Source X - width of leg mask (cross-dispersion direction) in sky pixels in sky pixels.

Bugs

There are no known bugs for this tool.