
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
