NAME ---- tg_create_mask -- Calculates the mask regions of the grating arms for AXAF flight L1 grating data files. The output is a region file in sky coordinates. USAGE ----- tg_create_mask infile outfile [input_pos_tab] [input_psf_tab] [grating_par] [grating_obs] [detector] [radius_factor_zero] [width_factor_arms] [r_astig_max_hetg] [r_astig_max_letg] [r_mask_max_hetg] [r_mask_max_letg] [debug] [use_user_pars] [max_source_num] [s1_zero_x] [s1_zero_y] [s1_zero_rad] [s1_width_heg] [s1_width_meg] [s1_width_leg] [s2_zero_x] ... [s2...] ... [s5...] ... [s7...] ... [s8...] ... [s10_zero_x] [s10_zero_y] [s10_zero_rad] [s10_width_heg] [s10_width_meg] [s10_width_leg] DESCRIPTION ----------- This program can be run in a variety of ways. The three main options are: (1) Run on a single input event file to get a single output resultant region file. This method does not use user specified mask sizes and calculates the grating mask from calibration data and error-budget approximations. A zero order source position table is also reguired as input (for details on table, see below); as well as a calibration data file which has the fwhm of an AXAF source versus to off-axis angle. There is a default table pointer used by the tool, but it can be reset by the user. (2) Run on a stack of input event files to get a stack of resultant region files. This method is the same as the the above, with the exception of working on multiple input/output files. (3) Run only on a SINGLE input event file and specify the regions explicitly (this method does not run on stacks). The difference from methods (1) and (2) above is that the the mask sizes are completely user specific. This means that the region mask sizes are not calculated using the calibration table; instead, the user parameters are used as input to the mask sizes. The tool does simple calculations of mask lengths to make sure they fit on the detector space, as well as write the resultant region file in the correct format for the next tool to use as input. Noting the above methods of running the program, the user must decide whether they want the mask regions to be calculated by the tool or whether they want to set the information themselves. Read the appropriate section below of how to run the tool. Automatic Calculations ---------------------- Required inputs are an event file parameter file/stack, source position table/stack. The tool uses the source positions in your table and calculates all the mask characteristics using the defocus, astigmatism, off axis angle, the telescope roll and it's tolerance, along with calibration grating data characteristics. The calculations of the mask involve: The routine tg_calc_zero_mask() is called by tg_create_mask() to calculation the zero order masks in r/d coordinates. Zero order radius is calculated using the defocus and interpolated fwhm of the data. A scaling width factor (which is set by the user) is used to increase the zero order calculated radius value. The equation is: d_defocus=(2*gratng_ring_radius/flight_rowland_diam^2)*(|defocus|) F_BOX=2*sqrt(3) F_GAUSS=2*sqrt(2*log(2)) radius=(sqrt( (interpolated_fwhm/F_GAUSS)^2 + (d_defocus/F_BOX)^2) ) * width_factor_zero_order The routine tg_calc_arm_mask() is called by tg_create_mask() to calculation grating arm mask in r/d coordinates. Arm mask width are calculated using the defocus, interpolated fwhm, max r and roll tolerance. A scaling width factor (which is set by the user) is used to increase the arm mask calculated width value. The equation is: d_astig_defocus=(2*grating_ring_radius/grtptr->rowland) *(r_max^2) + |(defocus/flight_rowland_diam)| d_roll=roll_tollerance*r_max F_BOX=2*sqrt(3) F_GAUSS=2*sqrt(2*log(2)) width = 2*sigma*width_factor + roll' width=2*(sqrt( (interpolated_fwhm/F_GAUSS)^2) + ((d_astig_defocus/F_BOX)^2) )*(width_factor_arms) + d_roll Once mask widths are calculated, mask lengths are also calculated using grating characteristics. Both the mask lengths and widths are then converted to sky coordinates and written to the region description file/stacks. Explicit specification of the Mask ---------------------------------- Required inputs are an event file parameter file/stack. The user must set the following mask parameters in order for the tool to work properly: # -------------------------------------------------------------------------- # The parameters below are to be set ONLY if the user wants to use their # own grating mask sizes instead of having the masks automatically generated. # Only ONE input file, with up to 10 soures, can be processed using the user # params. @ lists of multiple files can only be done with automated mask, # or by running each file individually with hand set mask sizes. To start, # you MUST set the following parameters: # # > pset tg_create_mask use_user_pars=yes max_source_num=# # # The parameter max_source_num should be set to the largest source ID number # for which you will enter parameters. If you have 2 sources with src_id's # of 2 and 6, respectively, the max_source_num=6, in this case. Each user # parameter name below is preceded with a source number, fill out only # those parameters which correspond to your src_id's. # Each source must have a zero order center position specified as well as # the grating mask width(s). An example with 1 HETG sources, with src_id=3: # # > pset tg_create_mask s3_zero_x=4762.34 s3_zero_y=2344.29 s3_zero_rad=35 # > pset tg_create_mask s3_width_heg=25 s3_width_meg=28 # (units are all in sky pixels) # -------------------------------------------------------------------------- You must set all the grating specific mask parameters for each of the sources you are working with. Each source has the following possible group of params to be set: s1_zero_x,r,h,,,,"Source 1 - x position of zero order" s1_zero_y,r,h,,,,"Source 1 - y position of zero order" s1_zero_rad,i,h,,,,"Source 1 - radius of zero order mask" s1_width_heg,i,h,,,,"Source 1 - width of heg mask in sky pixels" s1_width_meg,i,h,,,,"Source 1 - width of meg mask in sky pixels" s1_width_leg,i,h,,,,"Source 1 - width of leg mask in sky pixels" The zero order x,y,rad MUST be set (even if the zero order is not imaged on the detector). Setting the grating width depends on which grating you are using. If you have the HETG, then set the width_heg AND width_meg params, if you have the LETG, then set the width_leg. These groups of params should be set for each of the sources in your field of view of your qpoe file. Once mask widths are set and the tool is run, mask lengths calculated using grating characteristics. These mask lengths are then converted to sky coordinates and written to the region description file/stacks. The rest of the mask characteristics are used from the parameter file settings of the mask placement. PARAMETERS ---------- The parameters for this tool are complicated if the user is specifying all the mask characteristics on their own. However, the parameter setting get far more simple of the user does not specify the mask directly and lets the tool do all the calculations. I will try to distinguish on method from the other, in the parameter descriptions. infile = [filename | @input_par.lis] Input @par.lis of header params or one infile_evt1a.par file. If using the user specific mask characteristics, you can only have one input event par input file, stack lists are not permitted. An event file parameter file can be created using the task dmmakepar; this task takes an event file header and writes it to an ascii parameter file. Sample input event parameter stack list file: > cat input_par.lis sample1_evt1a.par sample2_evt1a.par sample3_evt1a.par outfile = [filename | @outfile.lis] Output @region.lis of region file names or one outfile_evt1a.reg file name. If using the user specific mask characteristics, you can only have one output region file name, stack lists are not permitted. Sample output region stack list file: > cat outfileion.lis sample1_evt1a.reg sample2_evt1a.reg sample3_evt1a.reg input_pos_tab = [filename | @input_table.lis] Input @table.lis of zero order positions tables or one table_src1a.fits file. This file/stack is only required if the user is NOT specifying the mask sizes on their own. NOTE: The position table currently stores extra information needed for mask calculations, which will later be integrated into the tool as calculations. So, there will be some fields in the table which will not need to be there in the future. The table must be in fits format; this format is the output of the tool tgsrcmatch and tgsrctable (source detection output along with source id information). For each source, there must be a row of information containing: ra --- the RA of the source (not currently used, can be fake) dec --- the Declination of the source (same as above) x --- the x sky pixel position of the zero order center y --- the y sky pixel position of the zero order center offaxis --- the off axis angle of that zero order center position (arc min) srcid --- unique source id you want to assign to each source (available numbers range from 1-10) IMPORTANT:: The table extension name must be: "GZO_POS" Sample table: > fdump Marx_HETG_ACIS-S_Espec_0000_2_src1a.fits Name of optional output file[STDOUT] Names of columns[] Lists of rows[-] SIMPLE = T / file does conform to FITS standard BITPIX = 16 / number of bits per data pixel NAXIS = 0 / number of data axes EXTEND = T / FITS dataset may contain extensions COMMENT FITS (Flexible Image Transport System) format defined in Astronomy and COMMENT Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365. COMMENT Contact the NASA Science Office of Standards and Technology for the COMMENT FITS Definition document #100 and other FITS information. END XTENSION= 'BINTABLE' / binary table extension BITPIX = 8 / 8-bit bytes NAXIS = 2 / 2-dimensional binary table NAXIS1 = 22 / width of table in bytes NAXIS2 = 2 / number of rows in table PCOUNT = 0 / size of special data area GCOUNT = 1 / one data group (required keyword) TFIELDS = 6 / number of fields in each row TTYPE1 = 'ra ' / label for field 1 TFORM1 = 'E ' / data format of field: 4-byte REAL TTYPE2 = 'dec ' / label for field 2 TFORM2 = 'E ' / data format of field: 4-byte REAL TTYPE3 = 'x ' / label for field 3 TFORM3 = 'E ' / data format of field: 4-byte REAL TUNIT3 = 'pixels ' / physical unit of field TTYPE4 = 'y ' / label for field 4 TFORM4 = 'E ' / data format of field: 4-byte REAL TUNIT4 = 'pixels ' / physical unit of field TTYPE5 = 'offaxis ' / label for field 5 TFORM5 = 'E ' / data format of field: 4-byte REAL TUNIT5 = 'arm_min ' / physical unit of field TTYPE6 = 'srcid ' / label for field 6 TFORM6 = 'I ' / data format of field: 2-byte INTEGER EXTNAME = 'GZO_POS ' / name of this binary table extension HISTORY This FITS file was created by the FCREATE task. HISTORY fcreate3.0d at 23/4/98 11:13:1. END ra dec x y pixels pixels 1 3.4511191E+02 5.8428200E+01 4.0965400E+03 6.0589600E+03 2 3.4476660E+02 5.8615002E+01 3.8515400E+03 6.3040000E+03 offaxis srcid arm_min 1 0.0000000E+00 1 2 2.5000000E+00 3 (input_psf_tab = $ASCDS_CALIB/psf_fwhm.fits) [filename ] Calibration .fits file with approximate mirror psf size vs off-axis angle. Only required if no user mask parameters are specified. The current default can be reset to any other table with the same general information - the table type must be same. The $ASCDS_CALIB area contains the default psf_fwhm.fits table. IMPORTANT:: The table extension must be: "PSF_FWHM" Sample table: > fdump psf_fwhm.fits Name of optional output file[STDOUT] Names of columns[] Lists of rows[-] SIMPLE = T / file does conform to FITS standard BITPIX = 16 / number of bits per data pixel NAXIS = 0 / number of data axes EXTEND = T / FITS dataset may contain extensions COMMENT FITS (Flexible Image Transport System) format defined in Astronomy and COMMENT Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365. COMMENT Contact the NASA Science Office of Standards and Technology for the COMMENT FITS Definition document #100 and other FITS information. ENDSIMPLE = T / file does conform to FITS standard BITPIX = 16 / number of bits per data pixel NAXIS = 0 / number of data axes EXTEND = T / FITS dataset may contain extensions COMMENT FITS (Flexible Image Transport System) format defined in Astronomy and COMMENT Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365. COMMENT Contact the NASA Science Office of Standards and Technology for the COMMENT FITS Definition document #100 and other FITS information. END XTENSION= 'BINTABLE' /Binary table written by MWRFITS BITPIX = 8 /Required value NAXIS = 2 /Required value NAXIS1 = 8 /Number of bytes per row NAXIS2 = 13 /Number of rows PCOUNT = 0 /Normally 0 (no varying arrays) GCOUNT = 1 /Required value TFIELDS = 2 /Number of columns in table COMMENT COMMENT *** Column formats *** COMMENT TFORM1 = 'E ' / TFORM2 = 'E ' / COMMENT COMMENT *** End of required fields *** COMMENT EXTNAME = 'PSF_FWHM' /FWHM of zero-order PSF COMMENT +------------------+ COMMENT | AXAF FITS File | COMMENT +------------------+ COMMENT ********************************************************* COMMENT > This file is written following certain AXAF-ASC < COMMENT > conventions which are documented in ASC-FITS-1.1 < COMMENT ********************************************************* COMMENT / Configuration control-------------------------- ORIGIN = 'ASC ' CREATOR = 'xxx - Version 0.0' REVISION= 0 / Processing system revision number COMMENT $Id: ascfits.tex,v 1.4 1998/05/12 14:50:42 arots Exp arots $ CHECKSUM= '0000000000000000' / ASCII encoded HDU checksum DATASUM = ' 0' / Data unit checksum written in ASCII CONTENT = 'FWHM ' /FWHM of zero-order PSF HDUNAME = 'FWHM ' /Zero-order PSF FWHM HDUSPEC = 'ARD Exposure Maps, Inst.Maps, TG L1.5-2 ICD' / ICD reference HDUDOC = 'ASC-FITS-1.1: McDowell, Rots: ASC FITS File Designers Guide' HDUVERS = '1.0.0 ' HDUCLASS= 'ASC ' HDUCLAS1= 'PSF ' / HDUCLAS2= 'FWHM ' / LONGSTRN= 'OGIP 1.0' / The OGIP long string convention may be used. COMMENT This FITS file may contain long string keyword values that are COMMENT continued over multiple keywords. This convention uses the '&' COMMENT character at the end of a string which is then continued COMMENT on subsequent keywords whose name = 'CONTINUE'. HISTORY Input event file: hrcx123456789N000_evt0.fits DATE = '1998-0803T00:00:39' / Date and time of file creation (UTC) MISSION = 'AXAF ' / Mission is AXAF INSTRUME= 'HRMA ' / HRC, ACIS, EPHIN, S/C subsystems DETNAM = ' ' / Detector name GRATING = 'NONE ' / Grating DATACLAS= 'SIMULATED' / If fake data, / include this (default is DATACLAS='OBSERVED') COMMENT COMMENT *** Column Names *** COMMENT TTYPE1 = 'OFFAXIS ' / TTYPE2 = 'FWHM ' / TUNIT1 = 'arcmin ' / TUNIT2 = 'arcsec ' / TLMIN1 = 0.00000 / TLMIN2 = 0.00000 / TLMAX1 = 60.0000 / HISTORY Testing dph 980622; first bintable extension; principal hdu END OFFAXIS FWHM arcmin arcsec 1 0.0000000E+00 7.1070480E-01 2 8.3300002E-02 7.2481644E-01 3 1.6670001E-01 7.7298743E-01 4 3.3329999E-01 8.4168440E-01 5 5.0000000E-01 7.2425443E-01 6 1.0000000E+00 8.5217273E-01 7 2.0000000E+00 8.2401264E-01 8 5.0000000E+00 2.7854469E+00 9 1.0000000E+01 1.0696798E+01 10 1.5000000E+01 1.7453949E+01 11 2.0000000E+01 3.1037743E+01 12 2.5000000E+01 3.8922913E+01 13 3.0000000E+01 4.7982021E+01 (grating_par = grating) [filename.par] Name of grating constants parameter file. The default is grating.par (grating_obs = ) [HETG|HEG|MEG|LETG] Observed grating type: HETG or HEG or MEG or LETG. The Drake Flat is currently not available. (detector = ) [ACIS|HRC-I|HRC-S] Detector type used in the observation: ACIS | HRC-I | HRC-S . (radius_factor_zero = 10) [integer] A scale factor which multiplies the approximate calculation of the one-sigma zero order radius. (width_factor_arms = 10) [integer] A scale factor which multiplies the approximate one-sigma width of the region in the cross-dispersion direction (r_astig_max_hetg = 0.56) [float] Max grating r coord (deg, along the dispersion) for HETG astigmatism calculation. (r_astig_max_letg = 1.10) [float] Max grating r coord (deg, along the dispersion) for LETG astigmatism calculation. (r_mask_max_hetg = 0.992) [float] Max grating r coordinate (deg) for HETG mask (to support offset pointing). (r_mask_max_letg = 2.1) [float] Max grating r coordinate (deg) for LETG mask (to support offset pointing). (display = 0) [integer (0:5)] Display level: 0 - no output, 5 - max display. THE FOLLOWING PARAMETERS ARE ONLY TO BE SET IF THE USER WANTS TO SPECIFY THE MASK SIZES EXPLICITLY. YOU MUST SET THE APPROPRIATE SOURCE ID PARAMETERS WHICH CORRESPOND TO THE SOURCES YOU WANT TO PROCESS. (use_user_pars = no) [bool] Use the mask parameters below: yes or no? (max_source_num = 1) [integer (1:10)] Maximum source id number for which to read params. NOTE: This is NOT the total number of sources! # ----------------------------------------------------------------- # Source ID # parameters x 10 # ----------------------------------------------------------------- (s#_zero_x = ) [float] Source # - x position of zero order in sky x pixels. (s#_zero_y = ) [float] Source # - y position of zero order in sky y pixels. (s#_zero_rad = ) [float] Source # - radius of zero order mask in sky pixels. (s#_width_heg = ) [float] Source # - width of heg mask in sky pixels in sky pixels. (s#_width_meg = ) [float] Source # - width of meg mask in sky pixels in sky pixels. (s#_width_leg = ) [float] Source # - width of leg mask in sky pixels in sky pixels. (mode = "ql") [string] Parameter interface mode. "ql" stands for "query and learn" which prompts you for input and updates "tg_create_mask.par" with your responses. EXAMPLE ------- Three examples will be listed, one for each of the different methods of using the tool. (1) Single input and output files; changing the width factors to be bigger than the defaults. % tg_create_mask infile=sample1_evt1a.par outfile=sample1_evt1a.reg input_pos_tab=table1_src1a.tab grating_obs=HETG detector=ACIS radius_factor_zero=20 radius_factor_arms=30 The result should be a region sample1_evt1a.reg with the mask size information. (2) Stacks of input event file parameters and output region files. % tg_create_mask infile=@input_par.lis outfile=@outfile.lis input_pos_tab=@input_table.lis grating_obs=LETG detector=HRC The result should be region files which were listed in the outfile.lis; with the mask size information. % cat outfile.lis sample1_evt1a.reg sample2_evt1a.reg sample3_evt1a.reg (3) User specific mask sizes for a single data set. There are 2 HETG sources of interest with ID 3 and 5. % tg_create_mask infile=sample1_evt1a.par outfile=sample1_evt1a.reg grating_obs=HETG detector=ACIS use_user_pars=yes max_source_num=5 s3_zero_x=4832.93 s3_zero_y=6327.47 s3_zero_rad=76 s3_width_heg=47 s3_width_meg=59 s5_zero_x=3218.735 s5_zero_y=5382.63 s5_zero_rad=93 s5_width_heg=62 s5_width_meg=78 The result should be a region sample1_evt1a.reg with the mask size information. A sample output file is: #.GRATING hetg #.SOURCE 1 #.COMPONENT 0 # TG_PART = 0 = gzo physical; circle 4097.54 4097.50 26 #.COMPONENT 1 # TG_PART = 1 = heg physical; rotbox 4097 4097 8182 41 5.18d #.COMPONENT 2 # TG_PART = 2 = meg physical; rotbox 4097 4097 8182 56 -4.75d The region file format places grating specific information as comments in the region file. The "#." signifies special grating comments which describe the grating (#.GRATING), source id (#.SOURCE) and grating part (#.COMPONENT). The grating describes the grating name for the entire region file; the source number is for the next lines of grating regions and is assumed to be the same until another source id is listed; the component preceeds each grating region. DATE ---- 01/11/98 04/23/98 06/15/98 09/16/98