NAME

    tgextract -- Extract grating 1D spectrum(a) from an event file.   

USAGE

    tgextract [infile] [regionfile] [outfile_type] [outfile] 
    [tg_srcid_list]  [tg_part_list] [tg_order_list] [ancrfile] 
    [respfile] [backfile=] [rowid=] [grating_par=] [bin_units=]
    [min_bin=] [max_bin=] [bin_size=] [num_bins=] [tg_d_units=] 
    [min_tg_d=] [max_tg_d=] [extract_background=] [min_bkg_tg_d=]
    [max_bkg_tg_d=] [clobber=] [display=] 

DESCRIPTION

   Bin Level 1.5 events into counts histograms, one per each
   source, grating part, and order, as specified by input
   parameters.  Calculate an uncertainty array for each
   spectrum. Optionally bin a background region, and also
   calculate its uncertainty array.  Output an AXAF FITS
   Type II PHA spectrum file, or one or more Type I PHA
   files.  From the binning parameters, create and write
   region extensions for both the source and background
   regions.

   Detailed Description:

   This tool should serve both the pipeline and interactive needs. 

   For pipeline usage, certain parameter defaults will be imposed; 
   for which some external calculations may be needed to specify
   the parameters.

   Primary function is to bin the event list into one or more
   1-dimensional spectra. 

   Each spectrum is for a given set of photon  attributes: 

        - source (if there are more than one in the file), 
        - part of the spectrum (such as HEG, MEG, LEG, or Drake 4-7), and 
        - diffraction orders (if ACIS is the detector).

   The preferred output is a Type II PHA file, in which there is a row
   for each attribute set, and the spectrum is an array column.  For
   simplicity, each array quantity (the spectra) stored in a column
   will have the same width (i.e., number of bins per spectrum).  This
   means that the grids are different for different orders, and also,
   may be truncated differently for different source positions.  No
   checking will be done in the pipeline to avoid truncation of
   off-axis sources.  User interactive processing will be required to
   recover those parts of the spectra from the Level 1.5 event list).

   TBR:  Alternatively, a Type I PHA file may be written, in which each
         attribute set specifies a separate file, since the Type I
         specification only allows a single spectrum (plus associated
         uncertainty and grid arrays).

   The cross-dispersion region is specified by limits constant with
   wavelength (a rectangle), 
   TBR: or via a table.  (A table input will allow variable
        width with energy and order, and the advantage is for keeping
        approximately a constant effective area for each bin (table
        creation is TBD). )
   Limits must be consistent with the pre-filtering mask applied in
   Level 1.5 processing (i.e., there won't be any photons with tg_d
   greater than some pre-specified amount).

   Background regions can be specified parallel to the spectrum or
   (TBD: ) via a table.  For pipeline use, the backgrounds
   will be symmetric and have top-bottom regions combined (i.e., same
   absolute valued region in the cross-dispersion direction, and
   binned together, such as -1.0 to -0.1 mm in tg_d, and 0.1 to 1.0,
   binned into one background spectrum instead of two).

   Each extract region is specified as a FITS Region table in the
   REGION extension of the output pha file.  In the case where the
   background is extract, there are a total of three region sections
   per spectrum: the spectrum region (SOURCE), the background region
   above the spectrum (BAKCGROUND_UP) and the background below the
   spectrum region (BACKGROUND_DOWN).

