Input event file (``Level 1''), which must have an extension called EVENTS. The extension must have columns called:

Name of file to write. Columns are specified by the eventdef paramter.

The input region file is appended to the output as a FITS extension.

Grating region, in sky coordinates. The region file defines the zero-order position and size, and the dispersed region sizes and orientations, in sky coordinates. The region is used to filter events for assignment of diffraction coordinates, and events are labeled by the region part they lie in. A region may be created with tg_create_mask.

The input region is copied to the output as a FITS extension.

Aspect Camera Assembly (ACA) offsets file, or Pointing Control and Aspect Determination (PCAD) aspect solution (asol) file. Either may be used. The former is derived from the latter via asp_calc_offsets. The aspect offsets file's columns specify the offset of the optical axis in sky pixels from the nominal right ascension and declination. The aspect solution file's columns contain both the optical axis location on the sky and the science instrument module (SIM) location relative to the optical axis.

If an offsets file is given, an alignment file (SIM offsets) must also be specified. If the aspect solution file (pcad or asol) is given, then the alignmentfile parameter can be redirected to use the acaofffile input.

Aspect solution files are preferred, since they have higher time resolution and remove a need for offsets files.

If more than one input file is used, then the files should be in chronological order.

Note: this parameter name is now an anachronism, since the preferred file type is the aspect solution (``*asol1.fits''). If the input is an asol file, then the alignment file parameter should be redirected to acaofffile, since the asol file contains all information necessary.

Science Instrument Module (SIM) offsets file (typically tagged with ``soff1.fits''), which contains a compressed form of the part of the aspect solution giving the position and rotation of the camera relative to the optical axis. This parameter can be redirected to use the acaofffile input (like the current default) if the aspect solution is used.

If more than one input file is used, then the files should be in chronological order.

File or 'stdout' for diagnostic text output.

This value specifies the name of the ascii text file which this tool will generate if the verbose parameter (see below) is set to a value other than 0. If the value is set to "stdout", the output will be redirected to standard output.

File used for ACIS order-sorting. This parameter is formerly called rmfile. (Only requried if the input is ACIS data.)

The calibration file which contains information derived from the CCD resolution and is used for determining diffraction orders. The file contains limits versus energy, which are typically +-3*sigma about the main peak of the CCD redistribution function. The file maps the redistribution peak and resolution with position on each CCD; ``OSIP'' stands for Order Sorting and Integrated Probability. The integrated probability contained within the energy limits is not used here, but is used in computing the time-averaged effective area (see ``mkgarf'' and ``fullgarf'').

Users can specify "CALDB" to automatically look up the file appropriate for the observation date. The header keyword "ACISDE" will contain the file name of the file actually used.

NOTE: this file is NOT the same as a CCD response matrix (RMF).

Order-sorting lower bound fraction; order > (int(order) - osort_lo). (osort_lo and osort_hi will be used for order-sorting only if the input data is ACIS and the input to the osipfile parameter is "NONE".)

This specifies fractional deviations from the integer order which will be included in order-sorting via CCD ENERGY values (PHA). eg. osort_lo=0.3, osort_hi=0.2 means that photons with real-valued orders between 0.7 < order <= 1.2 will be included in first order, 1.7 < order <= 2.2 will be second order, etc. (The real valued order is defined as the grating order*wavelength (tg_mlam) divided by the ``CCD wavelength'', (h*c)/ENERGY. )

This parameter and the next were introduced to bypass the OSIP file in cases when it is not appropriate or well calibrated (e.g., CC-mode, or in times when CCD temperature was changing).

Order-sorting upper bound fraction; order <= (int(order) + osort_hi). (osort_lo and osort_hi will be used for order-sorting only if the input data is ACIS and the input to the osipfile parameter is "NONE".)

Specifies fractional deviations from the integer order which will be included in order-sorting via CCD ENERGY values (PHA). eg. osort_lo-0.3, osort_hi=0.2 means that photons with real-valued orders between 0.7 < order <= 1.2 will be included in first order, 1.7 < order <= 2.2 will be second order, etc.

