|
|
|
|
|
SynopsisCreate a region file to define spectrum sky boundaries Syntaxtg_create_mask infile outfile input_pos_tab grating_obs [opt_parameters] Descriptiontg_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 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 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. 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. Example 1tg_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 2tg_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 3tg_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
Detailed Parameter DescriptionsParameter=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 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 parameter use_user_pars), 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 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=40 min=1 max=200)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 1508 sky pixels for HRC-S, and 392 for ACIS-S. 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 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. 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. CHANGES IN CIAO 3.0Default HEG and MEG region width scaling factors were adjusted to be consistent with 'tgextract'. Prior to CIAO 3, the event cross-dispersion range provided by the region was slightly less than the background binning region, so the BACKSCAL values were in error by about 20%. The revised values also better accommodate HEG and MEG overlap at short wavelengths, and provide good extractions somewhat short-ward in wavelength of Fe K. BugsSee the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs. See Also
|
 |
The Chandra X-Ray
Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA. Email: cxcweb@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2004. All rights reserved. |
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}