PARAMETERS

    infile [filename]  (root_evt1a.fits)

        Input event file (output file from L1.5 data processing).

    regionfile [filename]  (root_reg1a.fits | none)

        Input FITS region file associacted with event list.  This file
        is also created in L1.5, one for each event list.  This file 
        is used for the purpose of getting source id information,
        in case the tg_srcid_list parameter is set to 'all'.  The
        list of source id's is referenced from the region file in
        order to find out what 'all' sources are present.  If 'all'
        is not used, then the region file does not need to be input.
        In later stages of the tool, the region should be an
        extension of the infile events.  The file format can be
        found in the FITS REGION ASC document.  Sample data:

        SHAPE            X               Y               R
                         pixel           pixel           pixel
      1 circle             3.9763999E+03   4.1686001E+03   2.6000000E+01
                           0.0000000E+00   0.0000000E+00   0.0000000E+00
      2 rotbox             4.0950000E+03   4.1790000E+03   8.1820000E+03
                           0.0000000E+00   0.0000000E+00   4.1000000E+01
      3 rotbox             4.0950000E+03   4.1580000E+03   8.1820000E+03
                           0.0000000E+00   0.0000000E+00   5.6000000E+01
      4 circle             4.0403999E+03   4.7446001E+03   4.3000000E+01
                           0.0000000E+00   0.0000000E+00   0.0000000E+00

 
        ROTANG          COMPONENT SOURCE GRATING
        deg
      1   0.0000000E+00      1         1 hetg
          0.0000000E+00
      2   5.1799998E+00      2         1 hetg
          0.0000000E+00
      3  -4.7500000E+00      3         1 hetg
          0.0000000E+00
      4   0.0000000E+00      1         3 hetg
          0.0000000E+00

    outfile_type [pha2]  (pha1|pha2)

        Ouput file type: pha1 (single spectrum of OGIP TYPE I) or pha2
        (multiple spectra of OGIP Type II).

    outfile [filename or . or root]  (root_pha2.fits or root or '.')

        Output file name.  If outfile_type=pha2, the user can enter the
        full output file name or '.'.  If the '.' is used, the input file
        name is used to create the output file;  if infile = 
        root_extension.fits, then outfile will be root_pha2.fits.
        If outfile_type=pha1, the user can enter the rootname of the
        output file or '.'.  If root name is used, the output file will
        be named as:  root_<srcid><part><order>_pha2.fits;  if '.'
        is used, the input file name is used to create the output file:
        if infile = root_extension.fits, then outfile will be 
        root_<srcid><part><order>_pha2.fits.
 
    tg_srcid_list [string]  (all|string|@filename)

        The list of source orders to process.  
        "all" will process all the sources id's found in the event region
        file.  A comma separated string list can be used instead of the
        region file:   "1,2,5,7".  Another option is to use an @file which
        contains a comma separated list or source id's to process.

    tg_part_list [string]  (HETG|HEG|MEG|LETG|HESF|header_value)

        Grating parts to process: HETG, HEG, MEG, LETG, HESF,
        header_value.  'header_value' will take the input event file
        header value of the keyword GRATING.
 
    tg_order_list [string]  (default|comma list|range list|@file)

        Grating diffraction orders to process: 'default', comma list,
        range list, 'all', @file.
         - "default" is set to process the following:
           if ACIS:  1, 2, 3, -1, -2, -3
           if HRC:   -1, 1
         - a comma list is a comma separated string list of the orders
           the user wants to process, ie:
           "-5, -1, 1, 3"
         - a range list sets the min and max of the orders to process;
           all the orders in between, will be processed, ie:
           "-1..5"  will do orders from -1 to +5th order (excluding 0)
           a range list can be mixed with comma separated list
         - @file is a pointer to an ascii file which contains a comma
           separated list and/or range list of the orders to process

    ancrfile [filename]  (filename or 'none')

        Input ancillary response file name.  The filename or the word
        'none' gets written to output file in the ANCRFILE column.
        
    respfile [filename]  (filename or 'none')

        Input redistribution file name.  The filename or the word
        'none' gets written to output file in the RESPFILE column.
        
    (backfile = "") [filename]

        If BACKFILE column is to be filled in, enter name here; 
        otherwise, the column is not present in the output file.

    (rowid = "") [string of length 64]

        If ROWID column is to be filled in, enter name here;
        otherwise, the column is not present in the output file.

    (grating_par = grating) [param name]

        Name of the grating parameter file with grating characteristics.

    (bin_units = Angstrom) [Angstrom|eV|KeV|deg|pix|mm]

        Bin units (for bin parameters below): Angstrom, KeV, eV, deg, 
        pix, mm.  Specifies the units of min_bin, max_bin, bin_size and
        of the output histogram.

        If units are Energy, then the tg_lam values in the event file must
        be converted to energy via E = hc/lambda, where hc=12398.54 
        (hc=12.3985 for KeV) for lambda in Angstroms and E in eV.

        If other bin parameters are left to defaults (Angstroms), and
        bin_units is not Angstrom, then binning parameters are converted
        to the specified unit and events are binned accordingly.

    NOTE: Binning Parameters
    ------------------------
    If the grating type is HETG, the binning parameters should be
    given for MEG +1 order binning.  The bin characteristics
    will be updated for all other orders and grating parts, using
    the the following calculations:

            m * lambda = P * sin(theta)

        order * wavelength = period * sin(diffraction angle)

     Diffraction angle == tg_r is small, so sin(theta) ~ theta, so

            m * lambda = P * tg_r

     Calculating a bin size is done by taking the derivative:

            m * delta_lambda = P * delta_tg_r

            or equivalently

            delta_lambda  = (P/m) * delta_tg_r.

     If bins are specified for first order MEG and, the rest are
     scaled to:
                (Period_part/Period_MEG) / order

     If the grating is LETG (and detector is ACIS), the user can 
     specify the binning for LETG +1, and the rest of the binning 
     will be scaled by order only, as apposed to using the Period
     ratio's above.

    (min_bin = compute) ['compute'|real number]

        Minimum dispersion coordinate on which to start the binning.
        A real valued number can be specified in any other diffraction
        coordinate: max energy [keV], tg_r [deg], gdp [pix], or linear
        [mm].  The default is:  1.239854 Angstrom (10.0 keV).

        It is assumed that the bin coordinate refers to the left edge 
        of the bin, and the bin value is incremented if the data value
        is GE the bin coordinate, and LT the bin coordinate plus the
        bin_size.

        Min_bin could be overspecified: 
           min_bin = max_bin - num_bins * bin_size
           A value of 'compute' means calculate using a combination of
           the bin values entered and the default values. 

    (max_bin = compute) ['compute'|real number]

        Maximum dispersion coordinate on which to stop the binning.
        A real valued number can specified in any other diffraction
        coordinate: max energy [keV], tg_r [deg], gdp [pix], or linear
        [mm]. 

        Default: Determined by grating type and part:
           HETGS/HEG: 20 A
	   HETGS/MEG: 40 A
	   LETGS:    170 A
           LETG/ACIS-S: 100 A
           HETG/HEG/HRC-S:  30 A
           HETG/MEG/HRC-S:  60 A
           
        It is assumed that the max_bin coordinate refers
        to the right edge of the bin, and the bin value is incremented if
        the data value is GE the left edge (the bin coordinate) and LT
        the left edge plust the bin_size (right edge). 

        Max_bin could be overspecified:
           max_bin = min_bin + num_bins * bin_size
           A value of 'compute' means calculate using a combination of
           the bin values entered and the default values. 

    (bin_size = compute) ['compute'|real number]

        This is the size of the bins for storing the counts
        histogram.  It is assumed that all bins are the same size, and
        that the bin coordinate refers to the left edge of the bin.

        Default:  Determined by grating type, part, and order, for
                  0.012 mm linear scale (one-half spatial resolution).

                Wavelength bin is equal to:
                     TG_Period * linear_scale / Rowland_Spacing / tg_m

                First-order nominal size for 0.012 mm:
                  HETGS/HEG: 2.78e-03 A
                       /MEG: 5.56e-03 A
                  LETGS    : 1.38e-03 A

                Bins may be specified in other diffraction
                coordinates:  energy [eV], tg_r [deg], gdp [pix], or
                linear [mm].

        Bin_size could be overspecified:
           bin_size = (max_bin - min-bin) / num_bins
           A value of 'compute' means calculate using a combination of
           the bin values entered and the default values. 

    (num_bins = compute) ['compute'|integer]

        The number of bins for the resultant spectra.  For now, the
        default values are (max_bin-min_bin)/bin_size. 

        Default:  Determined by grating type and detector.  Nominal
                configurations: 

             HETGS:  7014 (default bin_min, bin_max, bin_size)
             LETGS: 12268 (default bin_min, bin_max, bin_size)

        The number of bins is possibly overspecified. Min_bin, max_bin,
        and bin_size completely specify the number of bins.  The
        'compute' option is for for calculating the number of bins:
           num_bins = (max_bin - min_bin) / bin_size

    (tg_d_units = deg) [deg|arcsec|mm|pix]

        Tg_d bin units (for tg_d parameters below): Angstrom, eV, deg,
        pix, mm.  Specifies the units of min_tg_d, max_tg_d,
        min_bkg_tg_d and max_bkg_tg_d.

        Only degrees are currently implemented in the tool, since tg_d
        is in degrees in the input file.

        NOTE: the following is a representation of the tg_d parameters:

          -----------------------------------  (+1.0)*(|max_bkg_tg_d|) 
                                                          =~+1.0mm
            the high-side background region   
   tg_d
    ^                                           
    |      -----------------------------------  (+1.0)*(|min_bkg_tg_d|)    
     +0.1  -----------------------------------    max_tg_d
      0.0       the "source" region  (the "prime" area) +----> tg_lam
     -0.1  -----------------------------------    min_tg_d
           -----------------------------------   (-1.0)*(|min_bkg_tg_d|)


           the low-side background region

          ------------------------------------   (-1.0)*(|max_bkg_tg_d|)
                                                          =~-1.0mm
 
          The region between min_tg_d and max_tg_d is the area when
          the data spectrum is extracted.  The area between 
          (|min_bkg_tg_d| and |max_bkg_tg_d|) && (-1.0*min_bkg_tg_d 
          and -1.0*|max_bkg_tg_d|) is the background spectrum.  Note 
          that the top and bottom background sections get added together
          to create one background spectrum.

    (min_tg_d = compute) ['compute'|real number]

      Specifies the minimum tg_d range to include in the histogram.
      Units are specified by tg_d_units.
        Default:  Determined by configuration:

            HETGS: -0.1 mm, == -2.39 arcsec, == -6.64E-04 deg
            LETGS: -0.2 mm, == -4.78 arcsec, == -1.33E-03 deg

    (max_tg_d = compute) ['compute'|real number]

      Specifies the maximum tg_d range to include in the histogram.
      Units are specified by tg_d_units.
      Default:  Determined by configuration:

            HETGS: +0.1 mm, == 2.39 arcsec, == 6.64E-04 deg
            LETGS: +0.2 mm, == 4.78 arcsec, == 1.33E-03 deg

    (extract_background = no) [boolean]

        Extract the local background spectrum?  If set to yes, the
        background spectrum will be in the output file(s).  The
        parameters min_bkg_tg_d and max_bkg_tg_d are used to 
        determine the size of the background spectrum.  If set to
        NO, then the output column BACKGROUND is not present in
        the output file(s).

    (min_bkg_tg_d = compute) ['compute'|real number]

       Specifies the minimum absolute value of tg_d for a background
       region.  The default starts where the spectral region ends
       (at max(|min_tg_d| || |max_tg_d|)).
       Events with cross-dispersion from the background region will
       be binned into a background spectrum.  The units are to be
       specified by tg_d_units.
       Default: Depends on configuration:

           min_bkg_tg_d = max(|min_tg_d| || |max_tg_d|))

    (max_bkg_tg_d = compute) ['compute'|real number]

       Specifies the maximum absolute value of tg_d for a background
       region.  The default values are listed below;  however, if the
       set defaults are still within the non-background tg_d range, 
       then, the max_bkg_tg_d is set to 10 times 
       max(|min_tg_d| || |max_tg_d|).
       Events with cross-dispersion from the background region 
       will be binned into a background spectrum.  The units are to be
       specified by tg_d_units.
       Default: Depends on configuration:

           HETGS: +/-1.0 mm == +/-23.9 arcsec, == 6.64E-03 deg
           LETGS: +/-2.0 mm == +/-47.8 arcsec, == 1.33E-02 deg

    (clobber = no) [boolean]

	If set to yes, existing output files will be overwritten.

    (display = 1) [integer 0:5]

	Program verbosity.  0 means display no messages to the screen
        while running.  5 means report maximum on what the program is
	doing. 

    (mode = "ql") [string]
	
	Parameter interface mode.  "ql" stands for "query and learn",
        which prompts you for input and updates
    	"tgextract.par" with your responses.