Grating in use: (HETG, HEG, MEG, LETG, header_value)

This parameter specifies the grating type so that the appropriate calibration data (such as grating period) can be read in from the calibration database. If ``header_value'' is specified, then use the GRATING keyword in the event header. If grating_obs is specified, it is compared with the header's value and a warning is printed if the two do not match.

Detector: (ACIS, HRC-S, HRC-I, header_value)

The detector on which this data was collected. This parameter specifies the instrument calibration data to be read. If header_value is specified, then use the DETNAM keyword in the event header. If an explicit detector name is specified, it is compared with the header's value and a warning is printed if they do not match. (Detector names must be all upper case.)

(NOTE: this has been superceded by osip=NONE and osort_lo, osort_hi parameters.) This should be left at 1.0, except possibly for extended sources. It is a multiplicative factor applied to the low energy limit in the spatial independent version of order-sorting table (the ``irm'' version). Altering this factor will alter the effective area fraction in an undetermined way. It is primarily here for back-compatibility with deprecated software versions.

Note: this parameter is ignored if the order-sorting file (input to the osipfile parameter) is the spatially dependent ``osip'' version.

(NOTE: this has been superceded by osip=NONE and osort_lo, osort_hi parameters.) This should be left at 1.0, except possibly for extended sources. It is a multiplicative factor applied to the high energy limit in the spatial independent version of order-sorting table (the ``irm'' version). Altering this factor will alter the effective area fraction in an undetermined way. It is primarily here for back-compatibility with deprecated software versions.

Note: this parameter is ignored if the order-sorting file (input to the osipfile parameter) is the spatially dependent ``osip'' version.

Offset to add to event time to synchronize with alignment data.

Randomization seed. If 0, then use a seed derived from the system time.

This value determines whether the seed value used for the pseudo-random number generator used in randomizing coordinate values. Setting this value to a non-zero value will allow the tool to generate the same random number sequence and thus identical results on different runs on the same system.

Pixel randomization half-width. The value can be either 0.0 or 0.5. A value of 0.0 means that no explicit coordinate randomization will be done.

Randomization may be applied to the chip pixel coordinates (CHIPX, CHIPY) before diffraction coordinates are derived. This is an anti-aliasing technique which removes moire-pattern affects due to transformation of one binned grid to another, or for removing systematic affects related to the aspect. It is usually a good idea to randomize, and it can be done without substantially degrading the resolution. It should be understood that even if rand_pix_size=0, there is an implicit randomization imposed by the dither and assumption that the photon position is at the pixel center. The implicit and unavoidable randomization is that of a boxcar convolution. Rand_pix_size other than zero is effectively an additional convolution by a triangular function.

Specify contents of the output file.

This field allows the user to specify the contents of the output file. The value may either be set to a desired list of columns and data types by the user, or a redirect to predefined event definitions. The default value of this parameter is a redirect to the output column specifications listed in the stdlev1_ACIS parameter.

The default value is:

eventdef = )stdlev1_ACIS

Other parameters defined, to which the parameter may be directed, are:

stdlev1_ACIS =
{d:time,i:expno,f:rd,s:chip,s:tdet,f:det,f:sky,s:ccd_id,l:pha,s:pi,f:ene
rgy,s:grade,s:fltgrade,s:node_id,s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:
tg_part,s:tg_smap,x:status} stdlev1_HRC =
{d:time,f:rd,s:chip,l:tdet,f:det,f:sky,s:chip_id,s:pha,s:pi,s:tg_m,f:tg_
lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}

Definition of the standard columns in an HRC or ACIS event file.

Definition of the standard columns in an ACIS event file.

Definition of the standard columns in an HRC event file.

Verbosity level: 0 - no output, 5 - maximum display.

This option allows the user to request a varying level of diagnostic output. Levels range from 0 to 5 with 0 representing no information and 5 representing the most. The log is written the value specified in the logfile parameter (see above).

If ``yes'', then an existing output file will be over-written. If ``no'', and the named outfile exists, exit with an error.