EXAMPLES

> tgextract infile=AS_004_evt1a.fits regionfile="" outfile_type=pha2 
            outfile=AS_004_pha2.fits tg_srcid_list=1
            tg_part_list=header_value tg_order_list=1 ancrfile=none 
            respfile=none backfile="" rowid="" grating_par=grating 
            bin_units=Angstrom min_bin=compute max_bin=compute 
            bin_size=compute num_bins=compute tg_d_units=deg 
            min_tg_d=default max_tg_d=default extract_background=yes 
            min_bkg_tg_d=default max_bkg_tg_d=default  clobber=yes

  The output Type II pha file is called AS_004_pha2.fits, and can be 
  viewed by any ftools and dmtools.  Here's a small section of the 
  output file:

   EXTNAME=SPECTRUM
   ----------------

        SPEC_NUM TG_M   TG_PART TG_SRC_ID

      1      1        1      1       1
      2      2        1      2       1

        ANCRFILE

      1 none
      2 none

        RESPFILE

      1 none
      2 none

        CHANNEL COUNTS STAT_ERR        BACKGROUND BIN_LO
                counts counts          counts     Angstrom
      1      1       0   1.8660254E+00      0       6.199579855050732E-01
             2       0   1.8660254E+00      0       6.227381244564402E-01
             3       0   1.8660254E+00      0       6.255182634078071E-01
      ...
      2      1       0   1.8660254E+00      0       1.239854000000000E+00
             2       0   1.8660254E+00      0       1.245414000000000E+00
             3       0   1.8660254E+00      0       1.250974000000000E+00
      ...

        BIN_HI
        Angstrom
      1   6.227381244564402E-01
          6.255182634078071E-01
          6.282984023591741E-01
      ...
      2   1.245414000000000E+00
          1.250974000000000E+00
          1.256534000000000E+00
      ...

   EXTNAME=REGION
   --------------

        SPEC_NUM ROWID            SHAPE            TG_LAM
                                                   Angstrom
      1      1   SOURCE           box                1.031047881781376E+01
      2      1   BACKGROUND_UP    box                1.031047881781376E+01
      3      1   BACKGROUND_DOWN  box                1.031047881781376E+01
      4      2   SOURCE           box                2.061992700000000E+01
      5      2   BACKGROUND_UP    box                2.061992700000000E+01
      6      2   BACKGROUND_DOWN  box                2.061992700000000E+01

        TG_D                    R                       ROTANG
        deg                     (Angstrom , deg)        deg
      1   0.000000000000000E+00   1.938104166461738E+01   0.000000000000000E+00
                                  1.327777777777778E-03
      2   3.651388888888888E-03   1.938104166461738E+01   0.000000000000000E+00
                                  5.974999999999999E-03
      3   3.651388888888888E-03   1.938104166461738E+01   0.000000000000000E+00
                                  5.974999999999999E-03
      4   0.000000000000000E+00   3.876014600000000E+01   0.000000000000000E+00
                                  1.327777777777778E-03
      5   3.651388888888888E-03   3.876014600000000E+01   0.000000000000000E+00
                                  5.974999999999999E-03
      6   3.651388888888888E-03   3.876014600000000E+01   0.000000000000000E+00
                                  5.974999999999999E-03

        COMPONENT INCLUDE TG_SRC_ID TG_M

      1      1         1       1         1
      2      1         1       1         1
      3      1         1       1         1
      4      2         1       1         1
      5      2         1       1         1
      6      2         1       1         1



DATE

    08/10/98
    09/16/98
